/
v3.0.1 Security Profile

v3.0.1 Security Profile

 

Version Control

Version

Date

Author

Comments

 

Version

Date

Author

Comments

 

3.0.0-draft1

May 3, 2022

Payments NZ API Working Group

Baseline

 

3.0.0-draft2

Nov 21, 2022

@Nigel Somerfield

Added refresh token introspection

 

3.0.0-draft2

Dec 15, 2022

@Nigel Somerfield

  • Updated Normative References

  • Updated Read and Write API Security Provisions

  • Added section 5.2 Authorization Code Flow - Non-Normative examples

  • Added section 6.2 Authorization Code Flow - Implementation Guide

 

3.0.0-draft2

Jan 5, 2023

@Nigel Somerfield

Updated Decoupled Flow examples

 

3.0.0-draft2

Jan 9, 2023

@Nigel Somerfield

Updated Decoupled Flow implementation guide

 

3.0.0-draft2

Jan 10, 2023

@Nigel Somerfield

Updated Hybrid Flow implementation guide

 

3.0.0-draft2

Feb 15, 2023

@Nigel Somerfield

Added supported authorisation grant types

 

3.0.0-draft2

Feb 21, 2023

@Nigel Somerfield

Updated:

  • Request Object references to include FAPI 1.0

  • Updated Request Object nbf and exp claim definitions for clarity

  • Moved the example JARM HTTP response earlier to improve readability

  • Minor wording change to reflect the CIBA ping is request to third party, not a response

Added:

  • Hybrid flow example HTTP authorisation response

 

3.0.0-draft2

Mar 1, 2023

@Nigel Somerfield

Added:

Updated:

 

3.0.0-draft2

Mar 13, 2023

@Nigel Somerfield

Removed ConsentId from JARM response token data model and examples.

 

3.0.0-draft2

Apr 4, 2023

@Nigel Somerfield

Added missing login_hint_token object (subject) definition

 

3.0.0-draft2

Apr 24, 2023

@Nigel Somerfield

Updated:

  • login_hint_token to include reference to RFC7519 registered JWT claims.

Added:

  • BCP-225 / RFC8725 as normative reference for JWT Best Current Practices

 

3.0.0-rc1

May 5, 2023

@Nigel Somerfield

Migrated:

  • Security Profile to new space as BWG guidance to separate Security Profile into its own standard

  • Security content from NZ Banking Data API to Security Profile

Updated:

 

3.0.0-rc1

Jun 16, 2023

@Nigel Somerfield

Updated:

  • ID Token description relating consent to customer. Now reads:
    ”In the NZ Open Data API context, the ID Token always identifies the consent (using ConsentId claim) that was authorised and Customer who authorised it (using the sub claim).”

  • Authorization code flow PAR request FAPI 1.0 applicability statement updated to clarify PAR is only required for authorization code flow.

 

3.0.0-rc1

Jul 21, 2023

@Nigel Somerfield

Corrected:

  • CIBA callback example HTTP request Authorization header did not use the correct client_notification_token value

 

3.0.0-rc2

Sep 12, 2023

@Nigel Somerfield

Baselined for release candidate 2

 

3.0.1

Sep 3, 2024

@Nigel Somerfield

Updated sections 7.1.2, 8.1 and 8.3. Clarify signing algorithms, certificate section and updated example keys to use x5c claim.

Jira issue addressed:
https://paymentsnz.atlassian.net/browse/ACSD-729

Patch release documentation:
https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1858633729

#005 v2.1.3, V2.2.3, v2.3.3, V3.0.1

Proposed update page that has been merged:

https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1822457858

 

Introduction

This document is based on the OpenID Foundation's Financial-grade API Read+Write specification FAPI-RW, which in turn is based on the Read only specification document FAPI. In addition, the Financial-grade API: Client Initiated Backchannel Authentication Profile FAPI-CB has been incorporated, to support a decoupled authentication flow. The Security Profile will further shape these profiles in some cases tightening restrictions and in others loosening requirements using keywords. Please see the introduction to FAPI-RW for a general introduction to the aims of this document.

The Security Profile outlines the differences between the FAPI-RW and FAPI-CB with clauses and provisions necessary to reduce delivery risk for API Providers.

Security Architecture

OAuth 2.0

OAuth 2.0 will be the foundational framework for API Security for the in-scope API standards. OAuth 2.0 itself is a framework which can be deployed in many ways, some of them completely incompatible with financial models. In order to securely use the OAuth 2.0 framework, a profile must exist by which both Third Parties and API Providers are certified to have correctly configured their clients and servers.

