Skip to main content

Consent Management 2.0 with Consent as a Service (CaaS)

Via consent as a service, SIX offers the Service User to hold the Service Provider token in a token store operated by SIX in accordance with the specifications of the participation agreement (CaaS). The participant’s use of CaaS causes the participant and its customer to be authenticated by SIX for each service call request. After successful authentication, SIX forwards the service call request with the provider token to the Service Provider on behalf of the participant.

CaaS thus enables the participant to make the service calls that are intended and to be authenticated in accordance with the Participation Contract via the bLink platform without having to store the provider token in its infrastructure in accordance with the specifications of the Participation Contract.

Similar to what is defined in Consent Management 2.0, Consent Management 2.0 with CaaS has some deviations from the original OAuth 2.0 flow:

  • OAuth Client-Secret is not supported in the consent management flow: the Client is authenticated by bLink by a client certificate.
  • The Auth Server of the Service Provider authenticates the Client by means of the "X-CorAPI-Client-ID" header. See Custom Headers
  • Token endpoints of Service Providers are not accessible to Clients.
  • The Service User will work with the so-called CaaS-Permission instead of the Service Provider Access-Token

Consent Management 2.0 with CaaS was defined with the following goals:

  • User can start the consent flow from the Client side.
  • Implement standard OAuth 2.0 flow.
  • Improve security, resilience, and error handling.
  • Provide secure Provider Token storage to Clients.

Assumptions​

Service Provider's Authorization Server supports transaction signing of consent using a 2nd factor, similar to signing of new creditors.

User Journey​

From a very high level, the user journey for CaaS is similar to what the normal Consent Flow 2.0 does, but with the difference that the Service Provider will redirect the client to CaaS so that CaaS can use the authorization code to retrieve the OAuth tokens, and the Service User will never gain access to the tokens.

Detailed Consent 2.0 Flow

  1. User-Agent is logged in to the Service User Application and chooses to connect to a specific Service Provider
  2. User-Agent is redirected to the Service Provider Authentication UI
  3. once authenticated, the User-Agent is redirected to the Consent-Page
  4. once the consent has been signed, the User-Agent is redirected to CaaS (with the OAuth authorization code)
  5. once CaaS has retrieved the access_token, the User-Agent is redirected back to the Service User Application

CaaS-Permission​

With CaaS, the Service User will not be able to gain access to the Provider Token. The system will instead use the CaaS-Permission which will be known to the Service User. A CaaS-Permission is a CaaS-internal construct which is used to look up the correct Provider Token.

After the Permission has been activated successfully, it can be used during business calls, where CaaS will inject the correct Provider-Token for each API-invocation separately. For the Service Provider, this process is transparent, and it looks as if the Service User has provided the correct Token on each API-call.

Permission

The CaaS-Permission has its own lifecycle, but it is heavily dependent on the Provider Token:

  1. After initial Setup, the Permission has status received:

    State Diagram

  2. As soon as the End-User lands on the redirect-endpoint during the oauth-flow (see below), CaaS attempts to retrieve the Provider Token using the provided authorization-code and state.

    1. If this succeeds, the status changes to valid. The permission can now be used to invoke the business-apis
    2. otherwise, the permission will expire immediately and a new permission has to be created

  3. If the Provider Access-Token expires:

    1. CaaS will attempt to refresh it in the background during the next business API call, and in case it is successful, the permission will remain in status valid. In case it fails for some technical reason (anything else than invalid_grant), the API-call will fail, but the permission will remain in status valid, and the API-call can be attempted again which will trigger another refresh-attempt.
    2. if the refresh fails for a business-reason, the Permission will change to status expired permanently, and API-Calls with this permission will therefore fail permanently. In this case, a new Permission has to be initiated and the end-user will have to go through the consent-flow again. There are two possibilities why it could fail:
      1. Provider Token has been revoked on Provider side, or
      2. There has not been any activity with the Provider Access-Token for longer than the validity of the Refresh Token

  4. The Service User can also explicitly revoke a permission by calling the DELETE endpoint (see Permission Revocation). In this case, the status will change to revoked permanently.

