3. Prerequisites and technical details

3.1. Actors registration

PSD2 actors must be registered by a registration authority. The information that has been collected must be accessible to other actors in order to provide trust and interoperability.

A non-registered actor cannot interact with another actor.

Each actor must be provided with at least one eIDAS certificate (QWAC), for TLS 1.2 purpose, delivered by a registered Qualified Trust Service Provider (QTSP).

The European Commission list of QTSPs can be retrieved at the following URL:

https://webgate.ec.europa.eu/tl-browser/

3.2. Cross-Authentication and Data Encryption

The STET PSD2 API relies on TLS 1.2 protocol in order to get cross-authentication between actors. Moreover, this protocol also ensures data confidentiality during their transport on the network.

Whenever a TPP connects as a client to an ASPSP API service, it will check the ASPSP server certificate (QWAC) and present its own eIDAS certificate (QWAC) respecting the ETSI/TS119495 Technical Specification.

The Organisational Identification within the Subject Distinguished Name of the certificate should actually be regarded as an Authorization Number that will respect the following format rules:

"PSD" as 3-character legal person identity type reference;
2-character ISO 3166 [7] country code representing the NCA country;
hyphen-minus "-" (0x2D (ASCII), U+002D (UTF-8)); and
2-8-character NCA identifier (A-Z uppercase only, no separator);
hyphen-minus "-" (0x2D (ASCII), U+002D (UTF-8)); and
PSP identifier (authorization number as specified by the NCA).

In case of authentication failure, on one side or the other, the connection must be closed.

No additional encrypting or authenticating feature is required.

3.3. Customer Authentication Approaches

Three different approaches can be used by a TPP to allow the PSU authentication by the ASPSP. These approaches rely on a PSU identification that must be relevant to the ASPSP (National identifier or Bank customer identifier).

These approaches are implemented in different ways, depending on the relevant use case:

either during the authorisation process (cf. §3.4.2), mostly for AISP and CBPII use cases,
or during the consent confirmation process, for instance in case of a PISP submitting a Payment Request (cf. § 3.4.2).

3.3.1. Redirect Approach

Through the Redirect approach, the PSU authentication process is fully processed by the ASPSP.

In order to allow this, the TPP has to redirect the PSU to the ASPSP authentication service, meaning the PSU will leave temporarily the TPP interface for authenticating towards the ASPSP interface.

The TPP might have already captured a PSU identifier that can be handled by the ASPSP for unambiguously recognizing the PSU. In this case this identifier might be forwarded through the redirection, when the redirect protocol allows the forwarding of this identifier.

After finalisation of the authentication, the ASPSP redirects the PSU back to the TPP interface.

3.3.2. Decoupled approach

Through the Decoupled approach, the PSU authentication process is fully processed by the ASPSP.

In order to allow this the TPP has to capture a PSU identifier that can be handled by the ASPSP for unambiguously recognizing the PSU, and to forward this identifier to the ASPSP.

Based on this identifier, the ASPSP will trigger an authentication through a decoupled device or application, meaning that the PSU will not leave the TPP interface during the authentication process.

3.3.3. Embedded-1-Factor approach

Through this approach, the PSU authentication process involves the TPP that will forward one

authentication factor, this factors being a "Possession" factor, e.g.

a One-Time Password sent by the ASPSP on a separate device or application owned by the PSU
a response to a challenge sent by the ASPSP on a separate device or application owned by the PSU

3.3.4. Exemptions to Strong Customer Authentication

Exemptions to Strong Customer Authentication are specified by the EBA RTS on SCA, especially for Payment Initiation Services.

In this context, the API allows the PISP to forward to the ASPSP any useful information. Moreover, the PISP may also hint the ASPSP on whether or not the relevant payment request could be subject to an exemption.

Eventually, the ASPSP keeps the final decision to apply or not this exemption.

3.4. Authorization

3.4.1. Levels of authorization

The following levels of authorization may be checked and combined in order to compute the effective rights granted to the TPP:

AUTHORIZATION LEVEL	DESCRIPTION
Authorization by TPP role	Once the TPP has been registered for a given role, it can call any of the PSD2 features provided by an ASPSP through the STET PSD2 API for this role.
Authorization by TPP-ASPSP agreement	The TPP can call any of the additional (non PSD2) features provided by an ASPSP through the STET PSD2 API, provided there is a bilateral agreement to use these features.
Authorization by TPP-PSU agreement	If the PSU has contracted with a TPP, he/she must - Give a list of the ASPSPs that he/she allows the TPP to access - Process an authentication against each of those relevant ASPSPs that will further allow the TPP to access the PSU data.
Authorization by PSU context	The PSU is able to specify his/her PSU context detailing, for each of its relevant accounts: - If this account will be accessible or not by the TPP - Which features can be used by the TPP The PSU can modify at any time his/her PSU context.

3.4.2. Technical basis

The TPP is authorized to access the ASPSP's API through an access token that can be retrieved through the OAUTH2 Authorisation Framework (https://tools.ietf.org/html/rfc6749).

Different authorisation grants can be used, depending on the TPP's role and use case to be applied.

The TPP may need to handle multiple OAUTH2 tokens provided by a given ASPSP on behalf of a given PSU. Actually, the request of a new OAUTH2 token must not imply the revocation of a previous one.

3.4.2.1. TPP Identity matching

The OAUTH2 protocol is enforced by checking the identity of the TPP during the OAUTH2 procedures through the TPP's eIDAS certificate, based on MTLS

