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 OAUTH2 protocol is enforced by checking the identity of the TPP during the OAUTH2 procedures through the TPP's eIDAS certificate, based on MTLS draft (https://datatracker.ietf.org/doc/draft-ietf-oauth-mtls/).

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…

Moreover, this setup can be automated.

3.4.2.1. 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-basedflows	Mandatory	IESG	[RFC7591]
token_endpoint_auth_method	Requested authentication method for the token endpoint.	Mandatory According to the MTLS draft (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] [MTLS] draft
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	[MTLS] draft
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 METADATA NAME	CLIENT METADATA **DESCRIPTION **	REQUIREMENT	CHANGE CONTROLLER	REFERENCE
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 theTPP.	IESG	[RFC7591]
client_uri	URL of a web page providing information about the client	Optional	IESG	[RFC7591]
logo_uri	URL that references alogoforthe 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 ofthelogo	Optional	STET (to beregistered)
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] and

• 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.2. 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.3).

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

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		TYPE AND CONSTRAINS
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	[1..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		TYPE AND CONSTRAINS
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.3. 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.

s:

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 (inseconds)	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.

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.4. 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		TYPE AND CONSTRAINS
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.5. 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		TYPE AND CONSTRAINS
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.6. 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.7. 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		TYPE AND CONSTRAINS
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.8. 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	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.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)

3.4.3.4. PSU detailed consent

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, getting or modifying a Payment/Transfer Request

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

3.4.5.2. 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, DECOUPLED or EMBEDDED-1-FACTOR approaches.

Once the PSU has confirmed the Payment Request, the PISP must itself confirm the paymentrequest 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 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 strongly recommended.

  • However, using the Client Credential token is still possible when the ASPSP implementation allows it.

  • Depending on the token type, the resource to be called is different:

    • "confirmation" for Client Credential token,

    • "o-confirmation" for Authorization Code token.

3.4.5.3. OAUTH2 Simple REDIRECT 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 simple redirection of the PSU to the ASPSP authentication server.

However, there is a risk attack (session fixation) based on the fact that a given PSU might forward the redirection request to another PSU who can be in a situation to pay the purchase made by the first PSU.

In order to avoid this, the PISP must ensure there is no "PSU-switch". 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 an attack and the PISP should then cancel the payment request for fraud reason. Otherwise, the PISP can confirm the payment request to the ASPSP who is then able to trigger the relevant Credit Transfers.

However, there is still a risk that the attacker simulates a redirection to the TPP which will successfully retrieve the nonce and confirms the payment request to the ASPSP.

The simple approach does not provide any mean for the ASPSP to detect this second attack by a fake redirection, although the probability of this second attack is still low.

3.4.5.4. OAUTH2 Enforced REDIRECT Approach

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

• Posting a payment request

• Getting the previously posted payment-request

• Modifying for cancellation the payment request

This approach complete the previous approach by replacing the simple redirection to the

ASPSP authentication server by the provision of an OAUTH2 Authorization Code token, which actually implies the PSU authentication.

• The ASPSP provides the TPP with the URI of the Authorisation server. Some parameters must be 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 parameters

  • [state] if needed

o [redirect_uri] which will be used in place of the [successfulReportUrl] field of the payment request. By the way, the [unsuccessfulReportUrl] field of the payment request will neither be used since OAUTH2 error mechanism will take place in case of failed authentication of the PSU.

No refresh token is provided and the confirmation of the payment request posting or

cancellation will need the Authorization Code token, whose lifetime is specified by the Authorization Server in order to limit the usability period.

As in the previous approach, the PISP must ensure, by the same nonce mechanism, there was no "PSU-switch" during the redirection.

However, unlike the previous approach, the ASPSP is now able to detect a second attack based on a fake redirection since in this case the OAUTH2 Authorization Code token cannot be provided to the PISP and used for the confirmation. The ASPSP is then able to reject the payment request for FRAUD reason.

In case of no attack, the confirmation sent by the PISP will lead to the normal triggering of the relevant Credit Transfers.

3.4.5.5. 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.6. 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 an 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.7. Recapitulative Table

	SIMPLE REDIRECT	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	In any case except for confirmation	In any case

	SIMPLE REDIRECT	ENFORCED REDIRECT	DECOUPLED	EMBEDDED- 1-FACTOR
Use of OAUTH2 Authorization Code token	Not used	Mandatory for confirmation	Not used
consentApproval set by ASPSP	Set with the ASPSP authentication server	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.

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 a 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 (when there is a payload)

    • 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. It is requested that this identifier is

    • 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 fingerprint of the certificate.

      • E.g.: https://path.to/myQsealCertificate_ 612b4c7d103074b29e4c1ec e1ef40bc575c0a87e

    • Or the keyId that has been assigned during the OAUTH2 technical setup (cf. § 3.4.2.1)

  • 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 continuing on this subject and the use of these two fields is not yet recommended.

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 ofthe 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 theTPP
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 theTTP
PSU-User-Agent	"User-Agent" header field sent by the PSU terminal whenconnecting to theTPP
PSU-Referer	"Referer" header field sent by the PSU terminal whenconnecting to theTPP
PSU-Accept	"Accept" header field sent by the PSU terminal whenconnecting to theTPP
PSU-Accept-Charset	"Accept-Charset" header field sent by the PSU terminal whenconnecting to theTPP
PSU-Accept-Encoding	"Accept-Encoding" header field sent by the PSU terminal whenconnecting to theTPP
PSU-Accept-Language	"Accept-Language" header field sent by the PSU terminal whenconnecting to theTPP
PSU-GEO-Location	The forwarded Geo Location of the corresponding HTTP request between PSU andTPP ifavailable.	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 retrievedintherelevantresponse.

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 pathto the correspondingfieldmight be addedinthereturn message.
RESOURCE_UNKNOWN	404	If resourceIdinpath
PERIOD_INVALID	400	Requested time period out ofbound.
ACCESS_EXCEEDED	429	The access onthe accounthas beenexceeding the consentedmultiplicity perday.
REQUESTED_FORMATS _INVALID	406	The requested formats in the Accept header entry are not matching the formats offered by theASPSP.

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/draft-ietf-oauth-mtls/
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