Version Control

Introduction

This document is based on the OpenID Foundation's Financial API Read+Write specification document, FAPI-RW, which in turn is based on the Read only specification document. The NZ Banking Data profile will further shape these two base 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 with clauses and provisions necessary to reduce delivery risk for an API Provider's OP.

Notation Conventions

The key words "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2. These key words are not used as dictionary terms such that any occurrence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.

1. 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 Connect 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.

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

3. Terms and Definitions

For the purpose of this document, the terms defined in [FAPI ReadOnly profile] FAPI, [FAPI Read+Write profile] FAPI-RW and [OpenID Connect Core] OIDC apply.

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

5. Read and Write API Security Profile

5.2 NZ Banking Data 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 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

1. shall support confidential clients;
2. may support public clients;
3. shall secure its token endpoint using mutually authenticated TLS;
4. shall only support the response_type value code id_token;
5. shall authenticate the confidential client at the Token Endpoint using one of the following methods:
   1. tls_client_auth as per MTLS (Recommended); or
   2. private_key_jwt or 'client_secret_jwt` (Recommended); or
   3. client_secret_basic or client_secret_post provided the client identifier matches the client identifier bound to the underlying mutually authenticated TLS session (Allowed - but this support will be reviewed for a future version of the Security Profile);
6. shall issue an ID Token in the token response when openid was included in the requested scope as in Section 3.1.3.3 of OIDC with its "sub" value corresponding to the "Intent Id" and optional acr value in ID Token.
7. may support refresh tokens.
8. 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.

Further, if it wishes to provide the authenticated user's identifier to the client in the token response, the authorization server

1. shall issue an ID Token in the token response when openid was included in the requested scope as in Section 3.1.3.3 of OIDC with its sub value corresponding to the authenticated user and mandatory acr value in ID Token.
2. shall support Request Objects passed by value as in clause 6.3 of OIDC.

5.2.3 Public Client

NZ Banking Data OPs can support Public Clients at their discretion.

Should an OP wish to support public clients all provisions of FAPI-RW will be adhered too with exceptions below;

1. shall request user authentication at appropriate level

5.2.4 Confidential Client

A Confidential Client

1. may use separate and distinct Redirect URI for each Authorization Server that it talks to;
2. shall accept signed ID Tokens;

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;
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; and
2. shall supply the last time the customer logged into the client as defined by FAPI clause 6.2.2.3; and
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-customer-ip-address: 198.51.100.119;
5. shall supply the customer's user agent if this data is available in the x-customer-user-agent header,

Further, the client

1. may supply the customers authentication context reference (ACR) or applicable in the x-fapi-customer-acr header, e.g., x-fapi-customer-acr;

7. Request Object Endpoint

7.1 Introduction

1. OPs shall not support request_uri, OIDC Request Object by Reference.
2. OPs shall support Request Objects passed by value as in clause 6.3 of OIDC.

8. Security Considerations

8.1 TLS Considerations

The TLS considerations in FAPI section 7.1 shall be followed.

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

8.2 Message Source Authentication Failure and Message Integrity Protection Failure

It is not mandated that the Authorization request and response are authenticated. To provide message source authentication and integrity protection:

1. Authorization servers should support the Request Object Endpoint as per FAPI-RW clause 7
2. Authorization servers should return an ID token as a detached signature of the authorization response as per FAPI-RW part 2 clause 5.2.2.3.

8.3 Message Containment Failure

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

8.4 JWS Algorithm Considerations

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

As a downgrade for FAPI-RW section 8.6.2: 

1. Both clients and authorisation servers may use algorithms that use RSASSA-PKCS1-v1_5 (e.g. RS256). However, this is not recommended, and this support will be reviewed for a future version of the Security Profile.

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

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 Intent Id.

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. 

Hybrid Flow Request with Intent Id

This section describes parameters that should be used with an hybrid grant flow request so that an Intent Id can be passed from the Third Party to an API Provider for minimum conformance for the NZ Banking Data API Profile.

Prior to this step, 

1. The Third Party would have already registered an intent (with an Intent Id) with an API Provider. This is achieved by using one of the account information or payment initiation consent APIs.
2. The API Provider would have responded with an Intent Id (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 MAY 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
&nonce=n-0S6_WzA2Mj
&redirect_uri=https://api.mytpp.com/cb
&request=CJleHAiOjE0OTUxOTk1ODd.....JjVqsDuushgpwp0E.5leGFtcGxlIiwianRpIjoiM....JleHAiOjE0.olnx_YKAm2J1rbpOP8wGhi1BDNHJjVqsDuushgpwp0E

Parameters

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.

The Request Object MUST contain a Claims section with:

• openbanking_intent_id

The Request Object MAY contain Claims to be retrieved via the UserInfo endpoint only if the endpoint is made available and listed on the well known configuration endpoint on the authorisation server.

The Request Object MAY contain additional Claims to be requested should the API Provider's Authorization Server support them, these Claims will be listed on the OIDC Well Known configuration endpoint.

As per OIDC - when the request parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. However, parameters MAY also be passed using the OAuth 2.0 request syntax even when a Request Object is used.

Within a "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:

  "auth_time": {"essential": true}

can be used to specify that it is essential to return an auth_time Claim. If the value is false, it indicates that it is a Voluntary Claim. The default is false. By requesting Claims as Essential Claims, the RP indicates to the End-User that releasing these Claims will ensure a smooth authorization for the specific task requested by the End-User. Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary, unless otherwise specified in the description of the specific claim.

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

{
	"alg": "PS256",
	"kid": "GxlIiwianVqsDuushgjE0OTUxOTk"
}
.
{
	"aud": "https://api.alphanbank.com",
	"iss": "s6BhdRkqt3",
	"response_type": "code id_token",
	"client_id": "s6BhdRkqt3",
	"redirect_uri": "https://api.mytpp.com/cb",
	"scope": "openid payments accounts",
	"state": "af0ifjsldkj",
	"nonce": "n-0S6_WzA2Mj",
	"max_age": 86400,
	"claims": {
		"userinfo": {
			"openbanking_intent_id": {
				"value": "urn:alphabank-intent-58923",
				"essential": true
			}
		},
		"id_token": {
			"openbanking_intent_id": {
				"value": "urn-alphabank-intent-58923",
				"essential": true
			},
			"acr_values": {
				"essential": true,
				"values": ["urn:openbanking:nz:sca",
					"urn:openbanking:nz:ca"
				]
			}
		}
	}
}
.
<<signature>>

Claims

Where appropriate follow the JWT Good Practice Guides http://self-issued.info/docs/draft-sheffer-oauth-jwt-bcp-00.html#rfc.section.3.1