Server-side RFC 7523 JWT Bearer grant with two VPs (PSA 10.10)

Related: #4078, #4079, #3965, #4038

Depends on:

• #4078 (client-side JWT bearer, shared client wallet owner type in policy config)
• #4079 (generic did:x509 credential validation — hard dependency)
• #4038 (scope model and AuthZen callback)

Problem Statement

The Nuts node, acting as an authorization server, currently only accepts the vp_token-bearer grant type with a single VP. The LSPxNuts PSA section 10.10 OAuth profile requires the AS to also accept the RFC 7523 jwt-bearer grant type (PSA 10.10.1) where the token request contains two VPs (PSA 10.10.6): VP1 (assertion) with the healthcare provider's credentials as authorization grant, and VP2 (client_assertion) with the service provider's credentials as client authentication. The AS must validate both VPs according to a defined processing order (PSA 10.10.6) and return detailed error codes on failure (PSA 10.10.10).

Solution

Extend the server-side token request handling to accept the jwt-bearer grant type with two VPs. The AS validates VP2 (client assertion) against the client PD and VP1 (authorization grant) against the organization PD, using PEX-based matching. Generic credential validation (crypto, signatures, expiration, did:x509 cert chain/CRL via #4079) is performed by the node; business rule validation can optionally be delegated to an AuthZen callback (see #4038). The AS advertises jwt-bearer support in its metadata (PSA 10.10.4) when a client PD is configured. New error codes (PSA 10.10.10) provide detailed feedback on validation failures.

User Stories

1. As a Nuts node operator acting as AS, I want to accept token requests using the RFC 7523 JWT bearer grant type, so that I can serve clients using the GF OAuth profile.
2. As a Nuts node operator, I want the AS to validate both the client assertion (VP2) and the authorization grant (VP1) against their respective PDs, so that only properly authenticated requests receive tokens.
3. As a Nuts node operator, I want the AS to continue accepting the existing vp_token-bearer grant type, so that backward compatibility is maintained.
4. As a Nuts node operator, I want the AS metadata to advertise jwt-bearer support when a client PD is configured, so that clients know which grant types are available.
5. As a client developer, I want descriptive error codes in token error responses that distinguish VP1 issues from VP2 issues, so that I can diagnose authentication failures.
6. As a Nuts node operator, I want the introspection response to include information from both VPs keyed by wallet owner type, so that the resource server has the full context for authorization decisions (PSA 10.10.9).
7. As a use-case designer, I want to define separate credential requirements for the client (SP) and the authorization grant (HCP) via the policy configuration, so that each party's required credentials are independently specified.
8. As a Nuts node operator, I want the token response to include the granted scopes (PSA 10.10.7), so that clients can adjust behavior based on what was authorized.
9. As a Nuts node operator, I want existing credential validation behavior to be preserved for current use cases, so that nothing breaks.

Implementation Decisions

Grant type handling

The token endpoint handler is extended to accept urn:ietf:params:oauth:grant-type:jwt-bearer alongside the existing vp_token-bearer. The grant type determines the validation flow:

• vp_token-bearer: single VP in assertion (existing flow, unchanged)
• jwt-bearer: VP1 in assertion + VP2 in client_assertion, client_assertion_type must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer

Two-VP validation flow (PSA 10.10.6)

Processing order:

1. Parse scope string and identify the credential profile scope (needed to look up the client and organization PDs)
2. Parse and validate VP2 from client_assertion — VP signature, credential signatures, expiration, revocation, audience. Match VP2 against the client PD
3. Parse and validate VP1 from assertion — VP signature, credential signatures, expiration, revocation, audience. Match VP1 against the organization PD
4. Apply scope policy to determine granted scopes (see #4038)
5. Optionally call AuthZen callback for business rule validation (if configured, see #4038)
6. Store VP/claim data internally and issue an opaque access token

VP validation includes replay prevention via jti tracking and exp / aud checks as specified in PSA 10.10.6.

Credential validation for did:x509-issued credentials (cert chain, CRL, issuer attribute matching) is handled by the generic did:x509 validation layer (#4079), which applies to all credential types automatically through VerifyVP.

Custom error codes (PSA 10.10.10)

New OAuth2 error codes for detailed failure reporting:

Error code	Description
invalid_presentation	VP is invalid (signature, structure, audience)
invalid_credential	A credential in the VP is invalid (expired, revoked, untrusted issuer)
missing_credential	A credential required by the PD is missing from the VP
insufficient_scope	The requested scope doesn't fit within the credential authorities
invalid_delegation	The delegation relationship between SP and HCP is invalid or missing

The error_description field provides a human-readable explanation. Per the spec, error responses must not leak details about internal authorization logic or credential contents of the data custodian (PSA 10.10.10).

These error codes also improve error reporting for the existing vp_token-bearer flow.

AS metadata (PSA 10.10.4)

When a client PD is configured for at least one credential profile, the AS metadata includes:

• grant_types_supported: adds urn:ietf:params:oauth:grant-type:jwt-bearer
• token_endpoint_auth_methods_supported: adds private_key_jwt

Introspection (PSA 10.10.9)

The access token is opaque — VP and claim data is stored internally in the node and retrieved via introspection.

The introspection response already structures data by wallet owner type via PresentationDefinitions (keyed by WalletOwnerType). Adding client as a new wallet owner type integrates naturally:

• PresentationDefinitions gains a client entry with the PD used to validate VP2
• PresentationSubmissions gains an entry for the VP2 submission
• VPToken array includes both VP1 and VP2
• InputDescriptorConstraintIdMap includes values extracted from both VPs

Existing introspection behavior for vp_token-bearer requests is unchanged — the client wallet owner type is only present when the jwt-bearer flow was used. This is an additive change that does not affect backward compatibility.

Token response (PSA 10.10.7)

The token response includes:

• access_token: opaque token
• token_type: DPoP
• expires_in: token lifetime in seconds
• scope: the granted scopes (credential profile scope + authorized resource scopes per #4038)

Presentation definition endpoint

The existing presentation definition endpoint supports the client wallet owner type, allowing remote clients to fetch the SP credential requirements for a given scope.

Modules to build/modify

1. JWT bearer token handler (new): handles the jwt-bearer grant type in the token endpoint. Parses and validates both VPs, matches against PDs via PEX, stores VP data and issues opaque access token. Parallel to the existing vp_token-bearer handler.
2. Error codes (modify): add new OAuth2 error codes. Apply them to both jwt-bearer and vp_token-bearer flows.
3. Introspection (modify): include VP2 data under the client wallet owner type in the introspection response.
4. AS metadata (modify): advertise jwt-bearer and private_key_jwt when client PD is configured.
5. Presentation definition endpoint (modify): support client wallet owner type parameter.

Testing Decisions

A good test verifies that given a token request with specific VPs and scopes, the correct access token is issued (or the correct error is returned) and the introspection response contains the expected data.

Modules to test:

• JWT bearer handler: unit tests for successful two-VP flow, VP1 failure, VP2 failure, missing client_assertion, wrong client_assertion_type, PD mismatch for each VP, replay prevention (jti)
• Error codes: verify correct error codes for each failure scenario (invalid VP, expired credential, missing credential, bad scope, bad delegation)
• Introspection: verify VP1 data under organization, VP2 data under client, backward compatibility (no client entry for vp_token-bearer requests)
• AS metadata: verify jwt-bearer is advertised when client PD exists, and not when it doesn't
• Backward compatibility: verify vp_token-bearer flow is unchanged
• Prior art: existing tests in auth/api/iam/s2s_vptoken_test.go, auth/api/iam/metadata_test.go

Out of Scope

• Client-side JWT bearer support (covered in #4078)
• Delegation verification via AS metadata — delegation_presentation and provider_presentation (PSA 10.10.5)
• DPoP changes (already implemented)
• URA-based token endpoint addressing (PSA 10.10.3)
• VC-type-specific validation logic in the jwt-bearer handler (handled generically via #4079)
• DSL or configurable rule engine for credential validation
• client_assertion presentation submission (VP2 is validated against the local client PD, not via a submission from the client)

Further Notes

• The invalid_delegation error code is defined per PSA 10.10.10 for future use when delegation verification is implemented. For now it may not be triggered by generic validation alone, but could be triggered by an AuthZen callback.
• The presentation definition endpoint supporting client wallet owner type enables a future pattern where the AS advertises its SP credential requirements to remote clients.
• Pastype validation (e.g., requiring pastype S for server certificates, Z for zorgverlenerspas) is handled via PD constraints on the $.issuer field using regex patterns — no code changes needed. See #4079 for details.

Start with the existing token flow and tests in auth/api/iam/s2s_vptoken_test.go and auth/api/iam/metadata_test.go. Trace the token endpoint, introspection, metadata, and presentation-definition handling before implementing the two-VP jwt-bearer flow. Done means both VPs are validated in order, errors and granted scopes are returned correctly, introspection contains organization and client data, metadata is conditional, and vp_token-bearer remains compatible.