v1.0.0

Jul 14, 2017 

Open Banking Read/Write API Team

Published

Implementer's Draft v1.0.0

Jul 28, 2017 

Open Banking Read/Write API Team

Renamed to Implementer's Draft. Client Registration section moved to OB Directory Specification

Implementer's Draft v1.0.1

Jul 31, 2017 

Open Banking Read/Write API Team

Recreating document from up to date sub sections.

Clarifications to Implementation Guide

• Enhanced Payments API Sequence Diagram to improve readability

• Enhanced Accounts API Sequence Diagram to improve readability and add in the GET and DELETE flows for Account Requests

• Removing the need to repeat the API scopes when the exchanging of an Authorization Code for an Access Token for Payments and Accounts API requests in the Sequence Diagram and example HTTP Requests

Implementer's Draft v1.1.0

Sep 29, 2017 

Open Banking Read/Write API Team

Reflecting changes to the R/W API specifications for v1.1:

• Updated Account Identification SchemeName and structure from BBAN to SortCodeAccountNumber

• Corrected -00:00 timezone format to +00:00

• Updated format for fields within Meta and Links sections to upper camel case

• Corrected "AwaitingAuthentication" to "AwaitingAuthorisation” in non-normative example

• Removed x-jws-signature headers from non-normative examples

  • Errata to add redirect_uri to header for the Request : Access Token Request using Authorization Code

Implementer's Draft v1.1.1

Open Banking Read/Write API Team

Reflecting errata updates resultant from live proving

• Authorisation servers to provide a discovery endpoint over tls not ma-tls and via a browser acceptable root. TDA Decision 117

Removing duplicate references to FAPI Read Write or Read specifications.

Adding explicit line number references

Implementer's Draft v1.1.2

Open Banking Read/Write API Team

Reflecting errata updates resultant from live proving and errata issued from the OIDF Financial API Working Group

• Part 1: clarify that the returned list of scopes should be those granted

• Part 2: Require redirect_uri to be inside signed request object

• Allow more ciphers between authorisation server & user's browser

• #131: client_id supplied in request body should match the one supplied elsewhere TDA Decision 118

• Now includes embedded version of profile from Open ID Foundation's Bitbucket repository (rather than duplicating content)

• Updated examples to reflect correctly namespaced intent ids

response_type

Required

OAuth 2.0 requires that this parameter is provided. Value is set to  'code id_token', 'code id_token token' or 'code'

TPPs MUST provide this parameter and set its value to one of the three above depending on what the ASPSP supports as described in its well-known configuration endpoint.

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

Note: risks have been identified with "code" flow that can be mitigated with hybrid flow, the OpenBanking Profile allows ASPSPs to indicate what grant types are supported using the standard well-known configuration endpoint. RP's must take care in valdiating that code swap attacks have not been attempted.

client_id

Required

TPPs MUST provide this value and set it to the client id issued to them by the ASPSP to which the authorization code grant request is being made.

redirect_uri

Required

TPPs 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 ASPSP.

scope

Required

TPPs MUST specify the scope that is being requested.

At a minimum the scope parameter MUST contain openid

The scopes MUST be a sub-set of the scopes that were registered during Client Registration with the ASPSP.

state

Recommended

TPPs MAY provide a state parameter.

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

If the parameter is provided, the ASPSP MUST play-back the value in the redirect to the TPP

OPs SHOULD include the s_hash

request

Required

The TPP MUST provide a value for this parameter.

The parameter MUST contain a JWS that is signed by the TPP.

The JWS payload MUST consist of a JSON object cotntaining a request object as per OIDC Core 6.1.

The request object MUST contain a claims section that includes as a minimum

• openbanking_intent_id: that identifies the intent id for which this authorisation is requested
  The intent id MUST be the identifier for an intent returned by the ASPSP to TPP that is initiating the authorisation request.

• acr_values
  TPPs MAY provide a space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference.

  The values MUST be one or both of:

  urn:openbanking:psd2:sca: To indiciate that secure customer authentication must be carried out as mandated by the PSD2 RTS

  urn:openbanking:psd2:ca: To request that the customer is authenticated without using SCA (if permitted)

  *Subject to review from Government Digital Services / Cabinet Office

Inside an ID Token.

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 ASPSPs Authorization Server support them, these claims will be listed on the OID Well Known configuration endpoint.

Field

Definition

Notes

Value(s)

Required by
   Protocol

Required by
   OBIE

iss

Issuer of the token

Token issuer will be specific to the business 

https://private.api.hsbc.com

https://private.api.firstdirect.com

https://private.api.marksandspencer.com 

Yes

Yes
 A JSON string that represents the issuer identifier of the authorization server as defined in RFC7519. When a pure OAuth 2.0 is used, the value is the redirection URI. When OpenID Connect is used, the value is the issuer value of the authorization server.