OIDC Core

The OpenID Connect Request object uses exactly the same claims object for specifying claim names, priorities, and values as OAuth 2.0. However if the Request object is used, the Claims object becomes a member in an assertion that can be signed and encrypted, allowing the API Provider to authenticate the request from the Third Party and ensure it hasn't been tampered with. The OpenID Connect Request object can either be passed as a query string parameter, or can be referenced at an endpoint that could theoretically be protected by MATLS. The use of JWT Request objects by reference is not supported due a number of delivery risks and remaining security concerns.

In addition to specifying a ticket, the Third Party can optionally require a minimum strength of authentication context or request to know how long ago the user was actually authenticated. Multiple tickets could be passed if necessary. Everything is fully specified. Vendors who implement this feature are not creating a one-off proprietary feature, they are simply supporting the OpenID Connect standard.

Full accountability is available as required by all participants. Not only can the API Provider prove that they received the original request from the Third Party, but the Third Party can prove that the access token that comes back was the token that was intended to be affiliated to this specific ConsentId.

OIDC Client Initiated Backchannel Authentication

The OIDC Client Initiated Backchannel Authentication (CIBA) profile enables a Client (Third Party) to initiate the authentication of the end-user (Customer) with the OpenID Provider (API Provider) in an out of band mechanism. This direct out of band mechanism between the Third Party and API Provider means that the Customer is not redirected to authenticate through the Customer's browser (or consumption device).

FAPI

The Financial API working group in the OpenID Foundation has created a draft standard for configuration of Financial-grade API security regimes. If any FAPI-compliant vendor can participate in the Open Data API ecosystem, it means that vendors can work to the standard and reach many customers, rather than having to create different solutions for different banking platforms. The FAPI profiles apply to both OIDC Core and OIDC CIBA profiles.

Scope

This part of the document specifies the method of

  • Applications to obtain the OAuth tokens in an appropriately secure manner for financial data access;

  • Applications to use OpenID flows to identify the Customer; and

  • Using tokens to interact with the REST endpoints that provides financial data;

This document is applicable to higher risk use cases which includes commercial and investment banking.

Normative References

The following referenced documents are strongly recommended to be used in conjunction with this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Terms and Definitions

For the purpose of this document, the terms defined in [FAPI ReadOnly profile] FAPI, [FAPI Read+Write profile] FAPI-RW, [OpenID Connect Core] OIDC, [OpenID Connect Client Initiated Backchannel Authentication Flow] CIBA, and [FAPI: Client Initiated Backchannel Authentication Profile] FAPI-CB apply.

Symbols and Abbreviated Terms

  • API Provider - provides APIs in a manner that complies with the API Standards (e.g. Account Information and Payment Initiation APIs), and connects those APIs with a Third Party.

  • Third Party - the entity that consumes an API in a manner that complies with the API Standards.

  • Customer - a natural or legal person that operates banking accounts.

Authorisation Scopes

To access each of the APIs, the API must be called with an access token in the HTTP Authorization header.

The scopes required with these access tokens and the grant type used to get the access token are specified in the specific API documentation.

Consent Authorisation

OAuth 2.0 scopes are coarse grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine grained scopes (e.g. a scope to specify that account information should only be provided for certain time periods or to enforce payments of a specified amount on a specified date).

A consent (identified with a ConsentId) is used to define the fine-grained permissions that are granted by the Customer to the Third Party. The API specifications define a variety of consents resources such as account-access-consents and domestic-payment-consents. The act of a Customer providing authorisation of a consent with an API Provider is called consent authorisation.

Two generic consent types are used in the API specification:

  • Short lived consents - these are used for one-off access to a protected resource

  • Long lived consents - these are used for enduring access to a protected resource

Steps for consent authorisation are:

  • The Third Party requests an API Provider to create a consent (with the fine-grained permissions) using a client credentials grant.

  • The API Provider creates the consent and responds with a ConsentId.

  • The Third Party then initiates an authorisation flow (passing in the ConsentId as a parameter) where the Customer authorises the consent with the API Provider. The supported grant types for the authorisation flow are described below.

  • The API Provider issues an access token to the Third Party tied to the authorised consent and the Customer.

Token Expiry

