Skip to main content

Onboarding Procedure for Service User

The onboarding procedure for a Service User (SU) is performed in three different phases: connectivity, implementation and verification. The figure below depicts an overview of these phases and the following sections explain the relevant details.

Testing procedures TPP

Connectivity​

In the first phase of the onboarding process, the SU focuses on the registration as a participant on bLink and establishing the connection to the testing environment. For the registration on the test environment, the SU provides the following documentation via the bLink Support Portal:

Once the participant is configured, the following code snippet can be used to test connectivity to bLink. Besides testing the connectivity, the SU will retrieve a list of all registered providers on bLink and get an impression of the functionality of the bLink Directory. 

curl -v \
--cert <your-full-chain-cert>.pem \
--key <your-cert-key>.pem \
-H "X-Correlation-ID: <correlation-id>" \
'https://api-qa.np.six-group.com/api/bankingservices/xe/b-link/platform/v2/directory/providers'

After a successful connectivity test, the SU can install the available Postman-Collection to start with the implementation phase.

Implementation​

The implementation comprises of two stages. Initially, the SU engages with the bLink Simulator CIDX9999999991 to establish consent with the simulated provider, enabling authorization for resource access. Subsequently, the SU develops the desired endpoints and seamlessly integrates the retrieved data into its application.

The consent flow simulates the authorization process for a Service User to access specific resources of a Service Provider as further described in Consent Management 2.0. SIX provides a Postman collection, which simulates the procedure from start to end with all involved parties: Service User, SIX and Service Provider. The SP is simulated by the bLink Simulator.

The following items describe the basic calls that will be performed with the security simulator for Consent 2.0 (the numbers each correspond to a specific step in Consent Management 2.0).

  • (4) Get list of active Providers: This request retrieves a list of all active Service Providers registered on this specific bLink testing environment. Postman extracts the "providerAuthEndpointUrl" in the consent flow item of the selected provider to initiate the (7) OAuth 2.0 authorization code grant flow.
  • (8.1-9.2) Simulate e-banking login beforehand to avoid login during the authorization flow using:
    • Opening E-Banking login form and submit login credentials. These steps could also be performed manually by opening the authorizationUrl [7] in a browser.
    • After successful login, the simulator automatically grants consents to all available resources.
  • (7) Initiate OAuth 2.0 authorization code grant flow, including redirectUri, state, scope and username.
    • "redirectUri": Location for redirect from SP to SU at step 17
    • "scope": Indicates the desired access rights according to the bLink APIs. On production, the applied scopes need to match with the admitted APIs.
    • "username": Provides the username of the end-user using the service of the SU
  • (18) Initiates the token request to bLink and SP, providing clientId, authorization grant-type, AuthCode, RedirectUri and username in the body of the request.
  • (24) Initiates the username validation request to bLink and SP in order to ensure that the username was not manipulated through an external party during the consent flow.
  • e-banking logout triggers session logout to simulator UI.

The following items describe the basic calls that will be performed with the security simulator for Consent 2.0 with CaaS (the numbers each correspond to a specific step in Consent Management 2.0 with CaaS).

  • (4) Get list of active Providers: This request retrieves a list of all active Service Providers registered on this specific bLink testing environment.
  • (A) Create Permission for a specified userId to selected providerId.
    • Parameters:
      • providerId: Indicates the SP to which resources the user wants to have access to. As per default settings of the collection, the bLink Simulator 2 is selected.
      • userId: Id of the end-user, which has to be defined by the SU
    • Request body:
      • username: Unambiguous recognition of the user who authorizes the consent. The username will be displayed to the user and must be confirmed in the provider's e-banking system.
      • scopes: Indicates the desired access rights according to the bLink APIs. On production, the applied scopes need to match with the admitted APIs. Multiple scopes can be requested by separating the scopes with "whitespace"
  • After submission of the request, a permission was created with status "received". The generated "authorizationUri" is used to initiate the Authorization Code Grant Flow in step [7].
  • (8.1-9.2) Simulate e-banking login beforehand to enable consent flow without manual browser interaction:
    • Opening E-Banking login form and submit login credentials. These steps could also be performed manually by opening the authorizationUrl [7] in a browser.
    • After successful login, the simulator automatically grants consents to all available resources.
  • [7] Initiate OAuth 2.0 authorization code grant flow by , including redirectUri, state, scope and username. (AuthorizationUrl may also be opened in browser and processed by manual login)
    • "redirectUri": Location for redirect from SP to SU at step 17
    • "scope": Indicates the desired access rights according to the bLink APIs. On production, the applied scopes need to match with the admitted APIs
    • "username": Provides the username of the end-user using the service of the SU
  • (18) Verify redirect_uri and state, request tokens, and send username linked to state parameter.
  • (24) Send username linked to state parameter.
  • e-banking logout.

