Update SSA and Client Registration standards for JARM and Authorization Code Flow

[CDR-API-Stream]

Description

To support Phase 3 FAPI 1.0 migration, update the DCR APIs to specify JARM and Authorization Code Flow support.

Area Affected

Dynamic Client Registration APIs
response_types enumeration

Change Proposed

• Add "code" to the valid response_types enumeration values in the "Registration Request using JWT"
• Update DCR Registration Request JWT to support JARM:
  • authorization_signed_response_alg
  • authorization_encrypted_response_alg
  • authorization_encrypted_response_enc

DSB Proposed Solution

The DSB proposed solution is presented here.

[CDR-API-Stream]

See #458 and comment for further information.

[CDR-API-Stream]

This issue was discussed in the last MI call. The DSB Proposed Solution has been updated as follows:

1. Add "code" to the valid response_types enumeration values in the "Registration Request using JWT"

Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. Permitted values: [code, code id_token] representing Authorization Code Flow and OpenID Connect Hybrid Flow respectively.

2. Add the following claims to the RegistrationProperties for Dynamic Client Registration APIs (PUT and POST for requests, and the GET response):

Claim	Required	Description
authorization_signed_response_alg	Conditional	The signing algorithm to use for JWT Secured Authorization Response Mode (JARM). Required when JARM is used for Authorization Code Flow: where response_type value code in conjunction with the response_mode value jwt (or variant) is used.
authorization_encrypted_response_alg	Conditional	The JWE alg algorithm to use for encrypting authorization responses in JWT Secured Authorization Response Mode (JARM). Required if authorization_encrypted_response_enc is provided.
authorization_encrypted_response_enc	Conditional	The JWE enc algorithm to use for encrypting authorization responses in JWT Secured Authorization Response Mode (JARM). When authorization_encrypted_response_enc is included, authorization_encrypted_response_alg MUST also be provided. Required if the Data Holder specifies response encryption algorithms in accordance with JARM. If both signing and encryption are requested, the response will be signed then encrypted, with the result being a Nested JWT, as defined in JWT [RFC7519]. The default, if omitted, is that no encryption is performed.

3. Update the "OpenID Provider Configuration End Point" section in accordance with Clarification on Minimum Algorithm Required for JARM #479 such that the following parameters are included:

• authorization_signing_alg_values_supported: CONDITIONAL. The list of JWS algorithms for signing the authorization response in accordance with [JARM]. Required when supporting Authorization Code Flow and [JARM].
• authorization_encryption_alg_values_supported: OPTIONAL. The list of JWE alg algorithms for encrypting the authorization response in accordance with [JARM]. Required if authorization_encrypted_response_enc algorithms are offered.
• authorization_encryption_enc_values_supported: OPTIONAL. The list of JWE enc algorithms for signing the authorization response in accordance with [JARM]. The default, if omitted, is that no encryption is performed.

4. The changes would have an obligation date of April 7th 2023 in alignment with the FAPI 1.0 Phase 3 migration obligation date.

[CDR-API-Stream]

The Data Standard's Chair has approved this issue be treated as urgent in combination with #479.

[markverstege]

Last maintenance iteration call we discussed defining the error scenarios for registration and negotiation when using JARM for the Authorization Code Flow. The following scenarios are presented below with proposed behaviour. If there are any other error scenarios that need to be considered, please propose them in the comments.

It's worth providing some context and a set of solution design questions that will help frame the responses to each scenario.

Context

OIDC Hybrid Flow

This flow uses response_type "code id_token" and requires the use of the ID Token as a detached signature. As such, id_token_encryption_alg_values_supported and id_token_encryption_enc_values_supported are required to be published in the Data Holder's OIDD.

Data Holders may continue to support OIDC Hybrid Flow after the 7th of April 2023. If they do so, they need to continue supporting these negotiation parameters and ID Token signing and encryption.

Authorization Code Flow

