Introduction
Client Authentication is generally covered in the upstream standards, OAuth, OIDC and FAPI.
The Consumer Data Standards specify requirements specific to the CDR, including required endpoints and claims.
See CDS Security profile.
The DSB recommends referring to these resources.
Below are notes on these issues, arising from participant questions.
Authentication with JWT
The DH authenticates a Customer as part of an authorisation process initiated by an ADR, and issues an authorisation for that ADR to access the Customer's data via published APIs. The DH must maintain an Authorisation end point for this purpose.
When DHs call ADR APIs, the DH authenticates itself with a signed JWT.
When ADRs call DH APIs, the ADR authenticates itself with a signed JWT.
JWT usage for Client Authentication and Dynamic Client Registration
The SSA generated by the CDR register will have an iss (issuer) claim set as cdr-register. The create registration flow documented in the CDR Register Design Reference provides a breakdown of the various JWKS URIs and when they are used to verify both the SSA and the registration JWT signatures.
Both the SSA and DCR JWTs require validation. The JWKS URI defined in the SSA belongs to the software product. Therefore, this is not a known set of values and is published and maintained by the Accredited Data Recipient (ADR). It is a requirement to retrieve these keys to validate the JWT request.
For the purposes of internal testing It is recommended that participants generate their own JWTs to cover the different variations that they may encounter. Numerous libraries can be found at JWT.IO that can be leveraged for this purpose.
There are non-normative examples provided in the CDR Register for reference. These are not designed to be used in testing, instead they can be used in conjunction with JWT.IO to understand the composition of the JWTs.
A mock register is also provided which participants can interrogate the code on: https://github.com/ConsumerDataRight/mock-register
OAuth, OIDC and FAPI
Request Object nbf and exp claims
ADR Software Products MUST send a request object containing a "nbf" (not before) claim and an "exp" (expires) claim that has a lifetime of no longer than 60 minutes after the "nbf" claim.
Refresh token
You can determine the expiry date and time of the refresh token by calling the token introspection endpoint to obtain the "exp" value of the refresh token.
See:
nbf claim
ADRs have been required to include the value for “nbf” in their Request Object since July 4, 2022.
From September 16, 2022, DHs can validate and may reject requests from ADRs that do not provide valid values for "nbf" and "exp" in the Request Object.
The DH must validate the nbf claim in accordance with RFC7523 and RFC7519.
x-fapi headers and unauthenticated calls
The presence of the x-fapi-customer-ip-address
header indicates that the consumer is logged into the ADR application and is present when the call is made.
Use of the x-fapi-customer-ip-address
and other x-fapi
headers does not apply to public APIs, because they are unauthenticated and the FAPI security profile is not required. If the ADR software product makes an unauthenticated call with x-fapi
headers, it should be ignored, not rejected.
Future Dated Obligations - Self-signed JWT Client Authentication
The CDS Future dated obligations for July 2022 that mention changes to Self-Signed JWT Client Authentication, affect only the ADR-hosted endpoints. There are no changes to the Self-Signed JWT Client Authentication mechanism when the Register calls the DH endpoint.
JWKs URI in the Data Holder enrolment form and the CDR Register
The rationale for the Data Holder (DH) in providing JWKs URI in the enrolment form and for the DCR register (ie a separate endpoint configuration) is so that outbound calls to the ADR can access different platform resources than the identity provider hosted by the DH. This configuration provides the flexibility to keep these systems separate if required.
Accredited Data Recipients without a Software Product
There is no impact on the Dynamic Client Registration (DCR) of the ADRs. Nothing change in the requests and responses from ADRs to DHs. It is only the calls from the DH to the CDR Register that are affected.
Error responses for unauthorised scopes during Client Authentication
For Client Authentication where the authorised scopes do not permit the client calling a particular endpoint due to insufficient permissions, a 403 forbidden error response is permissible. However, if the error behaviour is described by the upstream normative standard, then that standard takes precedence over the CDS.
Client authentication and client_id
The requirements, for passing and validating the client_id or other required parameters defined in the Private Key JWT client authentication section, apply to any CDS endpoints that require Private Key JWT client authentication.
The client_id is the value the DH issues to the confidential client (ADR software product) as part of Dynamic Client Registration (DCR). The subject in this instance is the confidential client.
The client_id should be validated against the subject claim value in the client-assertion and rejected if the client_id in the request is different to the subject claim in the client-assertion.
Authorization header during ADR revocation endpoint call
The revocation call from the DH to the ADR requires client authentication. The client assertion is sent in the body of the POST request.
The JWT is signed using the DH's private key.
The ADR can decrypt and validate the JWT by using the DH's public key, obtained by calling the DH's JWKS endpoint.
Customer context for bulk data APIs
For all authenticated APIs including bulk data APIs, the response has the context of the consumer that authenticated with the Data Holder (DH).
The customer context is provided by way of the Access Token that the Accredited Data Recipient ADR sends to the DH in the Authorisation header.
JWKS Key Selection
The latest FAPI specification provides guidance regarding appropriate key selection based on the JWK set returned via the OAuth client's JWKS endpoint.
Query string requirements of the authorise endpoint for Authorisation Code Flow with PAR
-
client_id
- Required as a query string parameter according to FAPI 5.2.3(16).
-
response_type
-
Not required as a query string parameter when using PAR, according to:
- FAPI 5.2.2(2.2) and RFC6749 3.1.1 only stating that the authorisation server requires, or shall be informed of the response_type (which is taken to mean could be via PAR).
- FAPI 5.2.3(9) which states "send duplicates" ... "if not using PAR".
- The Introductory Example in RFC9126 shows the response_type field moving from a "conventional OAuth 2.0" parameter at the authorize endpoint to a field in a POST to the /as/par endpoint, and it is then not included in the query string in the last /authorize?client_id=CLIENT1234 example (which aligns to the Non-normative example in the Standards. See "Authorise - FAPI 1.0 Final Phase 3 Obligation").
- The following OpenID FAPI1 certification test including the following summary:
"This test makes a PAR request and calls the authorization endpoint passing only the client_id and request_uri parameters - which must succeed, as per section 5 of https://datatracker.ietf.org/doc/html/rfc9101 - this intent was confirmed by the FAPI working group in https://bitbucket.org/openid/fapi/issues/315/par-certification-question-must-servers"
-
Not required as a query string parameter when using PAR, according to:
-
scope
- Not required as a query string parameter when using PAR, according to FAPI 5.2.3(9).
- This is only required for hybrid flow authorization attempts as per FAPI 5.2.3.1.
-
redirect_uri
- Not required as a query string parameter according to RFC6749 4.1.1.
Comments
2 comments
This guidance is inaccurate. FAPI 1.0 conformance suite validates that an authorisation server accepts requests lodged with PAR with parameters duplicated AND without. This has been discussed a few times in FAPI working group:
It appears the DSB has read the specifications incorrectly here. The RP MAY send these parameters and it MUST NOT be rejected, the authorisation server cannot require the parameters to be sent.
Further the JAR spec (which would be the authoritative spec here) specifies clients MAY send: https://www.rfc-editor.org/rfc/rfc9101.html#section-5-9
The requirement of these parameters is a backward compatibility component only, it adds no security benefit and is not intended to be the path forward.
Please sign in to leave a comment.