How-tos

CDR FAPI 1.0 Advanced: Transition to Phase 2

This article provides an overview of Cloudentity configurations to comply with the CDR FAPI 1.0 Advanced phase 2 profile requirements.

CDR FAPI 1.0 Advanced Alignment

The OIDF Financial-grade API (FAPI) security profile specifies security requirements for high risk API resources protected by the OAuth 2.0 Authorization Framework. CDR is adoptiong the FAPI specification to ensure the data holders and data recipients exchange data in the most secure way with appropriate consumer consents. CDR Phase 2 transition ensures mandatory Financial-grade API 1.0 Baseline and Financial-grade API 1.0 Advanced profile compliance with advanced OAuth specifications like OAuth 2.0 Pushed Authorization Requests(PAR), Proof Key for Code Exchange(PKCE), and more. Cloudentity has out of box compliance and certification in both FAPI 1.0 basic & FAPI 1.0 advanced profiles. With simple configuration updates existing workspaces can be transitioned to support CDR Phase 2 requirements.

At a highlevel, below recommendations for Phase 2 transition by CDR regime and the Phase 2 transition requirements are extracted and interpreted from the documents and discussion notes here.

CDR phase 2 transition timeline

Cloudentity Configuration Updates

New Workspaces

Please, note that new workspaces created after the proposed obligation date will have all the below settings enabled by default and this document will serve only as a reference guide thereafter.

Adopt FAPI 1.0: Baseline

No configuration update required, Cloudentity workspaces are already configured to be FAPI 1.0: Baseline compatible.

Adopt FAPI 1.0: Advanced

To enforce the FAPI 1.0 advanced profile specifications on an existing CDR workspace, navigate to Auth Settings » OAuth » General and select the CDR Australia Advanced option. Then, save your changes.

CDR - enabling FAPI advanced profile

Enforce Pushed Authorization Requests (PAR)

To enforce PAR on the server level and/or on the client application level, follow the instructions from the Enforcing PAR section of the OAuth Pushed Authorization Requests (PAR) Authorization Basics article.

CDR - PAR enforcement

With the above settings, PAR can be enforced for a given CDR workspace. Request URI expiry can also be configured within the settings as shown above and the value is set to 60 seconds by default. The configuration indicates that the request_uri must be used for the authorization code flow within the specified duration; this interval is measured to the point where the authorization server receives the request and does not include the time that it may take to process the request to issue or deny an authorization code.

Once the above configuration is toggled, in the OpenId Connect discovery endpoint for the given CDR workspace, below setting will be toggled to true.

"require_pushed_authorization_requests": true

Cloudentity also complies to below requirements as specified in FAPI PAR profile:

  • Request Object Expiry requirement specifies the request object must contain the exp claim that has a lifetime of no longer than 60 minutes after the nbf claim.
  • Request Object Expiry requirement specifies the request object must contain the nbf claim that is no longer than 60 minutes in the past.
  • Request Object Submission requirement uses the parameters included in the signed request object passed via the request_uri parameter

Enforce PKCE

PKCE authorization code flow is supported by default in the Cloudentity platform and can be enforced for all public clients.

  1. Navigate to Auth Settings » General » Allowed Grant types » Authorization Code

  2. Select Enforce PKCE for public clients.

CDR - Authorization Code Flow with PKCE - enable PKCE

OIDC Hybrid flow

Cloudentity configuration automatically limits the response types for the OIDC Hybrid flows in a CDR workspace and hence no specific configuration change is expected to meet this requirement. In a CDR-specific workspace, the following response_types are supported and can be found in the OIDC discovery endpoint as well.

  "response_types_supported": [
    "id_token",
    "code",
    "code id_token"
  ]

Refresh Token Cycling

Authorization servers at the data holders end MAY cycle refresh tokens when an access token is issued. In the refresh token grant type, the authorization server can optionally issue a new refresh token in the response, and if there isn’t a new refresh token, the client assumes the current refresh token continues to be valid.

One of the recommendations in Phase 2 is not to allow refresh token cycling at all. This means that the authorization server at the data holder end must not cycle refresh tokens and the existing refresh token should bound to the duration of the sharing arrangement.

Within Cloudentity, an advanced configuration can be enabled to stop refresh token cycling. When this configuration is turned on when an access token is requested in exchange of a refresh token, the existing refresh token is still valid and the existing one is returned and no new refresh token is created.

To disable refresh token cycling, navigate to Auth Settings » Advanced and select Disable refresh token cycling.

CDR - Disable refresh token cycling

JARM Support