This flow uses response_type "code" and in accordance with FAPI 1.0 Advanced, requires the use of JARM for message signing. A such, authorization_signing_alg_values_supported must be used and the Data Holder may support response encryption using authorization_encryption_alg_values_supported and authorization_encryption_enc_values_supported.

The algorithmic requirements are consulted on in Issue 547: Clarification on Minimum Algorithm Required for JARM.

Data Holders must support this flow no later than the 7th of April 2023.

Solution Questions

1. The JARM spec is ambigious when the client omits the authorization_encrypted_response_alg client metadata value. The JARM specification states that "The default, if omitted, is that no encryption is performed". Should Data Holders support no response encryption when this value is omitted, even if the Data Holder supports encryption and offers "RSA-OAEP" and/or "RSA-OAEP-256"? The quoted statement in the JARM spec could be interpreted as:

   • Option 1a: Always allow a "no response encryption" option for the client
   • Option 1b: If the Data Holder advertises one or more "alg" algorithms, the client MUST use one of the valid algorithms (that is, "no response encrytpion"). The Data Holder will return an error response if the authorization_encrypted_response_alg is omitted when the Data Holder advertises "alg" algorithm support.

2. Should a Data Holder that no longer supports OIDC Hybrid Flow reject response_type "code id_token" being included in the client registration (e.g. if "response_types": ["code", "code id_token"] is presented ?

   • Option 2a: Ignore "code id_token" and constrain only to "code"
   • Option 2b: reject the registration request with an applicable oAuth error (i.e. "invalid_client_metadata")

3. Should a Data Holder that no longer supports OIDC Hybrid Flow ignore id_token_signed_response_alg, id_token_encrypted_response_alg, id_token_encrypted_response_enc

   • Option 3a: Ignore the parameters for client registration when OIDC Hybrid Flow is not supported: onus is on the Data Holder to ignore these parameters to minimise impact to ADRs
   • Option 3b: Return an error if any of these parameters are present when OIDC Hybrid Flow is not supported: All Data Holders return an error and the onus is on the ADR to handle this
   • Option 3c: At the discretion of the Data Holder: onus is on the ADR to handle errors

Proposed JARM support

If the Data Holder does not support response encryption they may do so by providing an empty array for the associated parameters or omit them from their OIDD. ADRs should be capable of handling both.

"authorization_encryption_alg_values_supported": [],
"authorization_encryption_enc_values_supported": []

# is equivalent to

"authorization_encryption_alg_values_supported": null,
"authorization_encryption_enc_values_supported": null

The parameters may be omitted from the OIDD. This is the equivalent of the empty arrays.

JARM states that for client metadata authorization_encrypted_response_alg:

The default, if omitted, is that no encryption is performed.

JARM also states that for authorization_encrypted_response_enc:

If authorization_encrypted_response_alg is specified, the default for this value is A128CBC-HS256

In other words, if a value for authorization_encrypted_response_alg is specified and authorization_encrypted_response_enc is not specified then the default enc algorithm is A128CBC-HS256. This value is permitted by the CDS. See #479.

Client Metadata Negotiation Scenarios

The following scenarios consider incorrect values passed by the ADR during registration of their client with the Data Holder. This may include new registrations as well as updates to existing registrations.

#	Scenario	Pre-Conditions	Assertion(s)	Result
1	Invalid authorization_signed_response_alg client metadata value	Data Holders correctly supports JARM and Authorization Code Flow ADR is attempting the register for Authorization Code Flow with JARM	Where authorization_signed_response_alg is null, or empty string (""), or not ("PS256" or "ES256")	oAuth error response (error value): "invalid_client_metadata"
2	Invalid authorization_encrypted_response_alg client metadata value	Data Holder correctly supports JARM and Authorization Code Flow Data Holder advertises response encryption	Where authorization_encrypted_response_alg is not null, and empty string (""), or not ("RSA-OAEP" or "RSA-OAEP-256")	oAuth error response (error value): "invalid_client_metadata"
3	Omitted authorization_encrypted_response_alg client metadata value	Data Holders correctly supports JARM and Authorization Code Flow Data Holder advertises response encryption	Where authorization_encrypted_response_alg is null	Successful client registration No response encryption is performed
4	Invalid authorization_encrypted_response_enc client metadata value	Data Holders correctly supports JARM and Authorization Code Flow Data Holder requires response encryption	Where authorization_encrypted_response_enc is not null, and empty string (""), or not ("A256GCM" or "A128CBC-HS256")	oAuth error response (error value): "invalid_client_metadata"
5	Omitted authorization_encrypted_response_enc client metadata value	Data Holders correctly supports JARM and Authorization Code Flow Data Holder requires response encryption	Where authorization_encrypted_response_enc is null	Successful client registration Response encryption is performed authorization_encrypted_response_enc defaults toA128CBC-HS256
6	Valid authorization_encrypted_response_enc and missing authorization_encrypted_response_alg client metadata value	Data Holders correctly supports JARM and Authorization Code Flow Data Holder requires response encryption ADR client registration includes a valid authorization_encrypted_response_enc value	Where authorization_encrypted_response_enc is in ("A256GCM" or "A128CBC-HS256") authorization_encrypted_response_alg is null	oAuth error response (error value): "invalid_client_metadata"

Transition Negotiation Scenarios - Existing Client

These scenarios consider the transition of the Data Holder supporting OIDC Hybrid Flow, Authorization Code Flow and the retirement of OIDC Hybrid Flow. These scenarios also consider what happens if the Data Holder requires response encryption or retires response encryption.

In all of these scenarios there remains a responsibility on the ADR to monitor each Data Holder's OIDD to discover changes that may impact their client registrations.

Assumptions:

• the existing client is registered for OIDC Hybrid Flow
• the existing client is updating its registration to use Authorization Code Flow with JARM
• the existing client is registering a new client or updating its existing client registration to use Authorization Code Flow with JARM
• the ADR may register a client to use both OIDC Hybrid Flow and Authorization Code Flow if the Data Holder supports both
• if the ADR is registered to support both OIDC Hybrid Flow and Authorization Code Flow and the Data Holder removes support for OIDC Hybrid Flow, the existing client registration will be unaffected but the ADR can no longer use OIDC Hybrid Flow to establish authorisations.

#	Scenario	Pre-Conditions	Assertion(s)	Result
7	Authorization Code Flow + JARM and no response encryption	Data Holder supports Authorization Code Flow in accordance with FAPI 1.0 and CDS 1.20.0 Data Holder advertises "code" as a supported response_types_supported value ({ ... "response_types_supported": ["code",...]}) Data Holder advertises JARM as supported ({ ... "response_modes_supported": ["jwt",...], "authorization_signing_alg_values_supported": ["PS256", "ES256"]}) Data Holder does not support JARM response encryption. That is, the Data Holder does not advertise authorization_encryption_alg_values_supported and authorization_encryption_enc_values_supported in their OIDD, or the Data Holder advertises empty arrays	The ADR verifies that the Data Holder supports Authorization Code Flow with JARM The ADR updates its client registration such that, response_type "code" "response_mode" "jwt" authorization_signed_response_alg is in ("PS256", "ES256") authorization_encrypted_response_alg is null or omitted authorization_encrypted_response_enc is null or omitted	Successful client registration (create or update) No response encryption is performed Client may continue to be registered for OIDC Hybrid Flow if that is supported by the Data Holder and requested by the Data Recipient
8	Authorization Code Flow with JARM and response encryption	Data Holder supports Authorization Code Flow in accordance with FAPI 1.0 and CDS 1.20.0 Data Holder advertises "code" as a supported response_types_supported value ({ ... "response_types_supported": ["code",...]}) Data Holder advertises JARM as supported ({ ... "response_modes_supported": ["jwt",...], "authorization_signing_alg_values_supported": ["PS256", "ES256"]}) Data Holder advertises authorization_encryption_alg_values_supported and authorization_encryption_enc_values_supported in their OIDD	The ADR verifies that the Data Holder supports Authorization Code Flow with JARM The ADR updates its client registration such that, response_type "code" "response_mode" "jwt" authorization_signed_response_alg is in ("PS256", "ES256") Assertion A: authorization_encrypted_response_alg is null or omitted Assertion B: authorization_encrypted_response_alg is in authorization_encryption_alg_values_supported list ("RSA-OAEP" or "RSA-OAEP-256") authorization_encrypted_response_enc is in authorization_encryption_enc_values_supported list ("A256GCM " or "A128CBC-HS256") Assertion C: authorization_encrypted_response_alg is in authorization_encryption_alg_values_supported list ("RSA-OAEP" or "RSA-OAEP-256") authorization_encrypted_response_enc is null or omitted	Result A: Successful client registration (create or update) No response encryption is performed Client may continue to be registered for OIDC Hybrid Flow if that is supported by the Data Holder and requested by the Data Recipient Result B Successful client registration (create or update) Response encryption is performed using the selected algorithms Client may continue to be registered for OIDC Hybrid Flow if that is supported by the Data Holder and requested by the Data Recipient Result C Successful client registration (create or update) authorization_encrypted_response_enc is defaulted to A128CBC-HS256 by the Data Holder Response encryption is performed Client may continue to be registered for OIDC Hybrid Flow if that is supported by the Data Holder and requested by the Data Recipient
9	DH switches on response encryption	A Data Holder has supported JARM without response encryption. The Data Holder changes to support response encryption. Pre-Conditions ADR has an existing valid client registration Data Holder does not support response encryption Data Holder changes its OIDD to advertise response encryption support	Assertion A: If Solution Question 1a is supported, the client continues to work as-is without a registration update and no response encryption is performed Assertion B: If Solution Question 1b is supported, the client MUST update their registration to use a suitable encryption algorithm set. Until such time, the client cannot perform any new authorisation requests successfully. Existing authorisations will continue to work correctly. Assertion C: If the ADR updates to use response encryption, the client must register a suitable encryption algorithm set	Existing authorisations will continue to work. For Assertion B and C, new authorisations will be rejected by the DH unless the ADR updates their client registration
10	DH switches off response encryption	This requires the ADR to monitor the Data Holder's OIDD endpoint and identify the change to remove response encryption support. In this case, the ADR should update their client registration to remove any encryption algorithms. The Data Holder must ignore the encryption algorithms so they can continue to support ADR clients establishing new authorisation requests without breaking. ADRs should be developed so they are resilient and able to identify that the response is not encrypted and cater for this. Pre-Conditions ADR has an existing valid client registration Data Holder supports response encryption Data Holder changes its OIDD to remove response encryption support	Data Holder updates its OIDD and removes authorization_encryption_alg_values_supported and authorization_encryption_enc_values_supported. ADR polls Data Holder OIDD endpoint to discover the change ADR updates its client registration to stop using response encryption	Successful client registration update. If the ADR does not poll the Data Holder and attempts to perform response encryption validation it should see that the response is not encrypted and verify this is correct in accordance with the OIDD of the Data Holder and complete the authorisation successfully. The ADR will still have a client registered with a previously chosen response encryption algorithm - the ADR should update their client registration as soon as possible, but the Data Holder can ignore the registered encryption algorithm because they no longer support response encryption.
11	Client registration supports OIDC Hybrid Flow and Authorization Code Flow	ADR has an existing valid client registration with OIDC Hybrid Flow Data Holder supports Authorization Code Flow and JARM	ADR polls Data Holder OIDD endpoint to discover the change ADR updates its client registration to support both OIDC Hybrid Flow and Authorization Code Flow ADR provides a registration request where response_types = ["code", "code id_token"] id_token_signed_response_alg is a valid value id_token_encrypted_response_alg is a valid value id_token_encrypted_response_enc is a valid value authorization_signed_response_alg is a valid value authorization_encrypted_response_alg is a valid value authorization_encrypted_response_enc is a valid value	Successful client registration update for both OIDC Hybrid Flow and Authorization Code Flow
12	Data Holder removes OIDC Hybrid Flow support, client is already registered for Authorization Code Flow	ADR has an existing valid client registration with OIDC Hybrid Flow AND Authorization Code Flow Data Holder supports Authorization Code Flow	Data Holder removes support for OIDC Hybrid Flow	ADR must only use Authorization Code Flow with JARM ADR should update their client registration to remove OIDC Hybrid Flow A Data Holder may remove OIDC Hybrid Flow support for all clients without a registration update Any attempt by the ADR to initiate an authorisation request using response_type "code id_token" would be rejected
13	Data Holder removes OIDC Hybrid Flow, client is not registered for Authorization Code Flow	ADR has an existing valid client registration with only OIDC Hybrid Flow Data Holder supports Authorization Code Flow	Data Holder removes support for OIDC Hybrid Flow ADR performs a client registration update to register the client for Authorization Code Flow and JARM ADR provides a registration request where response_types = ["code"] authorization_signed_response_alg is a valid value authorization_encrypted_response_alg is a valid value authorization_encrypted_response_enc is a valid value ADR removes OIDC Hybrid Flow support response_types = ["code id_token"] is not permitted id_token_signed_response_alg is not permitted id_token_encrypted_response_alg is not permitted id_token_encrypted_response_enc is not permitted	ADR MUST only use Authorization Code Flow with JARM ADR MUST update their client registration to register for Authorization Code Flow A Data Holder may remove OIDC Hybrid Flow support for all clients without a registration update Any attempt by the ADR to initiate an authorisation request using response_type "code id_token" would be rejected

Invalid Data Holder configuration

If the Data Holder still supports OIDC Hybrid Flow:

The Data Holder is in an invalid state. The ADR should not update thier client registration to use ACF because the Data Holder is non-compliant and does not support JARM with Authorization Code Flow.

The ADR continues to use their current registration.

ADRs creating new client registrations should continue to use OIDC Hybrid Flow with the ID Token acting as the detached signature in accordance with FAPI 1.0 Advanced s5.2.3.1

If the Data Holder does not support OIDC Hybrid Flow:

Assuming the Data Holder has dropped support for OIDC Hybrid Flow and advertises they support ACF but doesn't support JARM, the Data Holder is non-compliant.

In this scenario, the ADR cannot perform any new authorisation requests successfully. Existing authorisations will continue to work as they only require the exchange of the existing refresh token for a short-lived access token.

[AG-IAM]

3. Should a Data Holder that no longer supports OIDC Hybrid Flow ignore id_token_signed_response_alg, id_token_encrypted_response_alg, id_token_encrypted_response_enc

   • Option 3a: Ignore the parameters for client registration when OIDC Hybrid Flow is not supported: onus is on the Data Holder to ignore these parameters to minimise impact to ADRs
   • Option 3b: Return an error if any of these parameters are present when OIDC Hybrid Flow is not supported: All Data Holders return an error and the onus is on the ADR to handle this
   • Option 3c: At the discretion of the Data Holder: onus is on the ADR to handle errors

Since "openid" scope is mandatory in request object, shouldn't atleast the "id_token_signed_response_alg" be passed in the DCR call, as the id_token will be returned from token endpoint.

[tinagroark]

Clarification for decision write-up please - point 13 seems to indicate id_token encryption is not allowed for ACF.

My understanding is that DCR client metadata does not allow the ADR to differentiate id_token encryption for each flow, therefore the standard must support id_token encryption for ACF where the ADR is registered for both Hybrid Flow and ACF.

Can you clarify please if id_token encryption is OPTIONAL or NOT ALLOWED for ADRs who register solely for ACF?

[nils-work]

This change request was incorporated through ConsumerDataStandardsAustralia/standards#282 (comment)