NZ Banking Data Security Profile v2.3.0
- 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.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 ID Token
- 5.1.3.1 Claims
- 5.1.1 Authorization Request
- 5.2 Decoupled Request
- 5.2.1 Authorization Request
- 5.2.1.1 Claims
- 5.2.2 Login Hint Token
- 5.2.2.1 Claims
- 5.2.3 ID Token Hint
- 5.2.4 Authorization Request Response
- 5.2.4.1 Claims
- 5.2.5 Token Request
- 5.2.6 Token Request Response
- 5.2.7 Ping Callback
- 5.2.8 ID Token
- 5.2.8.1 Claims
- 5.2.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 Decoupled Flow
- 6.2.1 Client Types
- 6.2.2 Grant Types
- 6.2.2.1 Client Credentials Grant Type
- 6.2.2.2 CIBA Flow
- 6.2.3 Access Tokens
- 6.2.4 Refresh Tokens
- 6.2.5 ID Tokens
- 6.2.6 Unspecified Behaviour
- 6.2.6.1 Validity Lengths
- 6.2.7 Success Flows
- 6.2.7.1 Client Credentials Grant Type (OAuth 2.0)
- 6.2.7.2 CIBA Flow
- 6.2.8 Non-Normative HTTP Request and Response Examples
- 6.3 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
Version Control
Version | Date | Author | Comments |
---|---|---|---|
2.0.0 | Apr 30, 2020 | Payments NZ API Working Group | Baseline |
2.1-draft1 | Jun 15, 2020 | @Gavin Wong (Unlicensed) | Updated:
|
2.1-rc2 | Sep 11, 2020 | @Gavin Wong (Unlicensed) | Updated:
|
2.2-draft1 | Oct 26, 2021 | @Gavin Wong (Unlicensed) | Updated:
Errata:
|
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 NZ Banking Data 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 NZ Banking Data 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 NZ Banking Data API Standard. 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 NZ Banking 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]: http://openid.net/specs/openid-financial-api-part-1.html
[FAPI-RW] - FAPI Read+Write profile [FAPI-RW]: http://openid.net/specs/openid-financial-api-part-2.html
[OIDC] - OpenID Connect Core 1.0 incorporating errata set 1 [OIDC]: http://openid.net/specs/openid-connect-core-1_0.html
[MTLS] - Mutual TLS Profile for OAuth 2.0 [MTLS]: https://tools.ietf.org/html/draft-ietf-oauth-mtls-03
[CIBA] - OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-02 [CIBA]: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html
[FAPI-CB] - Financial-grade API: Client Initiated Backchannel Authentication Profile [FAPI-CB]: https://openid.net/specs/openid-financial-api-ciba-ID1.html
[OAUTH-CLIENT-AUTH] - Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAUTH-CLIENT-AUTH]: https://tools.ietf.org/html/rfc7521
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.
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.
5.2 Read and Write API Security Provisions
5.2.1 Introduction
The NZ Banking Data API 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 requires 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 NZ Banking Data APIs.
5.2.2 Authorization Server
The Authorization Server
shall only support confidential clients;
shall secure its token endpoint using mutually authenticated TLS;
shall only support the
response_type
valuecode id_token
;shall require the ConsentId to be passed in the authorisation request as an essential claim;
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.
may support refresh tokens; and
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.
5.2.4 Confidential Client
A Confidential Client
may use separate and distinct Redirect URI for each Authorization Server that it talks to; and
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
shall mandate mutually authenticated TLS; and
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
shall use mutually authenticated TLS;
shall supply the last time the customer logged into the client as defined by FAPI clause 6.2.2.3;
shall supply the customer's IP address if this data is available as defined by FAPI clause 6.2.2.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
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:
shall not support
request_uri
, OIDC Request Object by Reference;shall only support Request Objects passed by value as in clause 6.3 of OIDC.
8. Security Considerations
The Message containment failure considerations in FAPI section 7.4 shall be followed.
8.5 TLS Considerations
The TLS considerations in FAPI section 7.1 shall be followed; and
The TLS considerations in FAPI-RW section 8.5 shall be followed.
8.6 JWS Algorithm Considerations
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.
5.2 Read and Write API Security Provisions
5.2.2 Authorization Server
The Authorization Server
shall require a previously staged ConsentId to be passed in the authentication request;
shall not require clients to provide a request_context claim - as these fraud and threat parameters will be passed in the consent object;
shall only support login_hint_token and id_token_hint; and
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
shall mandate mutually authenticated TLS; and
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
shall use mutually authenticated TLS;
shall supply the last time the customer logged into the client as defined by FAPI clause 6.2.2.3;
shall supply the customer's IP address if this data is available as defined by FAPI clause 6.2.2.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
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
The TLS considerations in FAPI-CB section 7.9 shall be followed.
7.10 Algorithm Considerations
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 an 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 the redirect authorisation flow for the NZ Banking Data APIs.
Prior to this step,
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.
The API Provider would have responded with an 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=s6BhdRkqt3
&state=af0ifjsldkj&
&scope=openid%20payments
&nonce=n-0S6_WzA2Mj
&redirect_uri=https://api.mytpp.com/cb
&request=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6I.....JjVqsDuushgpwp0E.5leGFtcGxlIiwianRpIjoiM....JleHAiOjE0.olnx_YKAm2J1rbpOP8wGhi1BDNHJjVqsDuushgpwp0E
Parameters
Parameter | NZ Banking Data 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 " 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 be 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.
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": { "value": "urn-alphabank-intent-58923", "essential": true } } }
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:
{