Design scope to presentation definition and request authorization API interface

[woutslakhorst]

In both the service-to-service access token request flow and OpenID4VP authorization request flow, a request with scopes needs to be mapped to the correct Presentation Definition. The responsibility for this lies outside the Nuts node. Policy Administration/Decision Points should make the decision. To aid vendor build these 'points' a standardised API contract could help.

The API should contain 2 calls:

• GET /presentation_definition?scope=X Y Z&authorizer=did:web:example.com
• POST /authorized

The did path parameter is used for tenant selection. It uses standard URLEncoding. The first API call is rerouted from a public call and must therefore not give different answers in the case of patient specific scopes.

The POST call should at least contain:

• the request URL
• most fields from the access token introspections (VPs, presentation_submission, scope, client_id, mapped input descriptor fields)
• 200 JSON return with access boolean. 403 is reserved for getting no access to the authorized endpoint.

[gerardsn]

The described contents of the POST sound like they are part of /token API in the s2s flow, and direct_post method of the OpenID4VP flow, but not part the /authorize call. The VPs and PS are the answer to /presentation_definition(=>presentation_definition_uri param in OpenID4VP authorize call) which comes after /authorize in OpenID4VP?) Or am I completely misinterpreting what this PR is for?

[reinkrul]

Missing a good term for the system implementing the API. Policy API/PAP (etc)/Policy backend?

We now have a "Presentation Exchange" store (vcr/pe/store.go#DefinitionResolver), which is a map to Presentation Definitions. Is that one going away now? Or is it one of the policy backends, which doesn't use the API?

Can you give an example of a backend implementation and how it matches the given fields?

Maybe tenant should just be a parameter, to keep things even more simple for implementations (no need to parse request URL other than the query parameters). Not all policy backends might care about the actual tenant?

[woutslakhorst]

The described contents of the POST sound like they are part of /token API in the s2s flow, and direct_post method of the OpenID4VP flow, but not part the /authorize call. The VPs and PS are the answer to /presentation_definition(=>presentation_definition_uri param in OpenID4VP authorize call) which comes after /authorize in OpenID4VP?) Or am I completely misinterpreting what this PR is for?

yes, would it change your mind if the endpoint was callend /check or /validate?

[woutslakhorst]

Missing a good term for the system implementing the API. Policy API/PAP (etc)/Policy backend?

We now have a "Presentation Exchange" store (vcr/pe/store.go#DefinitionResolver), which is a map to Presentation Definitions. Is that one going away now? Or is it one of the policy backends, which doesn't use the API?

Can you give an example of a backend implementation and how it matches the given fields?

Maybe tenant should just be a parameter, to keep things even more simple for implementations (no need to parse request URL other than the query parameters). Not all policy backends might care about the actual tenant?

The PEX store is indeed a 'catch-all' policy backend. Tenant is indeed also one of the introspection fields (iss) so the data is available.

An example: Patient agreed to share medication data to GPs. This consent is stored locally at the source. When the request comes in for /fhir/observation/5 the policy backend must decide on a yes or no. First: Is there consent for the triple (actor, custodian, patient). Patient agreed to share data with GPs so actor isn't needed. But the actor did submit an UZI credential with number and role code. So the custodian has to check (role, custodian, patient). Patient is not known from the request or via VCs. The backend must map the request URL to the patient ID. (local fhir query for the resource, extract patientID). Finally the backend has to query a DB to find the record listing: (GP, custodian, patientID)

PS: the backend also has to decide if observation with ID 5 falls under medication data.

[gerardsn]

The described contents of the POST sound like they are part of /token API in the s2s flow, and direct_post method of the OpenID4VP flow, but not part the /authorize call. The VPs and PS are the answer to /presentation_definition(=>presentation_definition_uri param in OpenID4VP authorize call) which comes after /authorize in OpenID4VP?) Or am I completely misinterpreting what this PR is for?

yes, would it change your mind if the endpoint was callend /check or /validate?

I missed that this was about the Policy Backend and not the node. I guess /authorize is fine but a different name might cause less confusion in conversations? Depending on the response it could also be /allowed or /permitted or even /authorized since this not an authorization request but confirming the authorization already exists?

[woutslakhorst]

changed endpoint names and replaced path params with query params