openid / authzen Goto Github PK

Discussed in #23

if we consider a case where PDP and PEP are from different vendors, do we want to include anything for discovery/meta-data about the PDP?

IP addresses belong to the network layer and may not be available to the PEP or may not affect many AuthZ decision requests.
If the subject is identified through its IP address, then it should be the subjects "id" attribute.

Also, IPv6 addressing schemes can be rather complex and error-prone, due to multiple variations in syntax:
eg. those are different variants of THE SAME ip address:

- fe80::AbCD:3:2:0001
- Fe80:0:0:0:abcd:0003:0002:0001
- Fe80:0:0:0:abcd:0003:0002:0001%eth1

Its horrid to implement a unification/syntax check on PDPs/PEP side.

recommendation:

• remove the "ipAddress" attribute until further specified.
• or define a dedicated structure with optional, freely defined attributes where an "ipAddress" can be defined as a custom attribute without further specification.

A field, whose value is of type string, which uniquely identifies the user.

What's the scope of uniqueness? Just from the caller's perspective or from the PDP's?

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L189

The asset about which this query relates ?

Discussed in #27

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L217

@goosetav @tulshi - we've spoken a little about returning a reason field that is optional and a configurable string.

e.g. https://docs.google.com/document/d/1eIxqlaFfomdzLgjIz0HD-lhpp9oDFyWwas5c80aM2QQ/edit#heading=h.nzdq06pglbza

Is this something we'd want to mention in the spec - I can see it being contentious and possibly slowing something down, but, I expect a conversation on that might be valuable. WDYT?

"Common Actions" currently defines 4 CRUD and one generice "access" action.

are those normative and mandatory for PDP/PEP spec compliance?
How should a PDP response, in cases a common action is not implemented or does not make sense for a Subject/Resource combination or policy?

The operation in section "Resource Query" is currently defined as

An Resource Query is a question about whether a subject can access a specific resource.

Using action and resource parameters as input, but there is no reference to the subject in the input and the supposed output is undefined.
The generic use case sounds like "give me all the resources (of some type) a specific user has access to".

Proposal:
Define this query as "Resource Lookup Query" to query for all resources a given subject type can perform a given action.
The resource-parameter should require either require no or certain criteria for the PDP to limit the space of resources (like "resource type" or additional attributes that describe a number of resources).

Proposed wording:

## Resource Query {#resource-query}

Perform a lookup of all resources of a particular kind on which the subject has the specified permission or the relation in which the subject exists.
It is a JSON object with the following fields:
.....

Ref "Subjects" contains definition for subject entity with a mandatory "id" attribute.
There is no definition of a subject type - contrary to "resource", which has a mandatory type.

In practice, an entity (object) may be referenced in both roles, sometimes as a subject, sometimes as a resource - depending on the context.
recommendation: describe "subject" and "resource" the same with both mandatory "id" and "type" attributes.

Change:
A Subject is a JSON ({{RFC8259}}) object that has the following fields:

id: : OPTIONAL. A field, whose value is of type string, which uniquely identifies the user within the scope of a PEP. This identifier could be an email address, or it might be an internal identifier such as a UUID or employee ID.

type: : OPTIONAL. The type of the subject. Its value is a string that specifies the type of the subject

this should likely be optional from the PEP -- the PDP should just reflect back the identifier that is provided (or generate a new one) -- we'll want to avoid having to enforce uniqueness, etc...

In the spec the error status reponses are specified:

401 | Unauthorized | An error message string
403 | Forbidden | An error message string

Suggest clarifying that

HTTP Status responses are always in regards to the use of the PDP decision API and are unrelated to the decision outcomes.
A status 401 from the PDP itself means the HTTP client (usually a PEP) is not authorized to call the PDP (e.g. because no
authorization header was provided or was invalid). Likewise, an HTTP Status 403 being returned by a PEP to its client would
normally be based on a status 200 response from the PDP containing a "deny" decision.

An array of strings -- how to handle if the assets are complex or nested?

I have seen machine identities used to mean all non-human entities (including devices and workloads). Still not perfect, but perhaps better than robotic?

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L83

Method in this context feels either slightly overloaded or too vague? Should we qualify it with an adjective or replace that word entirely?

: The operation the Principal has attempted on the Asset in an Authorization API request.

same questions as for principle identifier -- are these uniquely identifying and within what scope? (PDP or PEP) -- I think scoped to PEP.

https://github.com/SGNL-ai/authzapi/blob/5937da2ca3a3ed189bb066ce2f75c9bd5e0a380d/authorization-api-1_0.md?plain=1#L319

This feels like it will be error prone in implementation. I onder if we can avoid that risk by prohibiting overlapping scopes?

Discussed in #26

let's specific these are always an array even if there's only one response

PDP may want to keep a stateful session between the PEP and PDP.
Rationale: you could provide further input that would be used for the PDP to make a decision; the PDP provide guidance and the PEP adds additional information in a subsequent request.

See - inference engines and stateful sessions (here it would mean that we keep the working memory between executions, calls between the PEP and PDP). If this is desired, session id would need to be provided.

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L132