revoked_by_psu

There is one extra case where the Permission can transition to the status revoked_by_psu. This happens if the same User-ID is used for the same Provider-ID. See also userId-explanation for Step B in the Flow.

The Consent Flow with CaaS consists of two parts: the consent 2.0 OAuth flow starting at the Service User (steps 1 to 31) and a new flow between the Service User and CaaS (steps A to E).

Detailed Consent 2.0 Flow

Preparation Steps​

  1. The user logs into Client.
  2. Client creates a session.
  3. User navigates to consent page.
  4. Client retrieves a list of active Service Providers from bLink API directory using GET /directory/providers?status=ACTIVE. An example of this request is presented as follows: 
      GET /api/bankingservices/b-link/platform/v2/directory/providers?status=ACTIVE

      host: api.six-group.com
  5. The user selects the Provider and approves it.
  6. Client retrieves information about the chosen Service Provider from bLink API directory using GET /directory/providers/<providerID>. An example of this request is presented as follows: 
      GET /api/bankingservices/b-link/platform/v2/directory/providers/99999

      host: api.six-group.com

Pushed Authorization Request Flow​

A. The Client posts permission request to CaaS. For example (please refer to the api specification for parameter limits):

  POST /permissions/99999/aa240b58-be68-42e1-89d7-19a92f73f5c2
  host: api.six-group.com

  "username": "john.doe@acme.com",
  "scope": "urn:blink:xs2a:ais urn:blink:xs2a:pss:write",
  "externalReference": "5b3e0d40-c768-45b2-b569-9fa3d2feee5e"

B. CaaS creates (or updates) a permission using the clientId, userId, username, providerId, scope and optional externalReference from the request. CaaS generates a redirect URI with a state and adds them to the permission. The permission is stored and returned to the Client. For example:

"providerId": "CIDX9999999991",
"username": "hans.muster@six-group.com",
"permissionId": "31d78ef8-238d-4547-9a8d-9f057f321eeb",
"authorizationUri": "https://secure.fi.example.com/oauth/authorize?response_type=code&client_id=654321&redirect_uri=https%3A%2F%2Fapi.six-group.com%2Foauth%2Fauthresponse&state=d60dbae3-b1b2-419c-bc72-1054fab294ec&scope=urn%3Ablink%3Aa2a%3Aais%20urn%3Ablink%3Aa2a%3Apss%3Awrite&username=john.doe%40acme.com&provider_id=99999"
"status": "received"
userid URL parameter

The Service User can choose the User-ID value freely. It is allowed to assign multiple User-ID values to the same Customer. The only requirement is that each User-ID can be traced back to the correct end-user unambiguously.

For a specific User-ID value and Provider-ID combination, there can only be one valid Permission at a time. As soon as a new permission is initiated using the same User-ID and Provider-ID, the bLink CaaS Service will revoke any previously valid permission of the same User-ID and Provider-ID.

Please note: Even when using different User-IDs to create multiple valid permissions, it could still happen that the Service Provider doesn't allow multiple valid Access Tokens in parallel for the same E-Banking Access, which will result in previous permissions being invalidated as soon as they are used in an API-call.

C. The Client stores the permission in the context of user. The redirect URI and state from the permission are used in the authorization request in step 7.

D. CaaS redirects back to Client (using the internally configured clientCallbackUri) indicating the status of the OAuth 2.0 Consent Flow.

note

Callback URL is configured during the Service User Onboarding

E. Depending on status of OAuth 2.0 Consent Flow the Client uses the externalReference to handle its own state.

