| 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 | 29 | Open Banking Read/Write API Team | Recreating document from up to date sub sections. | Implementer's Draft v1.0.1 |
| Open Banking Read/Write API Team | Clarifications to Implementation Guide
|
...
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 occurence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.
Financial Services – Open Banking API Security Profile
This document is based on the OpenID Foundations Financial API Read+Write specification document which in turn is based on the Read only specification document. The OpenBanking profile will further shape these two base profiles in some cases tightening restrictions and in others loosening requirements using key words
...
Full accountability is available as required by all participants. Not only can the ASPSP prove that they received the original request from the TPP, but the TPP can prove that the access token that comes back was the token that was intended to be affiliated to this specific payment.
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 TPP to an ASPSP.
...
- The TPP would have already registered an intent with an ASPSP. This is achieved by using one of the account information or payment initiation APIs.
- The ASPSP would have responsded with an intent id.
Hybrid Grant Parameters
Minimum Conformance
Overview
This section describes the bare minimum set of Authorization Request parameters that an ASPSP must support for the Jan, 2018 release. The technical definitive reference is specified in OpenID Connect Core Errata 1 Section 6.1 (Request Object). All standards and guidance MUST be followed as per the specification.
...
Parameter | Open Banking | Notes |
|---|---|---|
| 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
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. |
Example for minimum conformance
Examples are non-normative
HTTP Request
|
Request JWS (Without Base64 encoding)
Note that "essential" is an optional required OPTIONAL. Indicates 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:
...
|
...
id_token returned - Sub being populated with an EphemeralId of the IntentId - Non Normative
|
id_token returned - Identity Claims and IntentId With sub being populated with an UserIdentifier - Non Normative
|
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 thisMUST 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. |
JSON Security Suite Information v1.0
General Guidance for JWT Best Practice: To Be Followed Where Appropriate
...
General outline for creating a JWS
Step 1: Select the certificate and private key that will be used for signing the JWS
As the JWS is used for non-repudiation, it MUST be signed using one of JWS issuer's private keys.
...
The signing certificate MUST be valid at the time of creating the JWS.
Step 2: Form the JOSE Header
The JOSE header is a JSON object consisting of three fields (claims):
...
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
...