Idea: decouple required credentials from OAuth2 scope

[reinkrul]

In Nuts v5/spec v1, the OAuth2 scope is specified by the use case. The client requests whatever scope it wants, and the server honors it. It is then verified by EHR business logic (why, actually? and is this really the case?).

In Nuts v6/spec v2, the requested OAuth2 scope is mapped to a set of credentials that need to be presented. An access token is only issued when the client's presentation fulfills that requirement. During data exchange, the EHR business logic checks that the access token contains the expected scope.

However, this last approach (v6) causes multiple issues:

• Only 1 scope is supported
• Scopes must be static (imposible to SMART on FHIR-style scopes)

We could solve this by dropping the relation credential-OAuth2 scope in Nuts v6, by moving identity/claim verification (as specified by use case/policy) from access token-request-time to access-token-usage-time:

Access token request

• we create 1 access policy (specifies which credentials to present/require for access token request)
  • It includes all defined credential types (e.g. X509Credential, HealthcareProviderRoleTypeCredential, DeziIDTokenCredential)
  • Could be extended by vendors if they use non-normative credentials/claims
• Only organization credential is required, rest optional
  • The requester presents whatever identity claims it has, as credentials;
    • care provider (org)
    • care provider (org) role type
    • care giver (person); if applicable (provided by EHR)
    • inschrijftoken/mandaattoken etc; if applicable (might be provided by EHR?)
  • The holder verifies whatever was presented, requiring at least care provider identity, then issues access token

Access token usage/data exchange

• The holder evaluates all supported authZ policies (eOverdracht, HA-inzage, ANW, BgZ, MO);
  • If any policy gives access, the request is allowed. If none do, the request is denied.
  • Policies only give access if the required identities/claims are present in the access token (introspection response)

[stevenvegt]

Decision: credential profile scope alongside SMART scopes

After discussion, we're not going with the "present all VCs, evaluate at usage time" approach from this issue. The credential selection should remain intentional and tied to a defined use-case credential profile.

The core insight is that we are an authentication server, not an authorization server. Our token issuance verifies identity via credentials; it does not make access control decisions about specific FHIR resources (or other scopes). This distinction matters when integrating with systems like SMART on FHIR, where fine-grained scopes (e.g. patient/Observation.read) imply that the authorization decision is already made at token issuance.

Approach: add a credential-profile scope (inspired by OpenID4VP 5.5) alongside SMART on FHIR scopes:

scope=medication-overview patient/Observation.read patient/MedicationRequest.read

medication-overview signals the correct VC profile selection and VP validation. The SMART scopes are passed through into the access token without the AS evaluating them.

Limitation: the resulting AT means "requester authenticated with the correct credentials," not "requester is authorized for these SMART scopes." This token is only valid when used with a correctly configured PDP that performs the authorization decision at request time. A standard SMART on FHIR RS trusting scopes as completed authorization would over-trust this token.

Alternatives considered and rejected:

1. Full decoupling as proposed in this issue — present all available VCs, single access policy, evaluate at usage time. Rejected: credential selection should remain explicit and profile-driven.
2. Resolve required credentials via PDP policies at token request time — match SMART scopes to policies to determine required VCs. Mixes concerns; partial version of full decoupling.
3. Keep single use-case scopes, ask POC partners to map internally to SMART scopes partners would need to hardcode maximum allowed SMART scopes per use-case. Not scalable outside of POCs, does not really solve the problem.

[reinkrul]

• Authorization Server only needs to grant scopes it actually supports (no need to error out on unknown scopes)
• PDP only executes (and thus, gives access based on) the scopes it supports.

This means;

• If a client (e.g. AORTA-GTK) requests medicatieoverdracht + SMART in FHIR scopes, the Nuts authz server only checks whatever scope it recognizes and validates the credentials according to that credential profile (could also be e.g. BGZ as additional scope). The created token only includes the recognised scopes, others are discarded. We return the scopes in the token response, to inform the client which scopes were granted.
• During policy evaluation, the PDP evaluates any policy it recognizes (in the case above, only medicatieoverdracht).

This solution fulfills the following requirements (that we currently have, whether they make sense or not), that we:

• want to validate scopes during access token request
• want to evaluate specific policies for authZ, not "any that we have"

By allowing scopes that aren't used in authN or authZ evaluation, we can cross the gap between specifications that treat scopes differently.

[stevenvegt]

We return the scopes in the token response, to inform the client which scopes were granted

Should we assume the granted scopes have meaning for the client? If we are going to rewrite scopes to internal one's this would not work. Is it common practice the client act on the granted scopes? If so, the rewrite might not work or is limited to a widely accepted list.

[reinkrul]

Why would we want to rewrite scopes?