The steps below follow the same numbering of the diagram of the Consent Management 2.0 Flow:

  1. Client starts standard OAuth 2.0 authorization code grant flow (response_type=code) by using the generated RedirectURL of the stored permission (Step C) to redirect to the Auth Server of the Service Provider. The following code snippet provides an examples of the initiation of the OAuth 2.0 authorization code grant flow:

      HTTP/1.1 302 Found
      
      location: https://secure.fi.example.com/oauth/authorize?response_type=code&client_id=654321&redirect_uri=https%3A%2F%2Fapi.client.example.com%2Foauth%2Fauthresponse&state=d60dbae3-b1b2-419c-bc72-1054fab294ec&scope=urn%3Ablink%3Aa2a%3Aais%20urn%3Ablink%3Aa2a%3Apss%3Awrite&username=john.doe%40acme.com&provider_id=99999
    caution

    Redirecting to authorization pages via iFrames is not allowed due to content security policy.

  2. The Auth Server of the Service Provider follow the steps below:

    1. Validates the (existence of) client_id.

    2. Executes any other actions required to verify if the request is correct, including a check to verify the requested redirect URI is currently whitelisted in the bLink directory.

    3. Uses the provider_id in multi-tenant environments to determine the corresponding tenant for login and consent (optional step).

    4. Redirects to login page if the User Agent is not logged in, otherwise it will redirect directly to consent page.

  3. The User logs into Service Provider application. A restricted session is created, where only functions required in the context of consent giving are allowed.

  4. The User is redirected to the consent page.

  5. Using the client_id from the authorization code request, the Service Provider application retrieves the Client information from bLink API directory. An example of this request is presented as follows:

      GET /api/bankingservices/b-link/platform/v2/directory/clients/654321

      host: api.six-group.com

  6. The consent page is prefilled with Client information and, if the Client username validation is supported by the Service Provider, the Client username. It is up to the user to user define the consent to be given (e.g. for access to account and payments).

  7. Service Provider application stores Client, consent and, if supported by Service Provider, the Client username (preferably as a hashed value) in the user's profile.

  8. The User signs the consent, the Client and optionally the Client username according to the policies of the Service Provider (e.g. using 2nd factor, similar to signing new creditors in e-Banking).

  9. The Service Provider stores the signature in the Consent Server.

  10. The Resource Server retrieves an authorization code from the Auth Server.

  11. The Resource Server redirects to the redirect_uri received from Client and include the authorization code received from the Auth Server and the state provided by the client. At this point the restricted session is finished. The following code snippet shows an example of the redirect:

      HTTP/1.1 302 Found

      location: https://webapp.api.six-group.com/redirect/bankingservices/b-link/v2/api-token?code=abcdefg&state=d60dbae3-b1b2-419c-bc72-1054fab294ec

  12. CaaS verifies if the requested URI matches the redirect_uri and if the state returned matches the state sent. If the verification is successful, CaaS requests the access and refresh tokens through bLink API and, going forward, acts as authenticating proxy towards the Service Provider's token endpoint. The username parameter (max. length: 64) of the logged user in step 12 must be added to the request. For proper routing by bLink API, the request must include a x-corapi-target-id header with the provider_id of the target Service Provider. An example is presented in following code snippet:

      POST /api/bankingservices/b-link/consent-flow/v2/oauth/token
      x-corapi-target-id: 99999
      host: api.six-group.com

      client_id=654321
      &grant_type=authorization_code
      &code=abcdefg
      &redirect_uri=https://api.client.example.com/oauth/authresponse
      &username=john.doe@acme.com
      ...

  13. bLink API token endpoint:

    1. Authenticates the CaaS Component

    2. Extracts the provider_id from the x-corapi-target-id request header.

    3. Determines the hostname/IP address and basepath of Auth Server token endpoint at target Service Provider.

    4. Sends the token request with the x-corapi-client-id header to target Service Provider.

      POST /proprietaryBackendPath/api/v2/oauth/token
      x-corapi-client-id: 654321
      host: api.fi.example.com

      client_id=654321
      &grant_type=authorization_code
      &code=abcdefg
      &redirect_uri=https://api.client.example.com/oauth/authresponse
      &username=john.doe@acme.com

  14. The Auth Server token endpoint of the Service Provider proceeds as follows:

    1. Identifies the Client using the x-corapi-client-id request header.

    2. Verifies authorization code, which must have been issued for this Client in the steps above.

    3. Verifies the redirect_uri, which must match exactly with the redirect_uri parameter from the initial authorization request.

    4. If supported by the Service Provider, validates the username from the POST request by hashing and comparing it against the hash value stored with the consent in step 15.

  15. The Consent Server verifies the consent, which depends on Service Provider's implementation (optional: validation of the username by hashing the value received in the request and comparing it with the value stored with the consent).

  16. The Auth Server generates access and refresh tokens and returns them to the Client according to the 5.1 section of the OAuth 2.0 specification:

    • If the issued access token scope is different from the one requested by the client, the auth server must include the scope parameter to inform the Client of the actual scope granted according to OAuth 2.0 specification, 3.3.
    • If the request fails for any reason, the Auth Server should inform the Resource Owner according to the 5.2. section of the OAuth 2.0 specification.

  17. CaaS (on behalf of the Client) stores the access and refresh tokens in the profile of the user.

  18. CaaS (on behalf of the Client) the use POST &ltsixUsernameValidationEndPointUri&gt username=&ltusername&gt request to send the username of the user to the bLink username validation endpoint. An example of this request is presented below:

      POST /api/bankingservices/b-link/consent-flow/v2/oauth/username
      x-corapi-target-id: 99999
      host: api.six-group.com
      authorization: bearer yJz93a3490dK7jlawk4laUWw

      username=john.doe@acme.com
      ...

  19. The bLink API username validation endpoint proceeds as follows:

    1. Authenticates the CaaS (on behalf of the Client).

    2. Extracts the provider_id from the x-corapi-target-id request header.

  20. bLink determines if the provider supports username validation:

    • If yes, then bLink determines the hostname/IP address and basepath of Service Providers' username validation endpoint and sends username validation request with the x-corapi-client-id header to it. An example is presented as follows: 
        POST /proprietaryBackendPath/api/v2/oauth/username
        x-corapi-client-id: 654321
        host: api.fi.example.com
        authorization: bearer yJz93a3490dK7jlawk4laUWw

        username=john.doe@acme.com
        ...
    • If not, bLink return status OK and continue skips to step 29.

  21. If username validation is supported by the Service Provider, it authenticates CaaS (impersonating the Client) using the access token from the POST request. The Consent Server calculates hash value of username from POST request and compares it against the hash value stored with consent (in step 5). If the hash values are identical, the consent is activated. Consent Server returns the result of the comparison (OK/NOK, see error below).

  22. If username validation is supported by the Service Provider and the result of step 27 is NOK, the Service Provider revokes the tokens issued in step 22. The Consent server returns the result (OK/NOK, see error handling table below for NOK). Subsequent correct calls to this endpoint must be idempotent.

  23. Depending on the result of step 23 the CaaS takes any actions required ("activate consent", delete tokens, etc.).