sub

Token subject identifier
 

A unique and non-repeating identifier for the subject i.e the customer.
  couple of rules:

• It needs to be the same when created by the authorisation and Token endpoints during the Hybrid flow. 

Non Identity Services Providers:

Use the Intent/Consent ID for this field.

Identity Services Providers:

Value at the discretion of the OP's.

Yes
 

Yes

openbanking_intent_id

Intent ID of the originating request

A unique and non-repeating identifier containing the intentid.

Use the Intent/Consent ID for this field.
 

No

Yes - it's acknowledged that this field may duplicate the value in "sub" for many providers.

aud
 

Audience that the ID token is intended for

OpenID Connect protocol mandates this MUST include the client ID of the TPP.

Should contain the ClientID of the TPP's OAuth Client.

Yes

Yes - as per FAPI RW / OpenID Standard.

exp

Token expiration date/time

Expressed as an epoch i.e. number of seconds from
  1970-01-01T0:0:0Z as measured in UTC.
 RFC7519.

Yes
 

Yes

The validity length will be at the discretion of the Banks provided that it does not impact the functionality of the APIs. For example, an expiry time of 1 second is insufficient for all Resource Requests.
 

iat
 

Token issuance date/time
 

Expressed as an epoch i.e. number of seconds from
  1970-01-01T0:0:0Z as measured in UTC. 

RFC7519.

Yes

Yes

auth_time

Date/time when End User was authorised

This field is Required when the max_age request is made or max_age is included as an essential claim. In order to be compliant with the protocol we therefore need to support it.

Expressed as an epoch i.e. number of seconds from 1970-01-01T0:0:0Z as measured in UTC.

Case-specific

Case-Specific 

nonce
 

Used to help mitigate against replay attacks
 

Value is passed in as a Request parameter. If present it must be replayed in the ID token

Case-Specific

Required by FAPI Read Write (Hybrid explicitly required - required by OIDC Core for Hybrid Flow).

Hybrid Flow support is optional in the OB Security Profile.

acr

Authentication Context Class Reference
 

An identifier that qualifies what conditions the authentication performed satisfied. The acr SHOULD correspond to one of the values requested by the acr_values field on the request however even if not present on the request the aspsp should populate the acr with a value that attests that the aspsp performed or NOT performed an appropriate level of authentication such that the aspsp believes it has met the requirement for "Strong Customer Authentication".

The values to be provided will be to urn:openbanking:psd2:ca or urn:openbanking:psd2:sca. To cover the exemptions cases of PSD2 the PISP / AISP must have a way to request that a Bank NOT perform SCA for some requests. It’s entirely within the banks gift to ignore the requested ACR_VALUES however the Bank must reply with what level of AuthN was performed. (Once RTS comes into affect).
 

No

Yes

Caveated: As RTS is not signed off and will not be delivered by initial go-live aspsps do not have to provide a response value.

Aspsps that do not wish to provide this as a claim should remove it from the well-known configuration endpoint.

As per OIDC Core, marking a claim as "essential" and an ASPSP can not fulfill it then an error should not be generated.

amr

Authentication Methods References

The methods that are used in the authentication. For example, this field might contain indicators that a password was supplied or OTP initiated.
  

Note – industry direction is to consolidate on https://datatracker.ietf.org/doc/draft-richer-vectors-of-trust. so expect this field to be replaced shortly. AMR doesn’t give the flexibility to address all the actual particulars of both the authn and the identity that sits behind it.

No
 

No requirement to specify as it is to be soon superseded by Vectors of Trust.
 

azp
 

Authorized party
 

OPTIONAL. Authorized party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 Client ID of this party. This Claim is only needed when the ID Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.

OB N/A

No
 

No specific requirement from OB.
 

s_hash

State Hash Value

May include state hash, s_hash, in the ID Token to protect the state value;

Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the state value, where the hash algorithm used is the hash algorithm used in the algHeader Parameter of the ID Token's JOSE Header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url encode them. The s_hashvalue is a case sensitive string.

No

Recommended by OB

at_hash

Access Token Hash Value

Access Token hash value.

Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

Conditional

As per Hybrid Flow (OIDC Core) - Yes

If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.

c_hash

Code hash value.

Code Hash Value

Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header.

Conditional

As per Hybrid Flow (OIDC Core) - Yes.

If the ID Token is issued from the Authorization Endpoint with a code, which is the case for the response_type values code id_token and code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.

alg

Yes

Mandatory

The algorithm that will be used for signing the JWS.

The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1.

This MUST be an algorithm that support asymmetric encryption.

OB MAY limit this down further.

kid

Yes (optional)

Mandatory

The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS.

This MUST match the certificate id of the certificate selected in step 1.

The receiver SHOULD use this value to identify the certificate to be used for verifying the JWS.

iss

Mandatory

The issuer of the JWS.