Authentication and OAUTH2 access token
Diagram of the OAUTH2 access token retrieval principle
As developer of an application wishing to use this API resources, you need to get an OAUTH2 access token following the steps below :
References
Section 3.4.3.2 of STET standard v1.4.0.47 : https://www.stet.eu/en/psd2/
OAuth 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1
Step by step development
1. Our customer specifies to you the identity of the Banque Populaire which holds his accounts.
2. You initiate the OAUTH2 access token recovery sequence by redirecting our customer to the bank’s authorization infrastructure, through the following URL pattern and parametersd'autorisation :
See also [STET Framework page 21]
GET /authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}[&state={state}]
Name | Data | Type | |
response_type | [1..1] | Expected type of token | String[10]String[10] Must be valued with “code” |
client_id | [1..1] | TPP identification | String[34] 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] [1..1] | Call-back URL of the TPP | String [140] => mandatory field for Banques Populaires |
scope | [0..1] | Specifies the generic accreditations that both the PSU and the TPP agreed on : _ for AISP
_ for CBPII :
| String [140] => Space delimited roles list |
state | [0..1] | Internal state that you can used for context management | String [34] |
3. The Banque populaire account holder (ASPSP) will :
Identify and authenticate the customer using one of the strong authentication methods proposed and presented to the customer;
Performs checks about your AISP or CBPII function (QWAC and QSealc certificates validity and your role validity, non-revocation of your profile etc.).
4. Afterwards, the Banque Populaire will redirect the customer to your website, using the previously given call-back URL and the following parameters. Please note that you will need to communicate this URL when you will fill the subscription form for the live on API 89C3 portal.
See also [STET Framework page 22]
Name | Data | Type | |
code | [1..1] | Short-time code to use in order to get the access token | String [34] |
state | [0..1] | Internal state if you provided it | String [34] |
5. You will then be able to call, through a POST request, the bank’s authorization infrastructure with the following :
See also [STET Framework page 22]
Name | Data | Type | |
grant_type | [1..1] | Requested authorization type | String [34] => Must be valued with “authorization_code" |
code | [1..1] | Short-time code previously provided by the ASPSP | String [34] |
redirect_uri | [1..1] | Call-back URL of the TPP | String [140] => must be equal to the redirect_uri provided in the GET / token request. |
client_id | [1..1] | TPP identification | String [34] => Must be equal or linked to the OrganizationIdentifier part of the Distinguished Name of the eIDAS certificate, according to ETSI specification |
Example
POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &client_id={clientId}
6. The Banque Populaire account holder (ASPSP) will :
Performs checks about your AISP or CBPII function (QWAC and QSealc certificates validity and your role validity, non-revocation of your profile etc.
Identify and authenticate your AISP or CBPII role through the X509 certificate that you present for safety of the mutual authentication
7. Once these verifications done and if they are conclusive, the bank will answer through a HTTP200(OK) response that embeds the following data :
See also [STET Framework page 23]
Name | Data | Type | |
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 values with “Bearer" |
expires_in | [0..1] | Token lifetime, in seconds. The token can be used several times as far as it is not expired. | Numéric |
refresh_token | [0..1] | Refresh token that can be used for a future token renewal request. | String [140] |
Example
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" }
8. As soon as the OAUTH2 access token has been provided by the Banque Populaire (valid for 90 days), you will be able to present it to consume the resources of the API (see the use cases for the API methods).
Authentication of our customer.
Identification methods of our customer
There are three different methods for customer identification wich should be relevant for the l'ASPSP (bank).
These three approaches are implemented in different ways, depending on the relevant use case :
- either during the authorisation process, mostly for AISP and CBPII use cases (cf. § 3.4;
- either during the consent management process, for instance in case of Payment Request (cf. § 3.5)
Redirect approach principle => This méthode doesn't apply for the Banques Populaires
Through the Redirect approach, the customer authentication process is fully processed by the ASPSP.
In order to allow this, the TPP has to redirect the customer to the ASPSP authentication service, meaning the customer will leave temporarily the TPP interface for authenticating towards the ASPSP interface.
The TPP might have already captured a customer identifier that can be handled by the ASPSP for unambiguously recognizing the customer. 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.
Exemptions to the strong customer authentication
Exemptions to the strong customer authentication are specified by the EBA (European Banking Authority) RTS on SCA, especially for Payment Initiation Services portant.
In this context, the API allows the TPP to forward to the ASPSP any useful information.
Eventually, the ASPSP keeps the final decision to apply or not this exemption.