Finalizing Steps​

  1. Optional step: Client redirects the user to its own landing page with a parameter indicating the flow status.
  2. User journey ends on a landing page of Client, which informs the user about the status of the flow. In case of error the user is informed on how to resolve the issues.

Permission Revocation​

  • Currently there can only exist one permission for a User-ID/Provider-ID combination with a status other than "revoked"/"revokedByPsu". As soon as a new permission is created for a User-ID and Provider-ID, any pre-existing permission for the same User-ID and Provider-ID is revoked.
  • A permission can be revoked by the Service User using the revokePermission-endpoint (DELETE /permissions/{providerId}/{userId})
NOTE

If tokens are revoked on Service Provider side (not through DELETE permission), there is no way for CaaS to know about it, other than that there will be error messages on subsequent calls when using some revoked token.

INFO

The CaaS Service will call the revoke-token endpoint in the background, provided that

  • the respective Service Provider supports revoke
  • the Service Provider has submitted the URL to be configured in bLink through the Support Portal
Multiconsent Support

Some Service Providers only allow one token per bank login/contract. For permissions this means, that if you create two permissions for the same Provider-ID, but with different User-IDs and if the resource owner uses the same login to log into his/her e-banking both times then the token issued for the first completed consent flow is revoked by the second. bLink cannot recognize if a token was revoked through this mechanism, and therefore the permission with the revoked token will appear to be "valid" until it is used in a use-case call.