An API Provider may issue an access token and refresh token for a long-lived consent. These tokens may expire before the consent expires. In such a situation, the state of the consent does not change and the API Provider must not modify the state of the consent.

Token Expiry Time

The expiry time for issued access tokens and refresh tokens must be deterministic for the Third Party.

In order to achieve this:

  • The API Provider must indicate the lifetime in seconds of the access token in the expires_in field of the JSON object returned by the token endpoint (see https://tools.ietf.org/html/rfc6749#section-4.2.2 ).

  • If the API Provider issues a refresh token, the API Provider must support refresh token introspection, as per the Security Profile

  • The location of the introspection endpoint is indicated in authorisation server metadata introspection_endpoint.

  • If the API Provider issues a refresh token that does not expire, the API Provider must populate refresh token introspection response claim exp with a value representing the number of seconds to 03:14:07 UTC on 19 January 2038 (end of 32-bit UNIX epoch), or a value further in the future.

Supported Grant Types

OAuth2.0 and OIDC provide support for a variety of methods for the Authorization Server to issue an access token to the Client. These methods are called Grants.

Some of these Grant Types only identify the client, but not the resource owner. It is sufficient to provide the client's identity.

On the other hand, other grant types identify the client and resource owner. The resource owner must be authenticated to issue access tokens through such a grant type.

The Security Profile supports a sub-set of these grants as well as the FAPI Profile CIBA grant.

Grant Type

Mandatory?

Grant Type

Mandatory?

Client Credentials

Mandatory

Authorization Code Flow (using PAR with PKCE and JARM)

Mandatory

Hybrid Flow

Optional

Decoupled Flow (CIBA)

Mandatory

Client Credentials Grant

Some of the APIs can be accessed using an access token issued through a Client Credentials Grant. These APIs are not restricted resources owned by the Customer and do not require Customer consent authorisation. It is sufficient to identify and authenticate the Third Party in order to call these APIs.

The Client Credentials Grant is documented in Section 4.4 of the OAuth 2.0 RFC.

Authorization Code Flow

The Authorization Code Flow (see https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth ), used with PAR, PKCE and JARM is both more secure and offers a better consumer experience than the Hybrid Flow.

The Authorization Code Flow uses Pushed Authorization Requests, aka PAR (with PKCE) to submit an authorization request for validation, before redirecting the customer. Third Parties can then redirect when an authorization request has passed technical validation with the API provider.

The JARM response removes the need for ID token to be exposed via the redirect, and as such prevents leakage of identity information. Because the JARM response is a signed-JWT, there is no requirement for detached signature, code hash or state hash.

ID Token

When an access token is generated through a Authorization Code Flow, an OIDC Authorization Server will also issue an ID Token along with the access token.

The ID Token is a signed JWT that consists of a number of claims that identify the resource owner. In the NZ Open Data API context, the ID Token always identifies the consent (using ConsentId claim) that was authorised and Customer who authorised it (using the sub claim).

As the ID Token is signed by the API Provider and bound to a specific Third Party (through the aud claim), the ID Token could be leveraged to identify the Customer in subsequent authorisation requests. OIDC caters for this by allowing the ID Token to be passed into an authorization code grant request as the id_token_hint query parameter (as documented here).

Error Condition

If the Customer does not complete a successful consent authorisation (e.g. if the Customer is not authenticated successfully), the authorization flow ends with a redirection to the Third Party with an error response as described in section 4.1.1 herehttps://openid.net/specs/openid-financial-api-jarm.html#the-jwt-response-document . The Customer is redirected to the Third Party with an error parameter indicating the error that occurred.

Hybrid Flow

The Hybrid Flow enables access to APIs that require the Customer as well as Third Party to be identified and authenticated.

The Hybrid Flow (see Section 3.3. of the OIDC Specification) provides a redirect based mechanism to redirect a Customer to the API Provider's authorisation pages in order to authenticate the Customer and generate an authorization code. The Third Party can then exchange this authorization code for an access token (and optionally refresh token) by calling the API Provider's token endpoint and authenticating itself.

The Security Profile and FAPI Read & Write API Security Profile specify a more stringent set of requirements that API Providers and Third Parties must adhere to.

ID Token

When an access token is generated through a Hybrid Flow, an OIDC Authorization Server will also issue an ID Token along with the access token.

The ID Token is a signed JWT that consists of a number of claims that identify the resource owner. In the Security Profile API context, the ID Token always identifies the consent (using ConsentId claim) that was authorised and Customer who authorised it (using the sub claim).

As the ID Token is signed by the API Provider and bound to a specific Third Party (through the aud claim), the ID Token could be leveraged to identify the Customer in subsequent authorisation requests. OIDC caters for this by allowing the ID Token to be passed into an authorization code grant request as the id_token_hint query parameter (as documented here).

Error Condition

If the Customer does not complete a successful consent authorisation (e.g. if the Customer is not authenticated successfully), the hybrid flow ends with a redirection to the Third Party with an error response as described in RFC 6749 Section 4.1.2.1. The Customer is redirected to the Third Party with an error parameter indicating the error that occurred.

Decoupled Flow (CIBA)

The CIBA flow is a decoupled authentication flow that enables access to APIs that require the Customer as well as Third Party to be identified and authenticated.

The Client Initiated Back-channel Authentication flow is part of the OpenID specifications. A FAPI Profile of the CIBA specification is available and API Providers that implement the CIBA Flow must adhere to this FAPI profile.

An API Provider must implement the CIBA Flow to allow Customers to authenticate themselves using a decoupled authentication device that may be distinct from the consumption device on which they consume the Third Party application.

The NZ Security Profile specifies a more stringent set of requirements that API Providers and Third Parties must adhere to.

An API Provider:

  • must support the id_token_hint as a method of identifying the Customer to be authenticated.

  • may support login_hint_token as a method of identifying the Customer to be authenticated.

  • must document on their developer portal, the methods of identifying a Customer that the API Provider supports.

A Third Party:

  • must pass a method of identifying the Customer in the authorisation request object using either the login_hint_token or id_token_hint (i.e., not both).

  • must create a consent with the API Provider prior to creating the CIBA authorisation request.

  • must pass the generated ConsentId as a custom claim in the authorisation request object (this allows the access token that is eventually generated to be bound to a specific consent).

If an API Provider does not support a specific method of identifying a Customer, the API Provider must return an error with the error field set to invalid_request as per https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.13 .

ID Token Hint

To identify a Customer through a previously issued ID Token - the Third Party must issue an authorisation request object with an id_token_hint which contains an ID Token from a previously successful authentication event for the Customer. As this is a previously used ID Token, it is valid for a Third Party to use an expired ID Token.

Third Parties must provide either a login_hint_token or id_token_hint (i.e., not both).

Login Hint Token

The login_hint_token is a token in the CIBA authorisation request object that contains a subject_type and corresponding claim that identifies the Customer for whom authentication is being requested.

Third Parties must provide either a login_hint_token or an id_token_hint (i.e., not both).

The Security Profile and related APIs support these login_hint_token identification claims:

  • phone

  • email

  • username

  • api_provider_token

  • third_party_token

UML Diagram
Data Model

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZLoginHintToken1

 

NZLoginHintToken1

 

NZLoginHintToken1

 

subject

0..1

NZLoginHintToken1/subject

 

NZLoginHintType1

 

subject_type

1..1

NZLoginHintToken1/subject/subject_type

The type of subject identification used in the login_hint_token. The subject_type must be accompanied by the corresponding claim field. E.g., a subject_type of "phone" must be accompanied by the corresponding phone claim.

NZCIBASubject1Code

api_provider_token
email
phone
third_party_token
username

phone

0..1

NZLoginHintToken1/subject/phone

A phone number that identifies the Customer with the API Provider.

PhoneNumber

^\+[0-9]{1,3}\s?[0-9]{1,14}(\s[0-9]{1,13})?$

email

0..1

NZLoginHintToken1/subject/email

An email address that identifies the Customer with the API Provider.

Max256Text

 

username

0..1

NZLoginHintToken1/subject/username

The username that identifies the Customer with the API Provider.

Max70Text

 

api_provider_token

0..1

NZLoginHintToken1/subject/api_provider_token

A token generated by a Customer's authentication device that identifies the Customer with the API Provider. This token is passed to the Third Party.

xs:string

 

third_party_token

0..1

NZLoginHintToken1/subject/third_party_token

A token generated by a Third Party and registered with a Customer's authentication device by the Customer.

xs:string

 

Example

This is an example of a login_hint_token using the phone number as the subject_type:

{ "alg": "PS256", "kid": "GxlIiwianVqsDuushgjE0OTUxOTk" } . { "subject": { "subject_type": "phone", "phone": "+64-220466878" } } . <<signature>>

Changes to Consent Status

A Customer may revoke their consent either through the Third Party or directly through the API Provider. This only applies to long-lived consents.

  • When the Customer revokes their consent with the API Provider, the API Provider must update the consent Status as Revoked.

  • When the Customer revokes their consent with the Third Party, the Third Party must make a request to DELETE the consent using the ConsentId.

In each of the above cases, the consent states are terminal i.e., the API Provider must not allow any further state changes. The API Provider must not permit any authorisation code grants to be initiated with such a consent.

Consent Re-authorisation

Consent re-authorisation is the scenario where the API Provider requests a long-lived consent to be re-authorised (e.g., because of fraud risk). In this scenario, the Third Party reuses the existing ConsentId, and the API Provider may tailor the re-authorisation flow to be more efficient than the full consent authorisation flow.

A Third Party may request a Customer to re-authorise an existing long-lived consent that is in the Authorised state (using the existing ConsentId) at any point of time. This includes before and after the tokens bound to the consent have expired.

An API Provider must accept a request from a Third Party to re-authorise a long-lived consent (that is in the Authorised state) at any point of time. This includes before and after the tokens bound to the consent have expired.

Once a consent is re-authorised, the Third Party must not use access tokens and refresh tokens that were previously issued for the same consent.

If an API Provider issues a new access token and refresh token as a result of consent re-authorisation, it may invalidate the previously issued access tokens and refresh tokens for the same consent.

Use of Refresh Token

An API Provider may issue a refresh token along with an access token as a result of consent re-authorisation.

When an access token expires, the Third Party may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification.

If the Third Party fails to get an access token using a refresh token, the Third Party must initiate a consent re-authorisation flow.

NZ Read and Write API Security Profile

The NZ Read and Write API Security Profile extends from [FAPI Read+Write profile] FAPI-RW.

This section identifies variations from FAPI-RW and the numbered section references where there is a variation in FAPI-RW.

Read and Write API Security Profile Variations

5.2 Read and Write API Security Provisions

5.2.1 Introduction

The Security Profile does not distinguish between the security requirements from a technical level between "read" and "write" resources. The security requirements for accessing Customer resources held at API Providers require more protection level than a basic OAuth 2.0 (RFC6749) supports.

As a profile of the OAuth 2.0 Authorization Framework, this document mandates the following to the specified APIs.

5.2.2 Authorization Server

The Authorization Server

  1. shall only support confidential clients;

  2. shall secure its token endpoint using mutually authenticated TLS;

  3. shall only support the response_type values code and code id_token;

  4. shall require the ConsentId to be passed in the authorisation request as an essential claim;

  5. shall issue an ID Token in the token response as in Section 3.1.3.3 of OIDC with its "sub" value corresponding to a Pairwise Pseudonymous Identifier (PPID) for the Customer - that uniquely identifies the Customer to the Third Party. This PPID must not be reused for another Third Party.

  6. may support refresh tokens;

  7. shall require the request object to contain an nbf claim that is no longer than 60 minutes in the past;

  8. shall require the request object to contain an exp claim that has a lifetime of no longer than 60 minutes after the nbf claim

  9. shall provide a discovery endpoint that does not require a client certificate to authenticate using a TLS certificate that should be trusted by the user agent; and

  10. shall only support private_key_jwt for client authentication

5.2.4 Confidential Client

A Confidential Client

  1. may use separate and distinct Redirect URI for each Authorization Server that it talks to; and

  2. shall accept and verify signed ID Tokens (JWS);

6. Accessing Protected Resources

6.1 Introduction

The FAPI endpoints are OAuth 2.0 protected resource endpoints that return various financial information for the resource owner associated with the submitted access token.

6.2 Access Provisions

6.2.1 Protected resources provisions

The resource server with the FAPI endpoints

  1. shall mandate mutually authenticated TLS; and

  2. shall verify that the client identifier bound to the underlying mutually authenticated TLS transport session matches the client that the access token was issued to.

6.2.2 Client Provisions

The confidential client supporting this document

  1. shall use mutually authenticated TLS;

  2. shall supply the last time the customer logged into the client as defined by FAPI clause 6.2.2.3;

  3. shall supply the customer's IP address if this data is available as defined by FAPI clause 6.2.2.4;

  4. shall supply the merchant's IP address if this data is available in the x-merchant-ip-address header, e.g., x-fapi-merchant-ip-address: 198.51.100.119; and

  5. shall supply the customer's user agent if this data is available in the x-customer-user-agent header.

7. Request Object Endpoint

7.1 Introduction

OPs:

  1. shall only support request_uri when used with PAR, and not OIDC Request Object by Reference;

  2. shall only support Request Objects passed by value as in clause 6.3 of OIDC and as per PAR.

8. Security Considerations

  1. The Message containment failure considerations in FAPI section 7.4 shall be followed.

8.5 TLS Considerations

  1. The TLS considerations in FAPI section 7.1 shall be followed; and

  2. The TLS considerations in FAPI-RW section 8.5 shall be followed.

8.6 JWS Algorithm Considerations

  1. The JWS algorithm considerations in FAPI-RW section 8.6 shall be followed.

NZ Client Initiated Backchannel Authentication Profile

The NZ Client Initiated Backchannel Authentication Profile extends from [FAPI: Client Initiated Backchannel Authentication Profile] FAPI-CB.

This section identifies variations from FAPI-CB and the numbered section references where there is a variation in FAPI-CB.

The Client Initiated Backchannel Authentication Flow [CIBA] specifies an alternate method of users granting access to their resources whereby the flow is started from a consumption device, but authorized on an authentication device.

Client Initiated Backchannel Authentication Variations

5.2 Read and Write API Security Provisions

5.2.2 Authorization Server

The Authorization Server

  1. shall require a previously staged ConsentId to be passed in the authentication request;

  2. shall not require clients to provide a request_context claim - as these fraud and threat parameters will be passed in the consent object;

  3. shall only support login_hint_token and id_token_hint; and 

  4. shall not support the user_code parameter in the authentication request.

6. Accessing Protected Resources

6.1 Introduction

The FAPI endpoints are OAuth 2.0 protected resource endpoints that return various financial information for the resource owner associated with the submitted access token.

6.2 Access Provisions

6.2.1 Protected resources provisions

The resource server with the FAPI endpoints

  1. shall mandate mutually authenticated TLS; and 

  2. shall verify that the client identifier bound to the underlying mutually authenticated TLS transport session matches the client that the access token was issued to.

6.2.2 Client Provisions

The confidential client supporting this document

  1. shall use mutually authenticated TLS;

  2. shall supply the last time the customer logged into the client as defined by FAPI clause 6.2.2.3;

  3. shall supply the customer's IP address if this data is available as defined by FAPI clause 6.2.2.4;

  4. shall supply the merchant's IP address if this data is available in the x-merchant-ip-address header, e.g., x-fapi-merchant-ip-address: 198.51.100.119; and 

  5. shall supply the customer's user agent if this data is available in the x-customer-user-agent header.

7. Security Considerations

7.9 TLS Considerations

  1. The TLS considerations in FAPI-CB section 7.9 shall be followed.

7.10 Algorithm Considerations

  1. The JWS algorithm considerations in FAPI-CB section 7.10 shall be followed.

Non-Normative Examples

Hybrid Flow

This section describes parameters that should be used with a hybrid grant flow request so that a ConsentId can be passed from the Third Party to an API Provider for minimum conformance for the NZ Read and Write API Security Profile (extending FAPI-RW). The hybrid flow is used as an optional redirect authorisation flow for the NZ Banking Data and other specified APIs.

Prior to this step, 

  1. The Third Party would have already registered a consent with an API Provider. This is achieved by creating a resource with an account information or payment consent APIs.

  2. The API Provider would have responded with a ConsentId (this is the unique identifier for the consent resource).

Authorization Request

This section describes the bare minimum set of Authorization Request parameters that an API Provider must support. The definitive reference is specified in OIDC Section 3.3.2.1 (Authentication Request) and OIDC Section 3.1.2.1 (Authentication Request)

All API Providers must support the issuance of OIDC ID Tokens, a Third Party must request that an ID Token is issued. 

This is a non-normative example of the Authorization Request:

GET /authorize? response_type=code%20id_token &client_id=Z5O3upPC88QrAjx00dis &state=zSYkfyTKWQuZOBikzsmc& &scope=openid%20payments &nonce=w8q2mp1-z0o5w3mVHf-Mlt &redirect_uri=https://thirdparty.co.nz/redirect &request=eyJhbGciOiJQUzI1NiIsImtpZCI6IlZzOFFEMzlKaFJPcHZPTzhkSlFILW43TU5xTzZlOEFK WEh2MTA0ZGtuNU0iLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2FzLmFwaS5wcm92aWRlci5jb y5ueiIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJDb25zZW50SWQiOnsiZXNzZW50aWFsIjp0cnVlLCJ2Y Wx1ZSI6InVybi1hbHBoYWJhbmstaW50ZW50LTU4OTIzIn19fSwiY2xpZW50X2lkIjoiWjVPM3VwUEM4O FFyQWp4MDBkaXMiLCJleHAiOjE2NzE3NTg2NDIsImlhdCI6MTY3MTc1ODA0MiwiaXNzIjoiWjVPM3VwU EM4OFFyQWp4MDBkaXMiLCJqdGkiOiJlZTBlYTE4Yy1lMGEyLTQwODYtYTQ0Yy0xOTJjMGIzNzRmN2QiL CJuYmYiOjE2NzE3NTgwMzIsIm5vbmNlIjoidzhxMm1wMS16MG81dzNtVkhmLU1sdCIsInJlZGlyZWN0X 3VyaSI6Imh0dHBzOi8vdGhpcmRwYXJ0eS5jby5uei9yZWRpcmVjdCIsInJlc3BvbnNlX3R5cGUiOiJjb 2RlIGlkX3Rva2VuIiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJzdGF0ZSI6InpTWWtmeVRLV1F1W k9CaWt6c21jIn0.A7iPTBmVa2Ngf2ZWMSDVUo_g0eZdE1jGv_LYksUjLANBGjbCMCptMSIj4XuW-26o1 lwtfsFIpOZ2H4gi10jVwmS9igWRKvauR2cjFooTxj4sidlH_JbSMQOZ-q2jQd7hwbiCnSGakFe5uqTiK Q8ZAzAM485YvQcGPQXxGW3OSEgIE34QeE0AOfm7t_k16jAsF0Xzr7CscYeL3jZ0QKhuFYweM1xf3v7gC 8mQZJ1MfGUrSbU4Hwq0VDNqjnF-jX1KUa_LzZ39psHUEB8xm612ikNpqVz9gFBEQ6NhH9LU_wdLAIB0_ OMCutZDkosoCTBN2IDtBuNDua65BEMwQk-4apIg2slQeEriEELbLQNM_c02gS7gh8NwWICWgyfszw72d UigoIGJCDN2rDiY21wDRUodU_N6X1w1ilNKDYKDt_PyE3a1MlaI732iQpqw1rqmc8nZM1MCBYmtKy2ZJ PbqqYdzM4CD1Tne6saavffN5mu_bopmvqoSQmK-jm8Vc1wZuf8-v4TnP6yDu_w8v_7p_DI2viv8pnZ7n nhUeDRVW1HfQCrg4ldxE06xBTwUMIYsEpg_0IUf7BR3BtJSH1cMsZ9Pq0tWIDCUylqapMR7bCAG8von8 OeqBibTmRI6H9ihPRizY5k06GJDIobSC9knqUSsoGRmfQRXWC-6kOAGuyg

Parameters

Parameter

NZ Security Profile

Notes

Parameter

NZ Security Profile

Notes

scope

Required

Third Parties must specify the scopes that are being requested.

The scope parameter must contain openid

The scopes must be a sub-set of the scopes that were registered during Client Registration with the API Provider.

response_type

Required

OAuth 2.0 requires that this parameter is provided.

Third Parties must specify "code id_token"

The values for these parameters must match those in the Request Object, if present.

client_id

Required

Third Parties must provide this value and set it to the Client Id issued to them by the API Provider to which the authorization code grant request is being made.

redirect_uri

Required

Third Parties must provide the URI to which they want the resource owner's user agent to be redirected to after authorization.

This must be a valid, absolute URL that was registered during Client Registration with the API Provider.

state

Required

Third Parties must provide a state parameter.

The parameter may be of any format and is opaque to the API Provider.

The API Provider must play back the value in the redirect to the Third Party.

The API Provider must include the s_hash in the ID Token.

nonce

Required

Third Parties must provide a nonce parameter.

Used to help mitigate against replay attacks.

The API Provider must replay the supplied nonce parameter in any ID Token response.

request

Required

The Third Party must provide a value for this parameter.

The Request Object parameter must contain a JWS that is signed by the Third Party.

The JWS payload must consist of a JSON object containing a Request Object as per OIDC Section 6.1.

Request Object

This section describes the Request Object which is used in the request Authorization Request parameter. The definitive reference is specified in OIDC Section 6.1 (Request Object). All standards and guidance MUST be followed as per the OIDC specification. Note that FAPI 1.0 Baseline and FAPI 1.0 Advanced place additional constraints on the Request Object.

As per OIDC - when the Request Object is used, the OpenID Connect Request Object values (in the JWT) supersede those which are passed using the OAuth 2.0 request query parameter syntax. 

The Request Object:

  • must contain a "claims" request parameter with the ConsentId in the "id_token" object as an essential claim

  • may contain additional "claims" to be requested if the API Provider's Authorization Server support them - these claims must be listed on the OIDC Well Known configuration endpoint.

In OIDC - the "claims" request parameter in the Request Object is used to request that specific Claims be returned in either the ID Token or at the userinfo endpoint. Hence the top level members of the "claims" request parameter are:

  • id_token

  • userinfo

The userinfo and id_token members of the claims request parameter are JSON objects with the names of the individual Claims being requested as the member names. Within an individual Claims field, the "essential" field is required to indicate whether the Claim being requested is an Essential Claim. If the value is true, this indicates that the claim is an Essential Claim.

For instance, the claim request:

"claims": { "id_token": { "ConsentId": { "essential": true, "value": "urn-alphabank-intent-58923" } } }

can be used to specify that it is essential to return the ConsentId as a claim in the ID Token.

This is a non-normative example of the Request Object JWS - without Base64 encoding:

{ "alg": "PS256", "kid": "Vs8QD39JhROpvOO8dJQH-n7MNqO6e8AJXHv104dkn5M", "typ": "JWT" } . { "aud": "https://as.api.provider.co.nz", "claims": { "id_token": { "ConsentId": { "essential": true, "value": "urn-alphabank-intent-58923" } } }, "client_id": "Z5O3upPC88QrAjx00dis", "exp": 1671758642, "iat": 1671758042, "iss": "Z5O3upPC88QrAjx00dis", "jti": "ee0ea18c-e0a2-4086-a44c-192c0b374f7d", "nbf": 1671758032, "nonce": "w8q2mp1-z0o5w3mVHf-Mlt", "redirect_uri": "https://thirdparty.co.nz/redirect", "response_type": "code id_token", "scope": "openid payments", "state": "zSYkfyTKWQuZOBikzsmc" } . <<signature>>

Claims

Where appropriate follow the JWT Best Current Practices Guides [BCP-225] https://www.rfc-editor.org/rfc/rfc8725  

Field

NZ Security Profile

Notes

Field

NZ Security Profile

Notes

iss

Required

The iss value should be the Client Id of the Third Party, unless it was signed by a different party than the Third Party.

aud

Required

The aud value should be or include the API Provider's Issuer Identifier URL.

scope

Required

Third Parties must specify the scopes that are being requested.

The scope parameter must contain openid

The scopes must be a sub-set of the scopes that were registered during Client Registration with the API Provider.

response_type

Required

Third Parties must provide this field and set its value to 'code id_token'.

The values must match those in the request parameter.

client_id

Required

Third Parties must provide this value and set it to the Client Id issued to them by the API Provider to which the authorization code grant request is being made.

redirect_uri

Required

Third Parties must provide the URI to which they want the resource owner's user agent to be redirected to after authorization.

This must be a valid, absolute URL that was registered during Client Registration with the API Provider.

state

Required

Third Parties must provide a state parameter.

The parameter may be of any format and is opaque to the API Provider.

The API Provider must play back the value in the redirect to the Third Party.

The API Provider must include the s_hash in the ID Token.

nonce

Required

Third Parties must provide a nonce parameter.

Used to help mitigate against replay attacks. 

The API Provider must replay the supplied nonce parameter in any ID Token response.

max_age

Optional

Third Parties may provide a maximum authentication age parameter.

This specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the API Provider. If the elapsed time is greater than this value, the API Provider must attempt to actively re-authenticate the Customer. (The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter.)

If the parameter is provided, the API Provider must include an auth_time Claim value in the ID Token.

claims.id_token.ConsentId

Required

Third Parties must provide a ConsentId.

The ConsentId must be the identifier for a consent resource returned by the API Provider to Third Party that is initiating the authorisation request.

exp

Required

Third Parties must provide an exp claim
The time after which the JWT must not be accepted for processing. The processing of the "exp" claim requires that the current date/time MUST be before or equal to the expiry date/time listed in the exp claim.

The exp claim must be no more than 60 minutes after the nbf (not-before) claim