Consent Management 2.0

Consent management authorizes a Third-Party Provider (TPP) to access specific resources of a corporate at a Financial Institution (FI). The process to establish consent between a corporate user (Resource Owner) and a bank (Resource Server) is based on the standard OAuth 2.0 authorization code flow with response_type=code as defined in IETF reference. Service Providers and Clients (TPPs) must support access via a bearer token and refresh tokens in order to successfully execute the authorization code grant flow.

At the most basic level, before OAuth 2.0 can be used, the Client must first obtain its own credentials (Client ID and Client Secret) from the authorization server in order to identify and authenticate itself when requesting an access token. With OAuth 2.0, users have a secure way to access online services using the OAuth 2.0 authentication framework without having to risk their login information.

However, to support the initiation of the process, OAuth 2.0 has been extended with an up-front pre-authentication and authorization step and some deviations from the standard OAuth 2.0 flow are presented as follows:

• OAuth Client Secret is not supported in the Consent Management Flow. The Client is authenticated by a client certificate.
• Token endpoints of Service Providers are located behind the SIX authenticating proxy.

Goals for Consent Management 2.0

Consent Management 2.0 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 of the bLink ecosystem.

User Journey

From a very high level, the user journey the consent-flow is a simple OAuth2 based journey. The following depiction shows the journey stations from the perspective of the User-Agent (Browser).

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 back to the Service User Application (with the OAuth authorization code)

Detailed Consent Management 2.0 Flow

The steps below follow the same numbering of the diagram of the Consent Management 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-consent-2/platform/v2/directory/providers?status=ACTIVE
   host: api-cert.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/&ltproviderID&gt. An example of this request is presented as follows:

   GET
   /api/bankingservices/b-link-consent-2/platform/v2/directory/providers/99999
   host: api-cert.six-group.com

OAuth 2.0 Steps and Username Validation

7. Client starts standard OAuth 2.0 authorization code grant flow (response_type=code) by redirecting to the authentication server of the Service Provider. For this, the following requirements must me considered:
   • A state must be included with the request.

   • The length of the URL-encoded state parameter is limited to 256 characters.

   • A scope parameter must be included with the request. The URL-encoded scope parameter must contain one or more of the scope tokens (as defined in OAuth2 Specification Section 3.3).

   • The scope parameter is limited to 256 characters.

   • The username of the currently logged-in user must be added as an URL-encoded username parameter to the request. The username parameter is limited to 64 characters.

   • A provider_id parameter must be included with the request. The provider_id and client_id parameters are limited to 30 characters.

   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

8. The Auth Server of the Service Provider follow the steps below:
   1. Validates the client_id.

   2. Executes any other actions required to verify if the request is correct.

   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.

9. The User logs into Service Provider application. A restricted session is created, where only functions required in the context of consent giving are allowed.
10. The User is redirected to the consent page.
11. 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-consent-2/platform/v2/directory/clients/654321
    host: api-cert.six-group.com

12. 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).
13. 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.
14. 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).
15. The Service Provider stores the signature in the Consent Server.
16. The Resource Server retrieves an authorization code from the Auth Server.
17. 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://api.client.example.com/oauth/authresponse?code=abcdefg&state=d60dbae3-b1b2-419c-bc72-1054fab294ec

18. The Client verifies if the requested URI matches the redirect_uri and if the state returned matches the state sent. If the verification is sucessful, the Client requests the access and refresh tokens through bLink API, which 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-2/consent-flow/v2/oauth/token
    x-corapi-target-id: 99999
    host: api-cert.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
    ...

19. bLink API token endpoint follow the steps below:
    1. Authenticates the Client.

    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-target-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

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

    1. Authenticates the Client using the x-corapi-target-id request header.

    2. Verifies authorization code, which must have been issued for this Client.

    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.

21. 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).
22. 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.
23. Client stores the access and refresh tokens in the profile of the user.
24. Client the use POST <sixUsernameValidationEndPointUri> username=<username> 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-2/consent-flow/v2/oauth/username
    x-corapi-target-id: 99999
    host: api-cert.six-group.com
    authorization: bearer yJz93a3490dK7jlawk4laUWw
    
    username=john.doe@acme.com
    ...

25. The bLink API username validation endpoint proceeds as follows:
    1. Authenticates the Client.

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

26. 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.
27. If username validation is supported by the Service Provider, it authenticates the Resource Owner 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).
28. 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.
29. Depending on the result of step 23 the Client takes any actions required ("activate consent", delete tokens, etc.).

Finalizing Steps

30. Optional step: Client redirects the user to its own landing page with a parameter indicating the flow status.
31. 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.

Token Revocation

For revoking tokens, there are multiple options:

• the Service Provider may revoke tokens
• the Service Provider should provide a UI for the resource owner to revoke tokens
• the Service Provider may implement the revoke endpoint, and the Service User may call this endpoint to revoke tokens
  • prerequisite is that the URL is configured in the bLink Directory (same as with the token url)
  • the Service User will call the revoke endpoint on bLink (available on Consent Flow API starting from v2.0.14.3). To know if revoke is supported for the given Service Provider, the Service User needs to check in the directory. This information is available on the Platform API starting from v2.0.15.3, indicated with the .features.consent_tokenRevocationActive flag (value=true)

NOTE

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

Tokens issued by Simulator

Tokens issued by the bLink Service Provider simulator are not persisted, which means that tokens are lost when the simulator is restarted.

"Multiconsent" Support

Some Service Providers only allow one token per bank login. If two consent flows with the same provider are done 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.

Error Handling

In the event of erros, the Resource Owner is redirected back to the Client Landing Page with a status parameter in the redirect indicating which error occurred. In the cases 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.

Phase	Error	Handling	Flow Steps
OAuth2 Authorization Request	Resource Owner cannot login at Service Provider.	After the maximum number of retries (as defined by the Service Provider) the Service Provider redirects back to the Service User 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 The Service User redirects to the Client Landing Page with the parameter status=access_denied added to the clientLandingPageUri.	8
OAuth2 Authorization Request	Scope parameter is missing or invalid	The Service Provider redirects back to the Service User 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 The Service User redirects to the Client Landing Page with the parameter status=invalid_scope added to the clientLandingPageUri.	8
OAuth2 Authorization Request	ProviderId and/or Username parameter is missing or invalid	The Service Provider redirects back to the Service User 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 The Service User redirects to the Client Landing Page with the parameter status=invalid_request added to the clientLandingPageUri.	8
OAuth2 Authorization Response	Service User cannot verify redirect URI and state.	The Service User redirects to the Service Provider Landing Page with the parameter status=invalid_request_client added to the clientLandingPageUri.	18
OAuth2 Authorization Request & OAuth2 Token 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 & 20
OAuth2 Token Request	Service Provider cannot verify authCode or state.	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 The Service User redirects to the Client Landing Page with the parameter status=<error code received from Service Provider> added to the clientLandingPageUri.	20
OAuth2 Token Request	Service 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 The Service User redirects to the Client Landing Page with the parameter status=invalid_username added to the clientLandingPageUri.	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 Service User with HTTP/1.1 200 OK { "valid_username": false } Service User deletes the access and refresh tokens received and stored in step 23 and redirects to the Client Landing Page with the parameter status=invalid_username added to the clientLandingPageUri.	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 Service User 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": "/b-link/v2/oauth/username/errors/CIDX9999999991/correlation-id" } Service User deletes the access and refresh tokens received and stored in step 23 and redirects to the Client Landing Page with the parameter status=invalid_username added to the clientLandingPageUri.

Timeouts

Steps Range	Description	Timeout value	Handling Service Provider	Handling Service User
7 - 23	Complete OAuth consent flow times out.	30 min	n/a	Take any actions to clean-up (state, etc.). If possible: notify Resource Owner.
16 - 20	Timeout between Authorization Response from Auth Server to Token Request from Service User.	n/a	Implicitly handled by expiration of Authorization Code.	If possible, the Service User redirects to the Client Landing Page with the parameter status=access_denied added to the clientLandingPageUri.
18 - 23	Timeout between Token Request and Token Response	30 sec	n/a	The Service User redirects to the Client Landing Page with the parameter status=restart_flow added to the clientLandingPageUri.
22 - 27	Timeout between Token Response from Service Provider and username validation / consent activation request by Service User (if username validation supported by Service Provider)	30 sec	Revoke access and refresh tokens issued in step 22.	Any future request to access the actual API will fail. Access token may not be refreshed. The Service User deletes the access and refresh tokens received and stored in step 23 and redirects to the Client Landing Page with the parameter status=restart_flow added to the clientLandingPageUri.
24 - 29	Timeout between username validation / consent activation request by Service User and corresponding response by Service Provider	30 sec	n/a	State of username validation / consent activation not clear. The Service User redirects to the Client Landing Page with the parameter status=not_activated added to the clientLandingPageUri.

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:

API	Use Case	Unique name of scope
Access to Account	AIS	urn:blink:xs2a:ais
Access to Account	PSS	urn: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 case	Scope read	Scope write (incl. read/update/delete)
AIS	urn:blink:xs2a:ais	n/a
PSS	n/a*)	urn:blink:xs2a:pss:write

*) Scope read might be added in the future.

OpenWealth API Scopes

The following scopes are defined for the OpenWealth API:

Use Case	Scope read	Scope write (incl. read/update/delete)
Custody services	urn:blink:ow:cstdy	n/a
Customer management	urn:blink:ow:custmgmt	urn:blink:ow:custmgmt:write
Order placement	urn:blink:ow:ordrplc	urn:blink:ow:ordrplc:write