Error Handling​

In the event of errors, the Resource Owner is redirected back to the client landing page with a status parameter in the redirect indicating which error occurred. In case of missing, invalid, or mismatching redirect URI, or if the client identifier is missing or invalid, the Service Provider should inform the Resource Owner of the error and must not automatically redirect the user-agent to the invalid redirect URI (as described in OAuth 2.0 Specification Section 4.1.2.1). Based on the error code, the Service User renders an error page and returns it to the Resource Owner.

The following table provides information on error handling as defined by the OAuth 2.0 Specification.

PhaseErrorHandlingFlow Steps
OAuth2 Authorization RequestResource Owner cannot login at Service Provider.

The Service Provider redirects to CaaS as described in OAuth 2.0 Specification Section 4.1.2.1 with the following error code added to the redirect URI:


error=access_denied

CaaS redirects to the Service User with the parameter status=access_denied added to the clientCallbackUri.

8
OAuth2 Authorization RequestScope parameter is missing or invalid.

The Service Provider redirects to CaaS as described in

OAuth 2.0 Specification Section 4.1.2.1

with the following error code added to the redirect URI:


error=invalid_scope

CaaS redirects to the Service User with the parameter status=invalid_scope added to the clientCallbackUri.

8
OAuth2 Authorization RequestProviderId and/or Username parameter is missing or invalid.

The Service Provider redirects to CaaS as described in OAuth 2.0 Specification Section 4.1.2.1 with the following error code added to the redirect URI:


error=invalid_request

CaaS redirects to the Service User with the parameter status=invalid_request added to the clientCallbackUri.

8
OAuth2 Authorization ResponseState parameter is missing or unknown.

CaaS redirects to a whitelabel error page of bLink indicating the missing or unknown state.

18
OAuth2 Authorization ResponseCaaS cannot verify redirect URI and state.

CaaS redirects to the Service User with the parameter status=invalid_request_client added to the clientCallbackUri.

18

OAuth2 Authorization Request

Service Provider cannot verify redirect URI.

The Service Provider should inform the resource owner as described in OAuth 2.0 Specification Section 4.1.2.1.

In any case the Service Provider must not automatically redirect the user-agent to the invalid redirect URI

8

OAuth2 Token RequestService Provider cannot verify authCode (code) or redirect_uri.

In case the authCode cannot be verified the Service Provider responds with a HTTP 400 (Bad Request) according in OAuth 2.0 Specification Section 5.2 with the following error code included in the response:

    {
    "error": "invalid_grant"
    }

In any other case the Service Provider includes the following error code in the response:

  {
  "error": "invalid_request"
  }

CaaS redirects to the Service User with the parameter status=<error code received from Service Provider> added to the clientCallbackUri.

20
OAuth2 Token RequestService Provider cannot verify username (if implemented).

The Service Provider does not return any tokens.

The Service Provider responds with a HTTP 400 (Bad Request) according in

OAuth 2.0 Specification Section 5.2

with the following error code included in the response:

    {
    "error": "invalid_request",
    "error_description": "invalid_username"
    }

CaaS redirects to the Service User with the parameter status=invalid_username added to the clientCallbackUri.

21
Username validation request

The username from the request does not match with the username from the consent (if implemented).

The Service Provider revokes access and refresh tokens issued in step 22 and responds to CaaS with HTTP/1.1 200 OK<br/>"valid_username": false CaaS deletes the access and refresh tokens received and stored in step 23 and redirects to the Service User with the parameter status=invalid_username added to the clientCallbackUri.

25
Username validation request

Service Provider cannot verify username due to missing username parameter, empty username or invalid token (if implemented).

The Service Provider revokes access and refresh tokens issued in step 22 and responds to CaaS with an error message in Problem Details Format (RFC 7807).

Example:

  HTTP/1.1 401 Unauthorized
  {
    "type": "/problems/TECHNICAL_ERROR",
    "title": "UsernameValidationServiceException",
    "detail": "Request parameter 'username' is missing",
    "instance": "/.../errors/CIDX9999999991/correlation-id",
  }

