Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Version

Date

Author

Comments

v1.0.0

 

Open Banking Read/Write API TeamPublished
Implementer's Draft v1.0.0

 

Open Banking Read/Write API TeamRenamed to Implementer's Draft. Client Registration section moved to OB Directory Specification
Implementer's Draft v1.0.1

 

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


Info
titlePlease Note

The MASTER location for this profile is located here: https://bitbucket.org/openid/obuk/src/4630771db004da59992fb201641f5c4ff2c881f1/uk-openbanking-security-profile.md?at=master&fileviewer=file-view-default

Version Control is located here: https://bitbucket.org/openid/obuk/commits/all. All changes are tracked as GIT commits for 100% transparency and visibility. Ideally comments, issues and pull requests will raised against the OIDF git repository however comments raised below as comments or on feedback pages will be responded too and incorporated during a transition period.

The tagged version in Bitbucket which corresponds to this specification version is included below.

...

Examples are non-normative

HTTP Request
Code Block
languagejs
themeMidnight
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
Request JWS (Without Base64 encoding)

...

can be used to specify that it is Essential to return an auth_time Claim Value.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. OIDC Core

Code Block

...

languagejs
themeMidnight
{
    "alg""RS256",

...


    "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": {"essential":

...

 true,

...


                "values": ["urn:openbanking:psd2:sca",

...


                     "urn:openbanking:psd2:ca"]}}

...


      }

...


    }

...


}

...


.

...


<<signature>>
id_token returned - Sub being populated with an EphemeralId of the IntentId - Non Normative
Code Block
language

...

js
themeMidnight
{
  "alg""RS256",

...


  "kid""12345",

...


  "typ""JWT"

...


}

...


.

...


{

...


   "iss""https://api.alphabank.com",

...


   "iat": 1234569795,

...


   "sub""urn

...

-alphabank

...

-payment

...

-58923",

...


   "acr""urn:openbanking:psd2:ca",

...


   "openbanking_intent_id""urn

...

-alphabank

...

-payment

...

-58923",

...


   "aud""s6BhdRkqt3",

...


   "nonce""n-0S6_WzA2Mj",

...


   "exp": 1311281970,

...


   "s_hash""76sa5dd",

...


   "c_hash""asd097d"

...


  }

...


.

...


{

...


<<Signature>>

...


}


id_token returned - Identity Claims and IntentId With sub being populated with an UserIdentifier - Non Normative

Code Block
languagejs
themeMidnight
{

...


  "alg""RS256",

...


  "kid""12345",

...


  "typ""JWT"

...


}

...


.

...


{

...


   "iss""https://api.alphabank.com",

...


   "iat": 1234569795,

...


   "sub""ralph.

...

bragg@raidiam.com",

...


   "acr""urn:openbanking:psd2:sca",

...


   "address""2 Thomas More Square",

...


   "phone""+447890130559",

...


   "openbanking_intent_id""urn

...

-alphabank

...

-payment

...

-58923",

...


   "aud""s6BhdRkqt3",

...


   "nonce""n-0S6_WzA2Mj",

...


   "exp": 1311281970,

...


   "s_hash""76sa5dd",

...


   "c_hash""asd097d"

...


  }

...


.

...


{

...


<<Signature>>

...


}

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


  

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.
 
NoYes - 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 thisthis 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_timeDate/time when End User was authorisedThis 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.

acrAuthentication 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 ReferencesThe 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/ANo
 
No specific requirement from OB.
 
s_hashState Hash ValueMay 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_hashAccess Token Hash ValueAccess 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_hashCode hash value.Code Hash ValueIts 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.

...