How should I rationalize this with an intentional decision we've made in SGNL to make assets optional (and thus the Id field) for some fairly valid use-cases?

This merge seems to have broken the automatic building of the GitHub pages: https://github.com/openid/authzen/actions/runs/7891433299

A PDP may involve third party components into policy evaluation as a sub-query, i.e. a Policy Information Point (PIP) which holds additional information about the resource/subjects relationships or other metadata required for the policy.

If one of those sub-queries fail (e.g. because the PIP is down or the query could not be processed correctly), the PDP should communicate this situation to the PEP.

there should be a response scheme by the PDP for the PEP, where the PDP differenciates between "yes, I have understood your decision request and here is your response for enforcement" and "I have trouble to decide on your request, so my response would be neither a 'yes' or 'no'"

Proposal wording for discussion:

If successful, the PDP returns a `200 OK` response code and an evaluation result document in the response body.
A successful response **always** contains the following elements:

* status: indicates whether the request was processed without errors and contains a valid authorization decision, OR if there were any errors. Possible values:
    * "success": authorization request successfully evaluated, no errors.
    * "error": Some errors occurred during the evaluation or the input parameters were faulty. In this case, an element "error" is included.
* allow: <true/false> gives the PDPs policy decision. ```true``` indicates "permission granted", ```false``` indicates "permission denied".

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L282C8-L282C8

The Access Evaluations API is a means

Should the access decision be signed by the PDP private key to ensure that the payload has not been tampered with?

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L156

In SGNL, we allow action fields with a null value (as well as no action field) - should this be incorporated into this document? I honestly don't know if it's valuable, but we certainly hit a need for it with customers.

https://github.com/SGNL-ai/authzapi/blob/4946793ec6db3337f2e3f35099fa38ad8049a1dd/authorization-api-1_0.md?plain=1#L57C38-L57C38

let's also define the PEP and PDP a bit more precisely in this section

The proposed Subject and Resource Search API return arrays of responses.
-- [A] One proposal is to return a "decision" attribute ("allow" or "deny") along with each response.
-- [B] Another is to return only "allow" responses, and assume everything not returned is denied.

[B] has advantages: it keeps the responses smaller in size, and makes it also easier/faster to compute the response.

If returning denied object is deemed necessary, then I would argue for adding 2 extra APIs: Search-Denied-Resources and Search-Denied-Subjects, smthg like that...

Discussed in #22

https://github.com/SGNL-ai/authzapi/blob/5937da2ca3a3ed189bb066ce2f75c9bd5e0a380d/authorization-api-1_0.md?plain=1#L103C12-L103C12

The header inidcates that this is about Authorization but then proceeds to reference authentication. Perhaps alternative wording can avoid this (e.g. "API calls SHALL be authorized with OAuth 2.0 access tokens. Implementors MAY use bearer tokens or sender constrained tokens, depending on the organizations policy".)

https://github.com/SGNL-ai/authzapi/blob/5937da2ca3a3ed189bb066ce2f75c9bd5e0a380d/authorization-api-1_0.md?plain=1#L177C1-L177C1

It would be good to include details of how the extensibility might work.

https://github.com/SGNL-ai/authzapi/blob/a7daf1c837bc074d499e5fd9e266ef42e4f9cb94/authorization-api-1_0.md?plain=1#L289

Should we state that both principal and queries fields are required? And similarly in the Search API below that states just one?

The draft currently defines a Resource Query API to lookup whether a subject can access a specific resource.

There should also be a complementary query to lookup which subjects have access a given resource.
Like "which users (subjects) can read the document 'xyz'?"
(whereas 'user' is a subject of type 'user' and "document 'xyz'" is a resource of type "document" and id 'xyz')

Proposed wording

## Subject Lookup Query

Perform a lookup of all subjects of a particular kind which have permissions to a certain resource. This is the complementary operation of 'Resource Lookup Query'.
Lookup subjects can be used in form of a question like "which subjects of type '_user_' have '_read_' permission on the object of 'document' and 'xyz'?"

mandatory input parameters should be

• resource definition (resource type or other criteria)
• permission (or relation?)
• subject criteria (type definition like "user" or "devices" or whichever type a subject may have)

Resource Query currently defines a lookup action on resources.

For clarification, "Resource Query" should be renamed to "Resource Lookup Query".

Other actions (like "update" or "delete") may be subject to further definition?

The "subject" has a definition for "deviceId":

deviceId: : OPTIONAL. A field, whose value is of type string, which uniquely identifies the device of the Subject

What exactly is „a device“, its syntax and intended use in the context of a policy?

recommendation:

• remove the "deviceId" attribute until further specified.
• or define a dedicated structure with optional, freely defined attributes where an "deviceId" can be defined as a custom attribute without further specification.

https://github.com/SGNL-ai/authzapi/blob/4946793ec6db3337f2e3f35099fa38ad8049a1dd/authorization-api-1_0.md?plain=1#L480

In Zanzibar-style implementations, you'd want to use the Search API to "List all of the documents that a user can view". For that scenario you'd want to also specify the asset type (e.g. "documents"), and it's not useful to return all the resources that can't be accessed. There might be a lot of them which are not relevant if you want to provide to the user a list of resources they can access.