This documentation is for WSO2 Open Banking version 1.3.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

This document discusses how WSO2 Open Banking has implemented the Electronic Identification, Authentication & Trust Services (eIDAS) Regulation.

Before you begin:

  • In order to try out the flows with the eIDAS approach, Third-Party Providers(TPPs) have to be registered in a Qualified Trust Service Provider (QTSP). 

    If you are testing the WSO2 Open Banking solution for UK compliance, you can use either of the following:

    • Original eIDAS certificates:
      • Qualified Website Authentication Certificate (QWAC)
      • Qualified e-Seal Certificate (QSealC)
    • Open Banking (OB) certificates:
      • Open Banking Web Authentication Certificate (OBWAC)
      • Open Banking e-Seal Certificate (OBSealC)

    OB certificates are issued by the Open Banking Directory upon registering as a Third-Party Provider (TPP). Click here to find instructions on generating OBWAC and OBSealC. 

  • In order to support eIDAS or OB certificates in WSO2 Open Banking, you need to update the client trust stores. 

     Click here to see how it is done...

    In order to support OB certificates in WSO2 Open Banking, upload the OBIE root and issuer certificates to the client trust stores as follows:

    1. Download the OBIE root and issuer certificates from the following locations:
      1. In sandbox environment, upload certificates from https://openbanking.atlassian.net/wiki/spaces/DZ/pages/252018873/OB+Root+and+Issuing+Certificates+for+Sandbox.

      2. In production environment, upload certificates from https://openbanking.atlassian.net/wiki/spaces/DZ/pages/80544075/OB+Root+and+Issuing+Certificates+for+Production.

    2. Use the following commands to add the certificate to the client trust stores of WSO2 OB APIM and WSO2 OB KM:

      Add root certificate
      keytool -import -alias tpproot -file <OB_ROOT_CERT> -keystore client-truststore.jks -storepass wso2carbon
      Add issuer certificate
      keytool -import -alias tppissuer -file <OB_ISSUING_CERT> -keystore client-truststore.jks -storepass wso2carbon

      The client trust stores are located in the WSO2 OB APIM and WSO2 OB KM servers in the following locations respectively:

      • <WSO2_OB_APIM>/repository/resources/security/client-truststore.jks
      • <WSO2_OB_KM>/repository/resources/security/client-truststore.jks

    In order to support QWAC and QSealC in WSO2 Open Banking, the client trust store must contain all the root certificates of the QTSPs in the UK and the EU region.

    • National Competent Authorities (NCAs) of each region maintains a list of QTSPs and QTSP certificates in their regions. The QTSP list and links to their QTSP certificates are aggregated to a single list named as List of Trust Lists (LoTL). 
    • You need to download all the QTSP certificates from LoTL and update the client trust store of WSO2 OB APIM. WSO2 Open Banking provides LoTL integrator, which is a separate tool to achieve this task. 
    • Once downloaded, follow the steps given below to run LoTL integrator:

      LoTL integrator requires a connection to each of the national trust lists hosted by NCAs in the EU region. Please make sure that the environment that you are running the tool has the required network-level access for each of the trust lists in the EU region.

      1. Create a copy of the client trust store in <WSO2_OB_APIM_HOME>/repository/resources/security/client-truststore.jks. When the tool asks for the path of the client trust store, provide the location to the copied client trust store.
      2. Extract the LoTL integrator and run the below command inside the directory of the LoTL integrator:

        java -jar custom-lotl-integrator-jar-with-dependencies.jar
      3. Provide the correct information when the tool asks for the path and password to the client trust store.
      4. Once you set up the client trust store successfully, replace the copy with the original client trust store. We encourage you to backup the original client trust store before the replacement.
      5. Restart the WSO2 OB APIM server.

In WSO2 Open Banking, eIDAS approach can be categorised into 3 flows:

Client registration

WSO2 Open Banking provides eIDAS support for Dynamic Client Registration (DCR) and Manual Client Registration (MCR). For client registration, the following certificates must be used:

  • A website authentication certificate to secure the transport layer (QWAC or OBWAC)
  • An e-seal certificate to secure the application layer (QSealC or OBSealC)

Dynamic Client Registration (DCR)

  1. The TPP must generate a Software Statement Assertion (SSA) in the OB Directory.
  2. The TPP must associate transport and application layer certificates with the Software Statement.
  3. Once associated, the certificates are available in the SSA under the software_jwks_endpoint parameter.
  4. Invoke the DCR endpoint using the QWAC/OBWAC as the transport certificate in the request header. To find sample request and response for the API invocation, see Registering an application.

    The application registration request relies on Mutual Transport Layer Security (MTLS) authentication for TPP authentication to validate the TPP. Thereby, the Account Servicing Payment Service Provider (ASPSP) extracts:

    • software_jwks_endpoint from the SSA and validates whether the transport certificate that is used to initiate the MTLS connection contains in the software_jwks_endpoint.
    • software_jwks_endpoint from the SSA and stores in the application for future validations during token generation and API invocations.

    The following diagram describes how the ASPSP validates the TPP in the DCR flow:

Following documents explain how to configure DCR in WSO2 Open Banking:

Manual Client Registration (MCR)

  1. The TPP must generate a Software Statement Assertion (SSA) in the OB Directory.
  2. The TPP must associate transport and application layer certificates with the Software Statement.
  3. Once associated, the certificates are available in the SSA under the  software_jwks_endpoint parameter.
  4. Log in to the API Store in WSO2 Open Banking and create an application by providing the generated Software Statement Assertion (SSA). To find how it is done, see Manual Client Registration - Create an application. The ASPSP extracts software_jwks_endpoint from the SSA and saves it in the application for future validations during token generation and API invocations.

Follow the instructions given here to configure DCR in WSO2 Open Banking:

Token generation

WSO2 Open Banking supports Private Key JSON Web Token (JWT) and MTLS as token authentication methods. 

Authentication methodDescription
Private Key JWT

Sign JWT using QSealC or OBSealC.

The signing certificate needs to be mentioned under software_jwks_endpoint of the SSA. 

MTLS

Initiate the access token request using the QWAC or OBWAC certificate as the certificate for mutual authentication. In the request header, mention the path to the public and private keys of the transport certificate. To find the sample request for the user-access token, see Account and Transaction API.

Thereby, the public key of the transport certificate provided for the token endpoint will be verified against the software_jwks_endpoint in the SSA.

The following diagram describes how the token generation is implemented in WSO2 Open Banking with accordance to eIDAS:

For more information about the token authentication methods used in WSO2 Open Banking, see API Security.

API invocation

APIs are protected using MTLS, which uses the QWAC or OBWAC as the transport certificate in each of the request headers. To enable to MTLS validations in the API invocations, see Configuring Mutual Transport Layer Security.




  • No labels