(https://datatracker.ietf.org/doc/rfc8705/).

This enforcement is obtained by the mandatory provisioning by the TPP of a [client_id] field within all OAUTH2 request. This [client_id] must match, directly or not, with the Authorisation Number located within the TPP's eIDAS certificate and this match must be checked by the ASPSP for each OAUTH2 request.

Direct matching

The match can be obviously direct when the [client_id] is equal to the Authorisation Number.

In this case the ASPSP's API MANAGER might be able to check and accept "on the fly" the OAUTH2 request.

Indirect matching

However, in some cases, especially when the API MANAGER is unable to process an "on the fly" registration, an OAUTH2 technical setup should occur prior to any OAUTH2 token request. This setup will result by the provisioning of a [client_id] value by the ASPSP to the TPP.

The provisioning of multiple [client_id] values that could be used for different use cases by the TPP is possible through replaying the setup.
Moreover, the setup allows the exchange of operational data between the TPP and the ASPSP for further use: logos, phone numbers, email addresses, certificates…

Eventually, this setup can be automated.

3.4.2.2. Automated OAUTH2 technical setup

Principles

While most of the API managers provide an inline setup interface, this setup can also be automated.

The RFC 7591 specifies an interactive dynamic protocol that allows a client to provision some context metadata and get a [client_id] value. As a complement, RFC 7592 specifies how to retrieve, modify or delete a previously posted context.

If several usage contexts are needed for a given API client, this client will have to reiterate the complete process to get as many [client_id] values as needed.

Actually, some TPPs might be client of an API on behalf of an agent (Article 4-38 of PSD2). Each agent should be considered as a specific usage context.

As this protocol is not mandatory, each API implementation will have to specify whether or not it is implemented.

Context metadata

The relevant metadata items to provide are listed below:

CLIENT METADATA NAME	CLIENT METADATA DESCRIPTION	REQUIREMENT	CHANGE CONTROLLER	REFERENCE
redirect_uris	Array of redirection URIs for use in redirect-based flows	Mandatory	IESG	[RFC7591]
software_statement	JSON Web Token (JWT) that asserts metadata values about the client software as a bundle	Optional	IETF	[RFC7591]
token_endpoint_auth_method	Requested authentication method for the token endpoint.	Mandatory According to the RFC8705 (cf. § 2.1.1), the value to be used will be "tls_client_auth" as soon as the draft will be promoted as an RFC.	IESG IETF	[RFC7591] [RFC8705]
tls_client_auth_subject_dn	Indicates the certificate subject value that the authorization server is to expect when authenticating the respective client.	Mandatory An [RFC4514] string representation of the expected subject distinguished name of the certificate, which the OAuth client will use in mutual-TLS authentication.	IETF	[RFC8705]

CLIENT METADATA NAME	CLIENT METADATA DESCRIPTION	REQUIREMENT	CHANGE CONTROLLER	REFERENCE
grant_types	Array of OAuth 2.0 grant types that the client may use	Mandatory Allowed values are: - "authorization_code" - "password" - "client_credentials" - "refresh_token"	IESG	[RFC7591]
response_types	Array of the OAuth 2.0 response types that the client may use	Optional "code" is the sole allowed value	IESG	[RFC7591]
client_name	Human-readable name of the client to be presented to the user	Mandatory Must specify the name of the agent or by default the name of the TPP.	IESG	[RFC7591]
client_uri	URL of a web page providing information about the client	Optional	IESG	[RFC7591]
logo_uri	URL that references a logo for the client	Optional	IESG	[RFC7591]
scope	Space-separated list of OAuth 2.0 scope values	Optional	IESG	[RFC7591]
contacts	Array of strings representing ways to contact people responsible for this client, typically email addresses	Mandatory At least one contact must be provided.	IESG	[RFC7591]
tos_uri	URL that points to a human-readable terms of service document for the client	Optional	IESG	[RFC7591]
policy_uri	URL that points to a human-readable policy document for the client	Optional	IESG	[RFC7591]
provider_legal_id	Authorization number of the TPP according to ETSI specification on eIDAS certificates for PSD2	Mandatory	STET (to be registered)
client_legal_id	Authorization number of the agent see below)	Mandatory in case of an agent which is distinct from the TPP	STET (to be registered)
logo	base64 encoded value of the logo	Optional	STET (to be registered)
jwks	Client's JSON Web Key Set [RFC7517] document value, which contains the client's public keys.	Optional The value of this field MUST be a JSON object containing a valid JWK Set. These keys can be used by higher-level protocols that use signing or encryption.	IESG	[RFC7591]

In a similar way to the ETSI specification on the Authorization Number for TPPs, the agent Authorization Number must respect the following format:

"AGT" as 3-character legal person identity type reference;
2-character ISO 3166 country code representing the NCA country;

hyphen-minus "-" (0x2D (ASCII), U+002D (UTF-8)); and
2-8-character NCA identifier (A-Z uppercase only, no separator);
hyphen-minus "-" (0x2D (ASCII), U+002D (UTF-8)); and
Agent identifier (registration number as specified by the NCA).
Interactions

The TPP submits its context metadata through a

POST /register

In response, it gets this context metadata completed by

the relevant [client_id]
the [registration_client_uri] as an endpoint for configuration of the client
the [registration_access_token] to be used for accessing the configuration of the client.
its issuing timestamp.

RFC7591 allows the server to update some of the context metadata if needed.

At any time, the TPP can retrieve the context metadata through a

GET /register/{client_id}

Updating the context metadata can be done through a

PUT /register/{client_id}

And deleting the context metadata is possible through a

DELETE /register/{client_id}

3.4.2.3. OAUTH2 Authorization Code Grant

The authorisation process might rely on an OAUTH2 sequence for obtaining an Authorization

