Skip to main content

Token Management

Access tokens​

Access tokens are issued by the Service Provider's authorization servers. There are no special requirements regarding content and structure of access tokens and the platform does not validate these tokens.

Important information about access tokens:

  • Access tokens are treated as black boxes by clients and bLink.
  • No changes required at Service Provider's authorization servers.
  • Allows use of symmetric token signing algorithms for JWTs.

Authorization code and token lifetime​

The following table defines mandatory and recommended lifetimes for authorization code and access/refresh tokens.

Code/TokenLifetimeTypeComment
Authorization code30 secMandatory The authorization code flow consists of a few redirects without user interaction. It is feasible to keep this lifetime short.
Access token24 hrRecommendation Shorter lifetime could lead to a token refresh flow for almost every resource access.
Refresh token30 daysMinimum required lifetimeRefresh token lifetime has to be extended with every access token refresh.
note

The access token expiration must be handled by the token issuer (Service Provider).

Authorization revoke​

Multiple tokens for same e-banking contract​

Some Service Providers allow only one token per bank contract.

In case two consent flows with the same provider are performed and the resource owner uses the same contract to log into the e-banking, then the token issued for the first completed consent flow will be revoked by the second. There is no notification that the existing token was revoked and can only be identified, by a failing refresh-call.

Service Provider IAM endpoints​

The Service Provider must expose the authorization endpoint to the internet. The token endpoint may be exposed solely to bLink, which acts as an authenticating proxy toward the token endpoint and protects it from unauthorized access.

Secure Token Storage​

Access and refresh tokens have a sensitive nature and must be protected. They need to be secured according to generally accepted best practices for secure password storage.

Request validation​

Only valid requests are forwarded by bLink to Service Providers. Requests from authenticated and authorized clients must meet the following requirements:

  • All mandatory request headers are present and syntactically correct
  • All optional request headers are syntactically correct
  • No unspecified request headers are present
  • JSON or XML payload is syntactically correct

Service Providers must validate that the access token in the request was issued (by the authorization server) to the client authenticated by bLink.

Token Refresh without CaaS​

The token refresh flow is implemented according to OAuth 2.0 standard.

Example of token expiration and subsequent refresh flow​

This example shows a payment initiation submission with an expired access token, subsequent token refresh and resubmission of initial payment initiation.

Multiple tokens 1

  1. Payment service user (PSU) is logged in at client and submits a payment initiation.
  2. Client
    1. stores IP address and User Agent of PSU
    2. prepares PSS message
    3. posts the message to bLink API including X-PSU-IP-Address and X-PSU-User-Agent headers (mandatory for PSS)
      Example from client to SIX:
        POST /api/bankingservices/b-link-consent-type/payment-submission-service/version/payments
        x-corapi-target-id: 99999
        host: api-cert.six-group.com
        authorization: Bearer ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2Np
        x-psu-ip-address: 34.12.19.3
        x-psu-user-agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36
        ...
  3. bLink API payments endpoint
    1. authenticates the client
    2. verifies authorization to payments endpoint
    3. validates the request
    4. forwards the request to the Service Provider
      Example from SIX to Service Provider:
    POST /proprietaryBackendPath/payments
    x-corapi-client-id: 654321
    host: api.fi.example.com
    authorization: Bearer ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2Np
    x-psu-ip-address: 34.12.19.3
    x-psu-user-agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36
    ...
  4. Resource Server of FI extracts access token and client_id from PSS request and calls Auth Server to authenticate user.
  5. Auth Server detects that access token is expired and returns an "invalid token error".
  6. Resource Server takes "invalid token error" and returns it via bLink API to the client. According to RFC6750 Section-3 the response must include the "WWW-Authenticate" response header in this case.
  7. Client initiates standard OAuth 2.0 token refresh flow
    Example from client to SIX: 
    POST /api/bankingservices/b-link-consent-type/consent-flow/version/oauth/token
    x-corapi-target-id: 99999
    host: api-cert.six-group.com

    client_id: 654321
    grant_type: refresh_token
    refresh_token: WVhRaU9qRTFOREV4TkRneE1Ea3NJbVY0
  8. bLink API token endpoint
    1. authenticates the client
    2. extracts the IID from the X-CorAPITarget-ID request header
    3. determines the hostname/IP address and basepath of Auth Server token endpoint at target SP
    4. sends token request with header X-CorAPI-Client-ID to target SP
      Example from client to SIX:
    POST /proprietaryBackendPath/oauth/token
    x-corapi-client-id: 654321
    host: api.fi.example.com

    client_id: 654321
    grant_type: refresh_token
    refresh_token: WVhRaU9qRTFOREV4TkRneE1Ea3NJbVY0
  9. Auth Server token endpoint of Service Provider
    1. authenticates Client using request header X-CorAPI-Client-ID
    2. verifies refresh_token (must have been issued to the Client authenticated from request header)
    3. calls Consent Server for consent verification
  10. Consent Server verifies consent
  11. Auth Server
    1. generates new access token
    2. and either generates new refresh token or extends lifetime of refresh token
    3. returns access token and optionally refresh token via bLink API to the client. If the request fails for any reason the Auth Server should inform the resource owner according to OAuth 2.0 specification, 5.2.
  12. Client stores new access token (and optionally refresh token).
  13. Client resubmits the PSS message from step 2
    Example from client to SIX:
POST /api/bankingservices/b-link-consent-type/payment-submission-service/version/payments
x-corapi-target-id: 99999
host: api-cert.six-group.com
authorization: Bearer 9pWlMxaVlXNXJhVzVuTFhWelpYSXRhV1Fp
x-psu-ip-address: 34.12.19.3
x-psu-user-agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36
...
  1. bLink API payments endpoint
    1. authenticates the client
    2. verifies authorization to payments endpoint
    3. validates the request
    4. forwards the request to the Service Provider
      Example from SIX to Service Provider:
    POST /proprietaryBackendPath/payments
    x-corapi-client-id: 654321
    host: api.fi.example.com
    authorization: Bearer 9pWlMxaVlXNXJhVzVuTFhWelpYSXRhV1Fp
    x-psu-ip-address: 34.12.19.3
    x-psu-user-agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36
    ...
  2. Resource Server of Service Provider extracts access token and client_id from PSS request and calls Auth Server to authenticate user.
  3. User is authenticated using access token and client_id.
  4. Resource Server calls Consent Server to verify consent.
  5. Consent Server verifies / returns consent.
  6. Resource Server
    1. stores/forwards X-PSU-IP-Address and X-PSU-User-Agent for fraud detection systems
    2. creates PSS resource
    3. returns response containing submissionId via bLink API to Client
  7. Client stores submissionId for consecutively polling the status of the PSS request.
  8. Client returns page showing "PSS submitted" status to user.

Token refresh with CaaS​

In case of CaaS, the Token handling is completely hidden from the Service User.

Refresh is handled automatically by CaaS during API calls. The Client does not notice any refresh (apart from a longer latency during refresh). However, refresh is only attempted if the Service User invokes an API call for a given End-User.

On Service Provider side the refresh is completely identical to the one without CaaS.

IMPORTANT

CaaS will only stop trying to refresh a specific token once the Service Provider response contains the error code invalid_grant. Any other error (e.g. internal server error) will result in retry attempts.

IMPORTANT

If the service provider has at any point responded with the error code invalid_grant, CaaS will set the corresponding CaaS permission to expired as well. The result is, that the Service User will have to create a new permission and complete a new consent-flow before he can access any data from the respective user again.

Multiple tokens for same Service Provider​

A customer (user) of a Service User may have two or more e-banking accounts (contracts) with the same Service Provider. If the user wants to integrate both e-banking accounts into their Service User application, then the application should ensure the handling of more than one token.

For example, suppose that an employee of an external asset manager (EAM) uses a Portfolio Management System (PMS) application works with Bank A and Bank B. He has already integrated both banks at once by going through the Consent Flow. But the EAM employee also has a second e-banking account with Bank B and he also wants to connect the second account to the PMS application. For this, he has to restart the Consent Flow. The steps of this process are presented as follows:

  1. First of all, the user has to log into the Service User application, where they get an overview of the banks with which they have already established a connection, as presented in the figure.

Multiple tokens 1

  1. After that, the user needs to click on "Connecting bank" in order to start a new Consent Flow.

Multiple tokens 2

  1. The user has to select Bank B and click "Connect".

Multiple tokens 3

  1. Finally, after giving the Consent for the second e-banking account of Bank B, the user will be redirected to the connections page. Both connections are now visible in the Service User's application and the user can manage these connections individually.

Multiple tokens 4

IMPORTANT

Existing Consents can't be updated through the bLink APIs. The bLink ecosystem only supports creating new consents because in consent-flow 2.0, there is no parameter which would allow to identify a specific consent. Any changes to existing consents have to be done purely on Service Provider side without any interaction through bLink.

Last updated on