By default, the Cloudentity authorization server has the JARM support enabled. When authorization code flow (response_type with value code) is used in conjunction with the response_mode value jwt, Cloudentity authorization server creates JWT-secured authorization responses.

The supported response mode can also be found in the OIDC Discovery endpoint as well.

  "response_modes_supported": [
  "fragment",
  "form_post",
  "query.jwt",
  "fragment.jwt",
  "form_post.jwt",
  "jwt"
  ]

Unique “kid” for JWK Set

FAPI 1.0 advanced recommends that the JWK set does not contain multiple keys with the same kid. Even though FAPI does not mandate this condition CDS has opted to ensure the kid for the key sets exposed by authorization server is unique. In Cloudentity, by default, the kid within a JWK key set auto generated is unique.

In case there is an operational process that creates the kid within JWKS used by the authorization server like import seed jobs instead of the default generated kid, it is recommended that such process assigns a unique kid per key set while initializing the CDR workspace.

ID Token Encryption Changed from MUST to MAY

As per OIDC FAPI guidelines ID token encryption is optional and CDR has also recommended to keep this optional. ID token encryption can be made optional at CDR workspace level and will be enforced at each client level based on following fields set during the client create or update using the DCR Register APIs. As per OIDC DCR specifications, if the below fields are not set, then it is assumed that the ID token doesn’t need to be encrypted. Otherwise, it needs to be.

id_token_encrypted_response_alg - OPTIONAL. JWE alg algorithm JWA REQUIRED for encrypting the ID Token issued to this client. If this is requested, the response is signed, and then encrypted with the result being a Nested JWT. The default, if omitted, is that no encryption is performed.

id_token_encrypted_response_enc - OPTIONAL. JWE enc algorithm JWA REQUIRED for encrypting the ID token issued to this client. If id_token_encrypted_response_alg is specified, the default for this value is A128CBC-HS256. When id_token_encrypted_response_enc is included, id_token_encrypted_response_alg MUST also be provided.

Configure ID token encryption in Auth Settings » Tokens » Signing and encryption.

CDR - ID token encryption

Scope Request Support

It is up to discretion of the authorization server whether to return granted scopes in access token. Even though FAPI requires the scope to be returned only in case of public clients conditionally in access token, Cloudentity authorization server continues to return all granted scopes, but reserves the right to stop returning the granted scopes as recommended at any point in time after Phase 2.

Deprecate Non Standard Claims

Cloudentity, by default, returns the Sharing Expires At and Refresh Token Expiry claims and by Phase 2 this field will be marked for deprecation and will be removed at any point after that without any notice. The claims_supported is also published in the OIDC document.

"claims_supported ": [
  "sub",
  "acr",
  "amr",
  "refresh_token_expires_at",
  "sharing_duration",
  "sharing_expires_at",
  "cdr_arrangement_id"
]

Cloudentity will continue to support the exp claim for refresh token expiry in refresh token introspection endpoint as specified in Security Endpoints. The exp claim is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time.

The workspace level setting for maximum time of refresh token TLL will be ignored for a CDR workspace instead the maximum time will be derived based on the consent duration of the data sharing agreement.

Cipher Support

FAPI 1.0 recommends following cipher suites. For TLS versions below 1.3, only the following 4 cipher suites shall be permitted:

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

When using the TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 or TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 cipher suites, key lengths of at least 2048 bits are required.

In case there are Web application firewalls (Cloudflare, Akamai, or different) or other software components that accepts and terminates TLS traffic on the path to Cloudentity or the data holder resource APIs, it is recommended that those components also be configured with the above cipher list to be compliant with the recommendations for accepting CDR traffic.

Configuration transition Highlights for Phase 2

Feature Cloudentity Phase2 configuration
FAPI 1.0: Baseline (Final) support FAPI 1.0: Baseline fully supported
Scope Request Support As specified by FAPI 1.0
Ignore Claims Outside The Request Object Ignored
Authorization Code Reuse Not Allowed
FAPI 1.0: Advanced (Final) support FAPI 1.0: Advanced fully supported
Cipher Support As specified by FAPI 1.0
JARM Support Supported
PAR version Supports RFC 9126
Require Pushed Authorization Requests Enforced
Request Object Submission PAR only
Request Object Expiry As specified
PKCE Support (RFC 7636) Available
Request URI Replay Refused & not allowed
Request URI Expiry Default 60 seconds
Refresh Token Cycling No Refresh Token Cycling
Retire Sharing Duration and Refresh Token Expiry claims Available marked for deprecation
Unique “kid” for JWK set Unique
Access Token Revocation Supported & enforced
Authorisation Flow - Hybrid Supported
Authorisation Flow - Authorization Code Supported