Code Grant token (cf. https://tools.ietf.org/html/rfc6749#section-4.1) and implements the REDIRECT approach.

This kind of token, depending on the ASPSP implementation:

Can be used for all AISP use cases;

Can be used for the CBPII use case;
Can be used for the PISP confirmation use case.

The process can be summarized through the following steps.

At first, the PSU must specify to the TPP, the identity of one of its ASPSPs.

Authorization Request

The TPP initiates the OAUTH2 sequence by redirecting the PSU to the relevant ASPSP's authorization infrastructure, through the following URL pattern and parameters

Since this is done by a redirection of the PSU, the eIDAS of the TPP cannot be presented at this stage.

Notice: The RFC 6749 does not specify the Authorization Code Grant to support the forwarding of the Resource Owner (PSU) user name or language preferences. However, some OpenID Connect features might be used for these purposes even though the OpenID Connect specification is not fully applied (cf. § 3.4.2.4).

GET /authorize?response_type=code&client_id=&redirect_uri=&scope=[&state=]

NAME		DATA	TYPE AND CONSTRAINS
response_type	[1..1]	Expected type of token	String[10] Must be valued with "code"

NAME		DATA	TYPE AND CONSTRAINS
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification
redirect_uri	[0..1]	Call-backURLoftheTPP	String[140]
scope	[0..1]	Specifies the generic accreditations that both the PSU and the TPP agreed on: - For AISP `o` aisp `o` extended_transaction_history - for CBPII `o` cbpii - for PISP `o` pisp	String[140] Space delimited roles list. Mandatory
state	[0..1]	Internal state that can be used by the TPP for contextmanagement.	String[1024] Recommended

The ASPSP

Identifies and authenticates the PSU
Computes the relevant TPP checks (roles, validity, non-revocation…)
Checks the [redirect_uri] against the ones that might have been declared during the automated OAUTH2 technical setup (cf. § 3.4.2.2). The provided [redirect_uri] must exactly match one those that have been registered.

Authorization Response

Afterwards, the ASPSP redirects the PSU to the TPP, using the previously given call-back URL (redirect_uri) and the following parameters:

NAME		DATA		TYPE AND CONSTRAINS
code	[1..1]	Short-time code to use in order to get the access token	String[36]
state	[0..1]	Internal state if provided by the TPP	String[1024] Recommended

The recommended lifetime of the authorization code as specified by the RFC 6749 is 10 minutes but it is up to the authorization server to set its own lifetime value.

Access Token Request

In order to get the access token, the TPP is now able to call, through a POST request, the ASPSP's authorization infrastructure with the following parameters.

POST /token HTTP/1.1

Host: server.example.com

grant_type=authorization_code &code= &redirect_uri= &client_id=

NAME		DATA
grant_type	[1..1]	Requested authorization type	String[36] Must be valued with "authorization_code"
code	[1..1]	Short-time code previously provided by the ASPSP	String[36]
redirect_uri	[0..1]	Call-back URL of the TPP	String[140] Must be equal to the one provided during the authorization code request
client_id	[1..1]	TPP identification.	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSIspecification

The ASPSP
- Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
- Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value.
- Computes the relevant TPP checks (roles, validity, non-revocation…)

Access Token Response

The ASPSP answers through a HTTP200 (OK) response that embeds the following data.

NAME		DATA
access_token	[1..1]	Access token provided by the ASPSP to the TPP.	String[140]
token_type	[1..1]	Type of the provided access token ("Bearer" or "MAC")	String[10] Must be valued with "Bearer"
expires_in	[0..1]	Token lifetime, in seconds. The token can be used several times as far as it is not expired.	Numeric
refresh_token	[0..1]	Refresh token that can be used for a future token renewal request.	String[140]

3.4.2.4. OpenID Connect extension to the OAUTH2 Authorization Code Grant

« As an optional feature, an authorization server may implement the OpenID Connect Core 1.0 » specification on top of the OAUTH2 "Authorization Code" flow.

The OpenID Connect protocol allows the API client (TPP) to get from the API server (ASPSP) an IdToken that will certify the identity of the PSU, once this PSU has been authenticated by the ASPSP.

Authentication request

The Open Id Connect Authentication Request relies on the OAUTH2 "Authorization Code" Authorization Request with some additional parameters, marked as bold in the following diagram)requirement.

NAME		DATA	TYPE AND CONSTRAINS
response_type	[1..1]	Expected type of token	String[10] Must be valued with "code"
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSIspecification
redirect_uri	[0..1]	Call-back URL of the TPP	String[140]

NAME		DATA	TYPE AND CONSTRAINS
scope	[0..1]	Specifies the generic accreditations that both the PSU and the TPP agreed on: - For AISP `o` aisp `o` extended_transaction_history - for CBPII `o` cbpii. - In any case `o` openid `o` offline_access	String[140] Space delimited roles list. additional scopes are required -openid for specifying the use of OpenID Connect -offline_access to allow the retrieval of a refresh token within the OpenID context.
state	[0..1]	Internal state that can be used by the TPP for context management.	String[1024]
nonce	[0..1]	Association of a client session with an Id token used to mitigate replay attacks	String[36]
max-age	[0..1]	Maximum authentication age (in seconds)	String[15]
ui_locales	[1..1]	End-User's preferred languages and scripts for the user interface.	String [140] End-User's preferred languages and scripts for the user interface, represented as a space-separated list [RFC 5646] Required by the API
id_token_hint	[0..1]	last known IdToken for the end-user (PSU), if any.	String [2048]
login_hint	[0..1]	Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).	String[36]

The [id_token_hint] parameter is quite useful to ease a PSU authentication request renewal by forwarding his/her already known identification. For a first authentication request the [login_hint] parameter can be used by the TPP to forward the PSU identification, as known by the ASPSP.

As for the OpenID Connect Authentication Request is based on the OAUTH2 Authorization Request, the latest is enhanced in the following way:

GET /authorize? response_type=code &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &scope= openid%20%offline_access%20% aisp20aisp & nonce=n-0S6_WzA2Mj & state=af0ifjsldkj HTTP/1.1 Host: server.example.com

Enhanced OAUTH2 Authorization Code Grant

