v3.0.0 Security Profile
- 1 Version Control
- 2 Introduction
- 2.1 Security Architecture
- 2.1.1 OAuth 2.0
- 2.1.2 OIDC Core
- 2.1.3 OIDC Client Initiated Backchannel Authentication
- 2.1.4 FAPI
- 2.2 Scope
- 2.3 Normative References
- 2.4 Terms and Definitions
- 2.5 Symbols and Abbreviated Terms
- 2.6 Authorisation Scopes
- 2.7 Consent Authorisation
- 2.8 Token Expiry
- 2.8.1 Token Expiry Time
- 2.9 Supported Grant Types
- 2.9.1 Client Credentials Grant
- 2.9.2 Authorization Code Flow
- 2.9.2.1 ID Token
- 2.9.2.2 Error Condition
- 2.9.3 Hybrid Flow
- 2.9.3.1 ID Token
- 2.9.3.2 Error Condition
- 2.9.4 Decoupled Flow (CIBA)
- 2.9.4.1 ID Token Hint
- 2.9.4.2 Login Hint Token
- 2.10 Changes to Consent Status
- 2.11 Consent Re-authorisation
- 2.11.1 Use of Refresh Token
- 2.1 Security Architecture
- 3 NZ Read and Write API Security Profile
- 3.1 5.2 Read and Write API Security Provisions
- 3.1.1 5.2.1 Introduction
- 3.1.2 5.2.2 Authorization Server
- 3.1.3 5.2.4 Confidential Client
- 3.2 6. Accessing Protected Resources
- 3.2.1 6.1 Introduction
- 3.2.2 6.2 Access Provisions
- 3.2.2.1 6.2.1 Protected resources provisions
- 3.2.2.2 6.2.2 Client Provisions
- 3.3 7. Request Object Endpoint
- 3.3.1 7.1 Introduction
- 3.4 8. Security Considerations
- 3.1 5.2 Read and Write API Security Provisions
- 4 NZ Client Initiated Backchannel Authentication Profile
- 5 Non-Normative Examples
- 5.1 Hybrid Flow
- 5.1.1 Authorization Request
- 5.1.1.1 Parameters
- 5.1.2 Request Object
- 5.1.2.1 Claims
- 5.1.3 Authorisation Response
- 5.1.4 ID Token
- 5.1.4.1 Claims
- 5.1.1 Authorization Request
- 5.2 Authorization Code Flow
- 5.2.1 Pushed Authorization Requests (PAR) with JWT-Secured Authorization Requests & Proof-Key Code Exchange
- 5.2.1.1 Proof Key Code Exchange
- 5.2.2 Authentication
- 5.2.3 PAR Request using JAR
- 5.2.4 PAR Response
- 5.2.5 Error Response
- 5.2.6 Authorize request with PAR
- 5.2.7 OIDC metadata
- 5.2.8 JWT-Secured Authorization Response Mode (JARM)
- 5.2.8.1 FAPI 1.0
- 5.2.8.2 Signing and encryption
- 5.2.8.3 Example JARM response
- 5.2.8.4 Error response
- 5.2.8.5 Token request
- 5.2.8.6 Token response
- 5.2.1 Pushed Authorization Requests (PAR) with JWT-Secured Authorization Requests & Proof-Key Code Exchange
- 5.3 Decoupled Request
- 5.3.1 Authorization Request
- 5.3.1.1 Claims
- 5.3.2 Login Hint Token
- 5.3.2.1 Claims
- 5.3.3 ID Token Hint
- 5.3.4 Authorization Request Response
- 5.3.4.1 Claims
- 5.3.5 Token Request
- 5.3.6 Token Request Response
- 5.3.7 Ping Callback
- 5.3.8 ID Token
- 5.3.8.1 Claims
- 5.3.1 Authorization Request
- 5.1 Hybrid Flow
- 6 Implementation Guide
- 6.1 Hybrid Flow
- 6.1.1 Client Types
- 6.1.2 Grant Types
- 6.1.2.1 Client Credentials Grant Type
- 6.1.2.2 Hybrid Flow
- 6.1.3 Access Tokens
- 6.1.4 Refresh Tokens
- 6.1.5 ID Tokens
- 6.1.6 Authorization Codes
- 6.1.7 Unspecified Behaviour
- 6.1.7.1 Client Types
- 6.1.7.2 Grant Types
- 6.1.7.3 Validity Lengths
- 6.1.8 Success Flows
- 6.1.8.1 Client Credentials Grant Type (OAuth 2.0)
- 6.1.8.2 OIDC Hybrid Flow
- 6.1.9 Non-Normative HTTP Request and Response Examples
- 6.1.9.1 Step 1 - Agree Payment Consent
- 6.1.9.2 Step 2 - Setup Payment-Order Consent
- 6.1.9.3 Step 3 - Authorize Consent
- 6.1.9.4 Step 4 - Create Payment-Order
- 6.1.9.5 Step 5 - Get Domestic-Payment Status
- 6.2 Authorization Code Flow
- 6.2.1 Client types
- 6.2.2 Grant types
- 6.2.2.1 Client Credentials grant type
- 6.2.2.2 Authorization Code Flow
- 6.2.3 Access Tokens
- 6.2.4 Refresh Tokens
- 6.2.5 ID Tokens
- 6.2.6 Authorization Codes
- 6.2.7 Pushed Authorization Requests
- 6.2.7.1 Proof Key for Code Exchange
- 6.2.8 FAPI JWT-Secured Authorization Response Mode (JARM)
- 6.2.9 Unspecified Behaviour
- 6.2.9.1 Client Types
- 6.2.9.2 Grant Types
- 6.2.9.3 Validity Lengths
- 6.2.9.4 Authorization Code
- 6.2.9.5 ID Token
- 6.2.9.6 Access Token
- 6.2.9.7 Refresh Token
- 6.2.10 Success Flows
- 6.2.10.1 Client Credentials Grant Type (OAuth 2.0)
- 6.2.10.2 Authorization Code Flow
- 6.2.11 Non-Normative HTTP Request and Response Examples
- 6.2.11.1 Step 1 - Agree Payment Consent
- 6.2.11.2 Step 2 - Setup Payment-Order Consent
- 6.2.11.3 Step 3 - Pushed Authorization Request (PAR)
- 6.2.11.4 Step 4 - Authorise Consent with JARM response
- 6.2.11.5 Step 5 - Retrieve Tokens
- 6.2.11.6 Step 6 - Create Payment Order
- 6.2.11.7 Step 7 Get Domestic-Payment Status
- 6.3 Decoupled Flow
- 6.3.1 Client Types
- 6.3.2 Grant Types
- 6.3.2.1 Client Credentials Grant Type
- 6.3.2.2 CIBA Flow
- 6.3.3 Access Tokens
- 6.3.4 Refresh Tokens
- 6.3.5 ID Tokens
- 6.3.6 Unspecified Behaviour
- 6.3.6.1 Validity Lengths
- 6.3.7 Success Flows
- 6.3.7.1 Client Credentials Grant Type (OAuth 2.0)
- 6.3.7.2 CIBA Flow
- 6.3.8 Non-Normative HTTP Request and Response Examples
- 6.4 Refresh token introspection
- 6.4.1 Overview
- 6.4.1.1 Steps
- 6.4.2 Endpoints
- 6.4.2.1 POST /introspect
- 6.4.3 Sequence diagram
- 6.4.4 Data model
- 6.4.4.1 Introspection request
- 6.4.4.2 Introspection response
- 6.4.5 Endpoint Authentication
- 6.4.6 Metadata
- 6.4.7 Usage Examples
- 6.4.7.1 POST Introspection request
- 6.4.7.2 POST Introspection response
- 6.4.8 Errors
- 6.4.1 Overview
- 6.5 Edge Cases
- 6.1 Hybrid Flow
- 7 JSON Security Suite
- 8 Prerequisites
- 8.1 Certificates
- 8.2 API Centre Register
- 8.2.1 Organisations
- 8.2.2 Keys
- 8.2.3 Authorisation Servers
- 8.2.4 Swagger
- 8.3 Keys used in examples
- 8.3.1 API provider:
- 8.3.2 Third Party:
Version Control
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 |
|
|
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:
Added:
|
|
3.0.0-draft2 | Mar 1, 2023 | @Nigel Somerfield | Added:
Updated:
|
|
3.0.0-draft2 | Mar 13, 2023 | @Nigel Somerfield | Removed |
|
3.0.0-draft2 | Apr 4, 2023 | @Nigel Somerfield | Added missing |
|
3.0.0-draft2 | Apr 24, 2023 | @Nigel Somerfield | Updated:
Added:
|
|
3.0.0-rc1 | May 5, 2023 | @Nigel Somerfield | Migrated:
Updated:
|
|
3.0.0-rc1 | Jun 16, 2023 | @Nigel Somerfield | Updated:
|
|
3.0.0-rc1 | Jul 21, 2023 | @Nigel Somerfield | Corrected:
|
|
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.
[FAPI] - FAPI ReadOnly profile [FAPI]: Final: Financial-grade API Security Profile 1.0 - Part 1: Baseline
[FAPI-RW] - FAPI Read+Write profile [FAPI-RW]: Final: Financial-grade API Security Profile 1.0 - Part 2: Advanced
[OIDC] - OpenID Connect Core 1.0 incorporating errata set 1 [OIDC]: Final: OpenID Connect Core 1.0 incorporating errata set 2
[MTLS] - Mutual TLS Profile for OAuth 2.0 [MTLS]: RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
[CIBA] - OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-02 [CIBA]: OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0
[FAPI-CB] - Financial-grade API: Client Initiated Backchannel Authentication Profile [FAPI-CB]: Draft-02: Financial-grade API: Client Initiated Backchannel Authentication Profile
[OAUTH-CLIENT-AUTH] - Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAUTH-CLIENT-AUTH]: RFC 7521: Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants
[JARM] - OpenID FAPI JWT-Secured Authorization Response Mode: Draft-02: Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
[PAR] - OAuth 2.0 Pushed Authorization Requests: RFC 9126: OAuth 2.0 Pushed Authorization Requests
[JAR] - The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR): RFC 9101: The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)
[PKCE] - Proof Key for Code Exchange by OAuth Public Clients: RFC 7636: Proof Key for Code Exchange by OAuth Public Clients
[BCP-225] - JSON Web Token Best Current Practices: RFC 8725: JSON Web Token Best Current Practices
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? |
---|---|
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