search

ConsumerDataStandardsAustralia / standards-maintenance

This repository houses the interactions, consultations and work management to support the maintenance of baselined components of the Consumer Data Right API Standards and Information Security profile.
41 stars 9 forks source link

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

Closed CDR-API-Stream closed 1 year ago

CDR-API-Stream commented 1 year ago

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

DSB Proposed Solution

The DSB proposed solution is presented here.

CDR-API-Stream commented 1 year ago

See https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/458 and comment for further information.

CDR-API-Stream commented 1 year ago

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.

  1. Update the "OpenID Provider Configuration End Point" section in accordance with #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.

  2. 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 commented 1 year ago

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

markverstege commented 1 year ago

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 https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/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:

# 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 commented 1 year ago

  1. 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 commented 1 year ago

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 commented 1 year ago

This change request was incorporated through https://github.com/ConsumerDataStandardsAustralia/standards/issues/282#issue-1486041781