Even though the OpenID Connect cannot be fully implemented, it may be worth using some of its specific parameters in order to enrich an OAUTH2 authorization request if the server allows it. The benefit of having the PSU identification, through the [login_hint] parameter, and language preferences, through the [ui_locales] parameter, should be seen as a real advantage.

Authentication Response

Case of a successful processing of the request, the server will return an authorization code through the redirection of the PSU towards the TPP.

HTTP/1.1 302 Found Location: https://client.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

Token request

The TPP requests the exchange of the authorization code against an OAUTH2 token.

POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

NB: The « Authorization » header is useless since authentication is provided through MTLS, based on the TPP eIDAS certificate (https://datatracker.ietf.org/doc/rfc8705/).

Token response

The Authorization server answers with:

An OAUTH2 access token
An OAUTH2 refresh token
An IdToken

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache

{

"access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }

IdToken structure

The structure of the IdToken is a Json Web Token (JWT).

In the previous example, the following data is included:

{ alg: "RS256", kid: "1e9gdk7" }. { iss: "http://server.example.com", sub: "248289761001", aud: "s6BhdRkqt3", nonce: "n-0S6_WzA2Mj", exp: 1311281970, iat: 1311280970 }. [signature]

The possible data items are described in the following table:

FIELD	REQUIREMENT	DESCRIPTION
iss	Mandatory	Tokenprovider identifier
sub	Mandatory	Token subject identifier
aud	Mandatory	Token recipient[client_id]
nonce	Conditional	Mandatory retrieval of the [nonce] parameter if present in the initial Authentication Request
exp	Mandatory	IdToken expiration date[RFC3339]
iat	Mandatory	IdToken creation date[RFC3339]
auth_time	Conditional	End-user (PSU) authentication date and time[RFC3339] when the [max_age] parameter is present in the initial Authentication Request

3.4.2.5. OAUTH2 Resource Owner Password Grant

The registration process relies on an OAUTH2 sequence for obtaining a Resource Owner Password Grant token (cf. https://tools.ietf.org/html/rfc6749#section-4.3) and implements the EMBEDDED approach.

This kind of token, depending on the ASPSP implementation:

Can be used for all AISP use cases ;
Can be used for the CBPII use case.

In order to enforce the flow and respect the two-factor authentication constraint, the "password" to be used must not be a static password but the concatenation of:

a possession factor obtained through an ad-hoc device provided to the PSU by the ASPSP,
and a knowledge factor (e.g. PIN)

However, it is important to notice that OAuth 2.0 Security Best Current Practice will likely deprecate this flow in the near future.

The process can be summarized through the following steps.

At first, the PSU must specify, to the TPP, the identity of one of his/her ASPSPs and provides him with

His/her identifier against the ASPSP services
A "password" that is the result of a Strong Customer Authentication applied to the PSU by the ASPSP.

Access Token Request

The TPP initiates the OAUTH2 sequence by sending the following request directly to the ASPSP's Authorisation Service.

POST /token HTTP/1.1 Host: server.example.com

grant_type=password &username= &password= &client_id= &scope=

NAME		DATA	TYPE AND CONSTRAINS
grant_type	[1..1]	type of requested grant	String[10] Must be valued with "password"
username	[1..1]	PSU identification	String[36]
password	[1..1]	PSU "password"	String[20] Result of the concatenation of a "knowledge factor" and a"possession"factor
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification
scope	[0..1]	Specifies the generic accreditations that both the PSU and the TPP agreed on: - For AISP `o` aisp `o` extended_transaction_history - for CBPII `o` cbpii	String[140] Space delimited roles list.

The ASPSP

Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value.
Computes the relevant TPP checks (roles, validity, non-revocation…)

The ASPSP checks the identifier of the PSU and parse the "password" in order to retrieve and

checks the "Knowledge" factor and the "Possession" factor, thus processing the SCA.

Access Token Response

In case of successful SCA, the ASPSP answers through a HTTP200 (OK) response that embeds the following data.

NAME		DATA
access_token	[1..1]	Access token provided by the ASPSP to the TPP.	String[140]
token_type	[1..1]	Type of the provided access token ("Bearer" or "MAC")	String[10] Must be valued with "Bearer"
expires_in	[0..1]	Token lifetime, in seconds. The token can be used severaltimes asfarasitisnot expired.	Numeric
refresh_token	[0..1]	Refresh token that can be used for a future token renewal request.	String[140]

3.4.2.6. OAUTH2 Client Credentials Flow

The registration of the TPP by the ASPSP relies on an OAUTH2 sequence for obtaining a Client Credential grant token (cf. https://tools.ietf.org/html/rfc6749#section-4.4).

This kind of token, depending on the ASPSP implementation:

Can be used for the CBPII use case ;
Can be used for the PISP confirmation use case (basic REDIRECT Approach);
Must be used for all others PISP use cases.

This procedure can be summarized through the following steps.

Access Token Request

The TPP sends directly, through a POST request, its access token request to the ASPSP

authorization infrastructure with the following URL pattern and parameters

POST /token Host: authorization-server.com grant_type=client_credentials &scope= &client_id=

NAME		DATA	TYPE AND CONSTRAINS
grant_type	[1..1]	Requested authorization type	String[36] Must be valued with "client_credentials"
scope	[0..1]	Specifies the generic accreditations that both the PSU and the TPP agreed on: PISP.	String[140] Space delimited roles list. Default value is"pisp"
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification

The ASPSP

Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
- Checks the matching, direct or indirect, between the Authorization Number within the eIDAS certificate and the [client_id] value.
Computes the relevant TPP checks (roles, validity, non-revocation…)

Access Token Response

The ASPSP answers through a HTTP200 (OK) response that embeds the following data.

NAME		DATA
access_token	[1..1]	Access token provided by the ASPSP to the TPP.	String[140]
token_type	[1..1]	Type of the provided access token ("Bearer" or "MAC")	String[10] Must be valued with "Bearer"
expires_in	[0..1]	Token lifetime, in seconds. The token can be used several times as far as it is not expired.	Numeric

3.4.2.7. Use of the Access Token

The access token must be used within each request within the "Authorization" header, prefixed

by the token type "Bearer".

The [client_id] that is linked to the access token must directly or indirectly match with the

Authorisation Number that is located within the TPP's eIDAS certificate (QWAC).

If the access token is expired, the request will be rejected with HTTP401 with an error equal to "invalid_token" and the request can be replayed once the access token has been refreshed.

If the access token scope cannot cover the request (case of extended transaction history request for instance):

The request will be rejected with HTTP403 with an error equal to "insufficient_scope"
The refresh token will be revoked so the request could be replayed once a new token, having the right scope, would have been requested and provided.

3.4.2.8. Refreshing the Access Token

Refreshing the access token is only possible when the access token was granted through an

OAUTH2 "Autorization Code", OpenID Connect or "Resource Owner Password" Grants.

According to the RFC 6749 (cf. https://tools.ietf.org/html/rfc6749#section-6), the Refresh Token can be used by the TPP in order to get a refreshed Access Token by the following request.

POST /token HTTP/1.1

Host: server.example.com grant_type=refresh_token &client_id= &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA &scope=

NAME		DATA	TYPE AND CONSTRAINS
grant_type	[1..1]		Must be valued with "refresh_token"
refresh_token	[1..1]	Value ofthe providedrefreshtoken
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification
scope	[0..1]	Specifies the generic accreditations that both the PSU and the TPP agreed on: "aisp" or "cbpii". "extended_transaction_history" is not allowed in this case.	String[140] Space delimited roles list.

The ASPSP

Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value.
The ASPSP answers through a HTTP200 (OK) response that embeds the following data.

NAME		DATA		TYPE AND CONSTRAINS
access_token	[1..1]	Access token provided by the ASPSP to the TPP.	String[140]

NAME		DATA
token_type	[1..1]	Type of the provided access token ("Bearer" or "MAC")	String[10] Must be valued with "Bearer"
expires_in	[0..1]	Token lifetime, in seconds. The token can be used several times as far as it is not expired.	Numeric
refresh_token	[0..1]	Refresh token that can be replace the previous refreshtoken.	String[140]

If the refresh token has been revoked, the request will be rejected with HTTP400 and an error equal to "invalid grant".

3.4.2.9. Refresh Token Revocation

The refresh token provided to an AISP is de facto revoked by the ASPSP

After timeout of the by-law specified delay between two SCAs.
After timeout of the ASPSP specified delay based on internal rules if any.
After reject of a request for insufficient scope in order to allow the AISP to request another token with the desired scope.
On request of a PSU wanting to revoke the TPP access on his/her account data.

The TPP is also able to ask for the revocation of the refresh token, according to RFC 7009 (cf.

https://tools.ietf.org/html/rfc7009) through the following request.

POST /revoke HTTP/1.1 Host: server.example.com

token=45ghiukldjahdnhzdauz &token_type_hint=refresh_token &client_id=

NAME		DATA	TYPE AND CONSTRAINS
token	[1..1]	Tokento berevoked by theASPSP.	String[140]
token_type_hint	[0..1]	Information about the type of token to be revoked	Must be valued with "refresh_token"
client_id	[1..1]	TPP identification	String[36] must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification

The ASPSP
- Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)

Checks the direct or indirect matching of the [client_id] value with the Authorisation Number that is located within the TPP's eIDAS certificate (QWAC).
Revokes the refresh token

3.4.2.10. Oauth2 for native apps

The RFC 8252 (https://tools.ietf.org/html/rfc8252) extends the use of the OAuth Authorization

request to applications that are installed on a given device (e.g. a smartphone).

Based on this RFC, one might consider having a straight through authorization process by using

Universal Link (IOS based devices)
App Link (Android based devices)

However, the API specification does not mandate this mechanism.

3.4.3. AISP authorization levels

Since a TPP is acting on behalf of a PSU being a PAO, the PSD2 use cases that are linked with AISP role require the following authorization levels:

Authorization by Role
Authorization by TPP-PSU agreement
Authorization by PSU context

3.4.3.1. List of the relevant ASPSPs

When contracting with a TPP, the PSU will provide a list of the ASPSPs that it allows the TPP to access. This list may not be exhaustive and so may not include some of the PSU's ASPSPs.

3.4.3.2. Registration of the TPP-PSU agreement by each ASPSP

This registration is due to enable the further access of the TPP to the PSU's data that is hosted by a given ASPSP by providing the TPP with an OAUTH2 access token.

The access token can be retrieved by one of the following Grants:

OAUTH2 Authorization Code grant (REDIRECT approach)
- This grant can be enhanced with the following additional parameters borrowed from OpenID Connect:
  - [login_hint]
  - [ui_locales]
OpenID Connect Grant (REDIRECT approach)
OAUTH2 Resource Owner Password (EMBEDDED approach)

Each ASPSP will have to document its own choice on this topic.

3.4.3.3. AISP OAUTH2 Scopes

It is requested that AISP, CBPII or PISP roles will not be mixed within a single scope definition OAUTH2 access token request.

The OAUTH2 scope requested by an AISP can be one of the following values:

"aisp"
"aisp extended_transaction_history"

The first scope value allows the AISP accessing all accessible accounts and data allowed by the PSU until expiration of the by-law specified delay between two SCAs. However, the value does not allow requesting an extended transaction history, i.e. history including transactions older than 90 days.

The second scope value allows the AISP accessing all accessible accounts and data allowed by the PSU until expiration of the by-law specified delay between two SCAs. It also allows requesting an extended transaction history.

However, this "aisp extended_transaction_history" scope will be restricted to "aisp" by the ASPSP during the first token refresh. Thus:

The AISP will be able to ask for an extended transaction history with the very first access token retrieved after a token request. So, in this case a single SCA will be required and used to get the token and to ask for an extended transaction history.
Any further extended transaction history request will be considered as out of scope (cf. §3.4.2)

The PSU detailed consent will specify which account or functionality will be accessible to the AISP. It can be seen as a collection of individual accreditations.

This collection is specific to a given PSU, a given TPP and a given ASPSP.

Each single accreditation relies on a specific account that is owned by the PSU and is held by the ASPSP. It specifies which pieces of data (transactions, balances) the TPP is allowed to carry out on this account.

The PSU manages this context with the AISP which is responsible of:

The capture of the PSU choices:
- The PSU specifies to the AISP which account and feature should be accessed or not.
The execution of the PSU choices:
- The AISP has the responsibility to respect the PSU choices and not to access any feature that it has not been granted for.

At any time, the PSU can edit his/her consent choices but this can only be done with the AISP.

Furthermore, the PSU consent may or may not be forwarded by the AISP to the ASPSP, according to one of the two following consent management models.

Full-AISP model (A1)

In this model, the ASPSP does not require to be informed of the details of the PSU consent.

Whatever the AISP request, the ASPSP will respond, being unable to check the compliance of the request against the PSU choices.

Actually, when getting the PSU context from the ASPSP (through the call [get /accounts]), the AISP will get all relevant HAL links for each eligible account. These HAL links will help the AISP to request the needed features on those accounts: balances and/or transactions.

Mixed model (A2)

In this model, the ASPSP does require to be informed of the details of the PSU consent. Therefore, the ASPSP has implemented an ad-hoc API entry-point that can be called by the AISP in order to forward the PSU choices.

Model choice

It is the charge of the ASPSP to implement or not the mixed model (A2). However, if this model has been implemented by the ASPSP, it is the charge of the AISP to forward the details of the PSU consent to the ASPSP whenever the PSU gives or edits this consent.

Once the details of the PSU consent has been received and saved by the ASPSP, the AISP, when getting the PSU context from the ASPSP (through the call [get /accounts]), will only get HAL links for authorized accounts and features.

3.4.4. CBPII authorization levels

Since a CBPII is acting on behalf of a PSU being a PAO, the PSD2 use cases that are linked with AISP and CBPII roles require the following authorization levels:

Authorization by Role
Authorization by TPP-PSU agreement
Authorization by PSU context

However, in some cases, the CBPII might have been previously enrolled by the PSU to the relevant ASPSP (cf. §3.4.4.3).

3.4.4.1. List of the relevant ASPSPs

When contracting with a TPP, the PSU will provide a list of the ASPSPs that it allows the TPP to access. This list may not be exhaustive and so may not include some of the PSU's ASPSPs.

3.4.4.2. Registration of the TPP-PSU agreement by each ASPSP

This registration is due to enable the further access of the TPP to the PSU's data that is hosted by a given ASPSP by providing the TPP with an OAUTH2 access token.

The access token can be retrieved:

Either through an OAUTH2 Authorization Code flow (REDIRECT approach)
Or an OAUTH2 Resource Owner Password (EMBEDDED approach)

3.4.4.3. Pre-enrolled CBPII authorization level

When the PSU has previously enrolled the CBPII to his/her relevant ASPSP, the latest may prefer to apply a simpler authorization scheme.

The access token can then be retrieved through an OAUTH2 Client Credentials flow, aiming that PSU authentication is useless since the PSU consent was already captured.

3.4.4.4. CBPII scope

It is requested that AISP and CBPII roles will not be mixed within a single scope definition OAUTH2 access token request.

The OAUTH2 scope requested by a CBPII can only be "cbpii".

3.4.5. PISP authorization levels and Fraud Management

3.4.5.1. Posting and getting a Payment/Transfer Request

For posting or getting a Payment Request on behalf of a Merchant, or a Transfer Request on behalf of an Ordering Party, the PISP can use an access token that can be retrieved from the ASPSP through an OAUTH2 Client Credentials flow.

3.4.5.2. Cancellation of a Payment Request

In case the PISP has to cancel a payment request, the Access token to be used can be retrieved from the ASPSP through an OAUTH2 Client Credentials flow as well.

However, the ASPSP may require an authentication of the PSU that can be performed through REDIRECT (simple, cf. infra), DECOUPLED or EMBEDDED-1-FACTOR approaches.

In this perspective, the PISP will

suggest the authentication approaches it supports
and provide the call-back URLs to use for the REDIRECT approach.
- At least one call-back URL must be provided
- A second one may be provided that will be used in case of exception during the process.

The ASPSP will then answer

either with the decision of not processing the PSU authentication,
or with the chosen authentication approach completed with the redirection URL to use in case of REDIRECT approach.

3.4.5.3. Confirmation of a Payment Request

For confirmation of a Payment Request, the law requires the PSU to be authenticated by the ASPSP.

This authentication shall be strong, unless exemption cases and can be performed through REDIRECT (OAuth2 enforced, cf. infra), DECOUPLED or EMBEDDED-1-FACTOR approaches.

The PISP will suggest the authentication approaches it supports. The ASPSP will then answer with the chosen authentication approach completed with the redirection URL to use in case of REDIRECT approach.

Once the PSU has confirmed the Payment Request through authentication, the PISP must itself confirm the payment-request after having checked, for instance, the absence of potential security flaw.

The posting of the PISP confirmation needs an access token as well.

For DECOUPLED or EMBEDDED-1-FACTOR approaches, this access token might be the one that was previously retrieved through the Client Credentials flow and used for posting the payment request.
For REDIRECT approach, the use of another access token, provided through an OAUTH2 Authorization Code flow that will embed the PSU authentication is mandatory.

3.4.5.4. Simple REDIRECT Approach

This approach can only be used for a Payment Request cancellation.

The PSU authentication is then processed through a simple redirection of the PSU to the ASPSP authentication server by using the URL that was initially provided by the ASPSP.

The ASPSP authenticates the PSU and then redirects the latest by using one of the call-back URLs that were provided by the PISP.

3.4.5.5. OAUTH2 Enforced REDIRECT Approach

This approach is mandatory for a Payment Request confirmation in REDIRECT approach.

An Authorization Code token will be used for the confirmation. The PSU authentication is processed through the Authorization Code flow with the ASPSP authentication server.

Purpose and risk analysis

The payment initiation may indeed face some security issues in REDIRECT approach.

A first attack (session fixation) might happen, based on the fact that a given PSU will forward the redirection request to another PSU who can be in a situation to authenticate and pay the purchase made by the first PSU.

Moreover, even if the first attack is mitigated, the attacker might also try to simulate the redirection (fake redirect) to the TPP in order to induce the confirmation of the payment request to the ASPSP.

Session fixation protection

In order to avoid the session fixation attack, the PISP must ensure there is no "PSU-switch" during redirection. This can be done by managing a nonce that

will be stored in the PSU user agent session before the redirection to the ASPSP and
- will be retrieved from the PSU user agent after the redirection.

In case the retrieval failed, the chances are good there was such an attack. The PISP should then cancel the payment request for fraud reason.

Otherwise, in case of successful nonce retrieval, the PISP can confirm the payment request to the ASPSP who is then able to trigger the relevant Credit Transfers.

Fake redirect protection

In order to post the confirmation, the PISP has to request an Authorization Code token from the ASPSP.

In response to the payment request, The ASPSP has provided the PISP with the URI of the Authorisation server. Some OAuth2 parameters must have been pre-valued:

[response_type] valued with "code"

[scope] valued with "pisp"
[context] valued with a hint to the payment-request

The PISP will complete this URL with its own OAuth2 parameters

[client_id]
[state] if needed
[redirect_uri] as call-back URL.

The OAuth2 Authorization Code grant can then complete (cf. §3.4.2.3).

After the retrieval of the Authorization Code through the redirection of the PSU back to the PISP, the latest must then ensure, by the nonce check mechanism, there was no "PSU-switch" during the redirection, as previously explained.

The PISP can then exchange the Authorization Code against the Access token.

the lifetime of the access token is specified by the Authorization Server in order to limit the usability period.
no refresh token has to be provided.

The confirmation is then posted, using this Access token.

In case of face redirect attack, the Access token could not have been retrieved by the PISP. Even in confirmation attempt, the ASPSP can detect the absence of the token and will then reject the payment request for FRAUD reason.

Otherwise, the confirmation sent by the PISP will lead to the normal triggering of the relevant Credit Transfers.

3.4.5.6. OAUTH2 DECOUPLED Approach

In this approach, the Client Credential token can be used for all PISP use cases:

Posting a payment request
Getting the previously posted payment-request
Modifying for cancellation the payment request
Confirming the payment request

The PSU authentication is processed through a decoupled channel initiated by the ASPSP.

After PSU authentication, the PISP is informed by a direct call by the ASPSP. The PISP can then confirm the payment request that will lead to the normal triggering of the relevant Credit Transfers.

3.4.5.7. OAUTH2 EMBEDDED-1-FACTOR Approach

In this approach, the Client Credential token can be used for all PISP use cases:

Posting a payment request
Getting the previously posted payment-request
Modifying for cancellation the payment request
Confirming the payment request

The PSU authentication is triggered through the sending of a One-Time-Password (OTP) or a challenge by the ASPSP to the PSU via a dedicated channel.

The PSU forwards the OTP or the response to the challenge to the PISP. The later can then include this piece of data within the confirmation to be addressed to the ASPSP who is then able to trigger the relevant Credit Transfers.

3.4.5.8. Recapitulative Table

	ENFORCED REDIRECT	DECOUPLED	EMBEDDED- 1-FACTOR
Nonce mechanism protection applied by PISP	The nonce must be computed by the PISP and stored within the PSU user- agent as far as the PISP accepts Simple REDIRECT or Enforced REDIRECT approaches when posting or cancelling a payment request.
Successful and Unsuccessful Report Uri provided by PISP	To be used by the ASPSP through PSU redirection	To be used directly by the ASPSP	Useless
Accepted Authentication Approach set by PISP	Must include "REDIRECT"	Must include "DECOUPLED"	Must include "EMBEDDED-1- FACTOR"
Applied Authentication Approach set by ASPSP	"REDIRECT"	"DECOUPLED"	"EMBEDDED-1- FACTOR"
Use of OAUTH2 Client Credentials token	In any case except for confirmation	In any case
Use of OAUTH2 Authorization Code token	Mandatory for confirmation	Not used
consentApproval set by ASPSP	Set with the ASPSP authorization server	Not used
Challenge set by ASPSP	Not used
psuAuthenticationFactor set by PISP	Not used		Valued with the OTP or response to a challenge

3.5. Applicative authentication

Each request sent by the TPP has to be signed using http-signature mechanism which is specified by the following IETF draft-paper:

https://datatracker.ietf.org/doc/draft cavage http signatures/

ASPSP might also apply http-signature to their responses.

3.5.1. Signature computation

The way it should be implemented is the following

Computing a SHA256 digest of the HTTP body and adding this digest as an extra HTTP header.
Using a specific Qualified Certificate (QSealC), respecting the ETSI/TS119495 Technical Specification, in order to apply an RSA-SHA256 signature on
- all the following headers that are present within the HTTP request sent by the TPP, including the previously computed digest
  - Date (if available)
  - Content-Type (when there is a payload)
  - Content-Length (when there is a payload)
  - X-Request-Id
  - All available "PSU"-prefixed Headers (cf. § 3.6)
  - the specific "(request-target)" pseudo-header which is specified by the IETF draft-paper
- all the following headers that are present within the HTTP response given by the ASPSP, including the previously computed digest
  - Date (if available)
  - Content-Type (when there is a payload)
  - Content-Length (if available)
  - X-Request-Id
Adding this signature within an extra HTTP header embedding
- The key identifier which must specify the way to get the relevant qualified certificate (see below)
- The algorithm that has been used
- The list of headers that have been signed
- The signature itself.

Since version #11 of the draft, two new pseudo-headers have been introduced in order to

strengthen the signature: (created) and (expires). However, work is still going on this subject and the use of these two fields is not yet recommended.

3.5.2. Value of key identifier

It is requested that this identifier is valued with:

Either the keyId that has been assigned by the authorization server during the OAUTH2 technical setup (cf. § 3.4.2.2).
Either a URL aiming to provide the relevant Qualified Certificate.
- In order to assure an easy discrimination of the certificate among others, it is requested that the last part of the URL to the certificate be suffixed by an underscore followed by the SHA-256 fingerprint of the certificate. ▪ E.g.:
  - https://path.to/myQsealCertificate_714f8154ec259ac40b8a9786c9908 488b2582b68b17e865fede4636d726b709f
- This URL could have been provided during the OAUTH2 technical setup within the "5xu" field of the JKS provided by the TPP (cf. RFC7517).

3.5.3. Exception handling

If the ASPSP notes that the signature is either absent or invalid, it shall reject the request with HTTP400.

EXTRA HTTP HEADER	DATA	COMMENT
Digest	Digest of the body
Signature	http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage- http-signatures/)	The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an http or https URL aiming to provide the relevant Qualified Certificate. The certificate format must be PEM

3.6. Fraud-detection-oriented information

The following extra HTTP-headers must be used within the HTTP request sent by the TPP, provided the relevant pieces of data are available within the connection between the PSU and the TPP. This forwarding allows the ASPSP to integrate this information into its own fraud detection process.

Moreover, these headers can be considered as proof of the PSU being connected.

EXTRA HTTP HEADER	DATA	COMMENT
PSU-IP-Address	IP Address of the PSU terminal when connecting to the TPP	In regards with GDPR rules, this must be subject to PSU's consent
PSU-IP-Port	IP Port of the PSU terminal when connecting to the TPP
PSU-HTTP-Method	HTTP Method used for the most relevant PSU's terminal request to the TTP
PSU-Date	Timestamp of the most relevant PSU's terminal request to the TTP
PSU-User-Agent	"User-Agent" header field sent by the PSU terminal when connecting to the TPP
PSU-Referer	"Referer" header field sent by the PSU terminal when connecting to the TPP
PSU-Accept	"Accept" header field sent by the PSU terminal when connecting to the TPP
PSU-Accept-Charset	"Accept-Charset" header field sent by the PSU terminal when connecting to the TPP
PSU-Accept-Encoding	"Accept-Encoding" header field sent by the PSU terminal when connecting to the TPP
PSU-Accept-Language	"Accept-Language" header field sent by the PSU terminal when connecting to the TPP
PSU-GEO-Location	The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available.	In regards with GDPR rules, this must be subject to PSU's consent
`PSU-Device-ID`	UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device.	In regards with GDPR rules, this must be subject to PSU's consent

3.7. Other specific HTTP headers to be used

EXTRA HTTP HEADER	DATA	COMMENT
X-Request-ID	Correlation header to be set in a request and retrieved in the relevant response.

3.8. Specific HTTP return codes and messages to be used

MESSAGE	HTTP CODE	SIGNIFIANCE
FORMAT_ERROR	400	Format of certain request fields are not matching the XS2A requirements. An explicit path to the corresponding field might be added in the return message.
RESOURCE_UNKNOWN	404	If resourceId in path
PERIOD_INVALID	400	Requested time period out of bound.
ACCESS_EXCEEDED	429	The access on the account has been exceeding the consented multiplicity per day.
REQUESTED_FORMATS _INVALID	406	The requested formats in the Accept header entry are not matching the formats offered by the ASPSP.

3.9. STET PSD2 API technical summary

TOPIC	CHOICE	COMMENT
Access network	Internet
Network protocol	HTTP 1.1 (Minimum)
Data encryption Cross-authentication	TLS 1.2	Could be enforced through STS and/or PFS
Authorization protocol	OAUTH2	In respect of RFC 6749, 7009 One of the following token modes - Authorization Code Grant (AISP, CBPII) - Resource Owner Password (AISP, CBPII) - Client credential (PISP, CBPII) Based on MTLS,the identity of the TPP is provided by its eIDAS certificate during OAUTH2 procedures. https://datatracker.ietf.org/doc/rfc8705/
Applicative protocol	REST	In respect of the Richardson Maturity Model, on level three in order to provide HYPERMEDIA links.
Applicative authentication	http-signature	Notice this is actually an IETF draft, waiting for approval and so subject to some modifications. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/
PSU Strong Customer Authentication approaches	REDIRECT, DECOUPLED, EMBEDDED-1-FACTOR
Data format	JSON/UTF8	With use of ISO20022 based data structures
Technical documentation	SWAGGER 2.0	Date/Time format must respect ISO8601 and RFC3339 in accordance with OpenApi specifications. The creator of a Date/Time shall choose - Any time-zone format although UTC format is recommended. - Any second fraction format, including no second fraction. A simple date can be specified as an UTC date/time with a time part equal to "00:00:00Z". The recipient of a Date/Time must be able to interpret its value as far as it is compliant with ISO8601 and RFC3339.