v3.0.0 Security Profile

Owned by Nigel Somerfield
Nov 13, 2023
85 min read

 

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.0

Nov 13, 2023

@Nigel Somerfield

Version 3.0.0 release

 

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 imp