CaaS deletes the access and refresh tokens received and stored in step 23 and redirects to the Service User with the parameter status=invalid_username added to the clientCallbackUri.

API-Call with invalid Permission-ID

CaaS is blocking the API call with INSUFFICIENT_PRIVILEGES error

CaaS permission doesn't exist or is not in status valid or expired

Example:

  HTTP/1.1 403 Forbidden
  {
    "type": "/problems/INSUFFICIENT_PRIVILEGES",
    "title": "Access denied",
    "detail": "Access not allowed for specified permission",
    "instance": "/api/.../v3/accounts/errors/correlation-id"
  }
API-Call with invalid Permission-ID

During an API-Call, CaaS tries to refresh the access-token using the refresh-token, but gets an expired response from the Service Provider.

Refresh-Token has expired, and Permission therefore has expired too.

Example:

  HTTP/1.1 403 Forbidden
  {
  "type": "/problems/EXPIRED_TOKEN",
  "title": "Permission expired",
  "detail": "Specified permission has expired permanently",
  "instance": "/api/.../v3/accounts/errors/correlation-id"
  }

Timeouts​

Step


Range

DescriptionTimeout valueHandling Service ProviderHandling Service User
7 - 23Complete OAuth consent flow times out.30 minn/a

Take any actions to clean-up (state, etc.). If possible: notify Resource Owner.

18 - 23Timeout between Token Request and Token Response30 secn/a

CaaS redirects to the Service User with the parameter status=restart_flow added to the clientCallbackUri.

22 - 27

Timeout between Token Response from Service Provider and username validation / consent activation request by CaaS (if username validation supported by Service Provider)

30 secRevoke access and refresh tokens issued in step 22.

If supported by Service Provider: Any future request to access the actual API will fail. Access token may not be refreshed.

22 - 27

Timeout between username validation / consent activation request by Service User and corresponding response by Service Provider

30 secn/a

State of username validation / consent activation not clear.
CaaS redirects to the Service User with the parameter status=not_activated added to the clientCallbackUri.

Sessions inside your application

If an adapter service setup is chosen, there is an additional session that can be implemented to enhance the security of your integration. This is the session between the adapter service and your business application that is used to transfer data from the service provider to your application and vice versa. Limiting the duration of this separate session adds another protective layer to your adapter service.

Scopes​

The Service User uses the scope request parameter of the access request to specify its desired access rights. Every API published on bLink must document its scope requirements as a list of accepted strings to be used in the scope parameter. A best practice is to assign each scope a unique name, in the form of an URN.

Scopes for bLink shall match the following pattern: urn:blink:<api_name>:<name_of_use_case>

For use cases that execute write operations, the suffix :write shall be added to the URN. For use cases that execute delete operations, the suffix :delete shall be added. For use cases that execture read operations, the suffix :read may be added.

Every API gets an unique name assigned by bLink. The owner of an API defines the unique names for the use cases including the suffixes. Some examples are presented below for AIS and PSS:

APIUse CaseUnique name of scope
Access to AccountAISurn:blink:xs2a:ais
Access to AccountPSSurn:blink:xs2a:pss:write

Given that:

  • urn:blink = Fixed prefix defined by bLink
  • xs2a = name of API assigned by bLink
  • ais , pss:write = names of use-cases and suffixes defined by API owner

Access to Account API Scopes​

The following scopes are defined for the Access to Account API:

Use caseScope readScope write (incl. read/update/delete)
AISurn:blink:xs2a:aisn/a
PSSn/a*)urn:blink:xs2a:pss:write

OpenWealth API Scopes​

The following scopes are defined for the OpenWealth API:

Use CaseScope readScope write (incl. read/update/delete)
Custody servicesurn:blink:ow:cstdyn/a
Customer managementurn:blink:ow:custmgmturn:blink:ow:custmgmt:write
Order placementurn:blink:ow:ordrplcurn:blink:ow:ordrplc:write
Last updated on