| Table of Contents | ||||
|---|---|---|---|---|
|
...
Version | Date | Author | Comments |
|---|---|---|---|
| v1.0.0 |
| Open Banking Read/Write API Team | Published |
| Implementer's Draft v1.0.0 |
| 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 |
| Open Banking Read/Write API Team | Recreating document from up to date sub sections. Clarifications to Implementation Guide
|
| Implementer's Draft v1.1.0 | Open Banking Read/Write API Team | Reflecting changes to the R/W API specifications for v1.1:
| |
Implementer's Draft v1.1.1 | Open Banking Read/Write API Team | Reflecting errata updates resultant from live proving
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 | ||
|---|---|---|
| ||
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 | ||||
|---|---|---|---|---|
| ||||
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 | ||||
|---|---|---|---|---|
| ||||
{ |
...
"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 | ||||
|---|---|---|---|---|
| ||||
{ |
...
"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 | ||||
|---|---|---|---|---|
| ||||
{ |
...
"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 | Required by |
iss | Issuer of the token | Token issuer will be specific to the business | 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.
| 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 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 | 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. |
...
1. The PISP can query for the status of a Payment-Submission by invoking the /payment-submissions using the known PaymentSubmissionId. This can use an existing access token with payments scope or the PISP can obtain a fresh access token by replaying the client credentials grant request as per Step 2 - Setup Single Payment Initiation.
| Request: payment-submissions/{PaymentSubmissionId} | Response: payment-submissions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
2. A PISP can also optionally query for the status of a Payment resource by invoking /payments/{PaymentId}. This can use an existing access token with payments scope or the PISP can obtain a fresh access token by replaying the client credentials grant request as per Step 2 - Setup Single Payment Initiation.
Account API Specification
...