Post-Processing of Consent Flow with CaaS

  • To verify, if the consent flow was successful and the permission can be used for use case requests, perform request GET/permission
    • Successful: Permission is in status "valid"
    • Failed: Permission remains in status "received" (Check the configured WES credentials in Postman and Error Handling for troubleshooting)
Token Management by bLink Simulator

Tokens issued by the bLink Service Provider simulator are not persisted and will be lost when the simulator is restarted. 

Permissions for the simulator are therefore no longer usable after a restart, but they will appear "valid" until the access token associated to the permission expires and the permission is used in a use case call.

Custom Token Behavior in Service Provider Simulator

To facilitate testing the CaaS flow, the Service Provider simulator (CIDX9999999991) was modified to enable custom token behaviors. The following parameters were introduced which can be used in the authorization request:

ParameterDescription
token_expirationConfigures the lifetime (in seconds) of the access token. (Default 86400)
Notice: If the multiple_tokens_per_user parameter is set to “false” and a valid token already exists for the Service Provider login, then this parameter will be ignored, and the pre-existing token will be returned.
refresh_token_expirationConfigures the lifetime (in seconds) of the refresh token. (Default 604800)
Notice: If the multiple_tokens_per_user parameter is set to “false” and a valid token already exists for the Service Provider login, then this parameter will be ignored, and the pre-existing token will be returned.
multiple_tokens_per_userIndicates (true/false) if multiple tokens are allowed per Service Provider login. (Default false) 

Example​

Add the parameters to the “authorizationUri” returned in the permission creation response:

https://tools-blink-xe.np.sixgroup.com/serviceprovider/api/v2/oauth/authorize?response_type=code&redirect_uri=https://webapp-qa.np.six-group.com/redirect/bankingservices/xe/b-link/v2/api-token&state=f7de02c5-c21e-4162-aa48-e5124903efb8&client_id=CIDX9999999990&username=test_etu_technicaluser1&provider_id=CIDX9999999991&scope=urn:blink:xs2a:ais&multiple_tokens_per_user=true&token_expiration=5&refresh_token_expiration=20 
...

Use Case​

The use case flow aims to test the technical and functional integration of the respective APIs through a simulated SP. The SP simulator can be addressed by sending a request to the specific Target-ID, corresponding base path, API module and version and targeting a specific module endpoint. As a result, the requester will receive a standardized payload containing the information associated with the particular endpoint.

SU sends a request to bLink containing:

  • X-CorAPI-Target-ID → CIDX9999999991 (ID bLink Simulator)
  • Module Name
  • Module Version
  • Specific Endpoint

An example request would contain:

If correctly submitted, the user receives a response with a standardized payload. If submitted incorrectly, the user receives a corresponding problem definition.

A successful response is presented in the code snippet below:

"response Get/customerAccounts": [
    {
        "customerIdentification": "123123456",
        "customerReferenceCurrency": "CHF",
        "accountOverview": [
            {
                "accountIdentification": "CH0204835000626882001",
                "accountIdentificationType": "IBAN",
                "accountType": "cashAccount",
                "accountReferenceCurrency": "CHF",
                "accountName": "Konto/CHF",
                "accountDesignation": "Haushalt",
                "portfolioInformation": {
                    "portfolioIdentification": "876543219",
                    "portfolioReferenceCurrency": "CHF"
                }
            },
            {
                "accountIdentification": "9876.5432",
                "accountIdentificationType": "other",
                "accountType": "safekeepingAccount",
                "accountReferenceCurrency": "CHF",
                "accountName": "Depot/CHF",
                "accountDesignation": "Vermögensverwaltungsmandat Tony",
                "portfolioInformation": {
                    "portfolioIdentification": "876543219",
                    "portfolioReferenceCurrency": "CHF"
                }
            }
        ]
    },
    {
        "customerIdentification": "987987654",
        "customerReferenceCurrency": "EUR",
        "accountOverview": [
            {
                "accountIdentification": "CH0208401000051138778",
                "accountIdentificationType": "IBAN",
                "accountType": "cashAccount",
                "accountReferenceCurrency": "EUR",
                "accountName": "Konto/EUR",
                "accountDesignation": "Cash EUR",
                "portfolioInformation": {
                    "portfolioIdentification": "654987987",
                    "portfolioReferenceCurrency": "EUR"
                }
            },
            {
                "accountIdentification": "CH0208401000051134564",
                "accountIdentificationType": "IBAN",
                "accountType": "cashAccount",
                "accountReferenceCurrency": "USD",
                "accountName": "Konto/USD",
                "accountDesignation": "Cash USD",
                "portfolioInformation": {
                    "portfolioIdentification": "654987987",
                    "portfolioReferenceCurrency": "EUR"
                }
            },
            {
                "accountIdentification": "9876.1231",
                "accountIdentificationType": "other",
                "accountType": "safekeepingAccount",
                "accountReferenceCurrency": "EUR",
                "accountName": "Depot/EUR",
                "accountDesignation": "Discretionary Mandate EUR",
                "portfolioInformation": {
                    "portfolioIdentification": "654987987",
                    "portfolioReferenceCurrency": "EUR"
                }
            }
        ]
    }
]

Upon becoming acquainted with the bLink system and simulator, the SU can start the implementation of the endpoints and integrating the available test data received from the SP simulator.

As soon as the implementation in the SU's application is finished and has reached a mature state, the SU can start the Verification process.

Interaction with actual Service Provider on Testing Environment

The bLink testing environments enables the direct interaction with a Service Provider registered on bLink. To be admitted for the connection to a particular provider, the SU must get in touch with the provider directly by contacting one of the provider's contacts registered in the bLink Directory. In order to gain access to the provider's test environment, a contractual basis must be established, which is often only the case with a project-based approach.

Verification​

The Verification of the Service User's implementation is the final step in the onboarding procedure and part of the admission process to activate new participants on bLink. During this procedure, the participant must verify if the consent flow and applied use cases are correctly implemented and meet the bLink requirements and specifications. The verification procedure consists of a set of predefined tests to verify the following aspects of connectivity, token management, and processing use case API calls. The verification is held in a bilateral meeting between representatives of bLink and the SU, at which the SU presents the implemented functionality directly in its application. A SU can initiate the verification procedure via bLink Support Portal - Technical Validation and will be asked to provide possible timeslots for the meeting.

After successful technical validation, the SU receives a formal confirmation which needs to be attached to the section "Overarch" of the admission dossier "AQUA" or section "Completion" in the admission tool.

Production Go-Live​

Once a Service User passed the bLink admission process, the SU must provide a new certificate that complies with the requirements described in TLS Certificates for configuration and a Go-Live date will be agreed upon. At the specified date, the Services User participant status changes from "ONBOARDING_DEVELOPMENT" to "ACTIVE" and all admitted use cases from "ONBOARDING_CERTIFICATION" to "CERTIFIED".

Last updated on