This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
eIDAS Implementation for PSD2 Compliance
This document discusses how WSO2 Open Banking has implemented the Electronic Identification and 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.
- Original eIDAS certificates:
In order to support eIDAS or OB certificates in WSO2 Open Banking, you need to update the client trust stores.
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)
TPP Validation Service
TPP validation service allows OBIE-registered Account Servicing Payment Service Providers (ASPSPs) to validate TPPs from the NCAs. This is done by validating QWAC or OBWAC. Follow the steps to enable this service:
This is available only as a WUM update effective from January 21, 2021 (01-21-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.
Prerequisites:
- Make sure you have uploaded QWAC or OBWAC as the transport certificate in
<WSO2_OB_APIM_HOME>/repository/resources/security/wso2carbon.jks.
- Update
<WSO2_OB_APIM_HOME>/repository/resources/security/client-truststore.jks
with the OBIE root, issuer certificates as mentioned here.
- Add the QSealC keypair corresponding to QWAC or OBSealC keypair corresponding to OBWAC into a new JKS. For example,
wso2carbon-signing.jks.
- Place the JKS file in the
<WSO2_OB_APIM_HOME>/repository/resources/security
directory. Open the
<WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml
file:Add the following configs under the
<CertificateManagement>
section:- The
SoftwareStatementId
value needs to be configured according to the OBWAC/QWAC that has been configured in the<WSO2_OB_APIM_HOME>/repository/resources/security/wso2carbon.jks
. The OBIE service-related endpoints are for the OBIE sandbox environment.
<TPPValidationService> <CacheExpiry>3600</CacheExpiry> <TPPValidationImplClass>com.wso2.finance.open.banking.gateway.service.obie.OBIECertValidationServiceImpl</TPPValidationImplClass> <OBIE> <SoftwareStatementId>ykNOgWd2RgnuoLRRyWBkaY</SoftwareStatementId> <Scopes> <Scope>ASPSPReadAccess</Scope> <Scope>TPPReadAccess</Scope> <Scope>AuthoritiesReadAccess</Scope> </Scopes> <TokenEndpoint>https://matls-sso.openbankingtest.org.uk/as/token.oauth2</TokenEndpoint> <ValidationEndpoint>https://matls-dirapi.openbankingtest.org.uk/certificate/validate</ValidationEndpoint> <RedirectEndpoint>https://matls-api.openbankingtest.org.uk/scim/v2/OBAccountPaymentServiceProviders</RedirectEndpoint> <MemberState>GB</MemberState> </OBIE> <ScopeRegexPatterns> <AISP>accounts+</AISP> <PISP>payments+</PISP> <CBPII>fundsconfirmations+</CBPII> </ScopeRegexPatterns> </TPPValidationService>
- The
Configure the
<SigningKeystore>
tag with the file path of the JKS file that contains the OBSealC.Configure the
<SigningCertificateAlias>
and the<SigningCertificateKid>
tags with the alias and KID value of the signing certificate (OBSealC):<Server> <!-- alias the certificate is under --> <SigningCertificateAlias>signing</SigningCertificateAlias> <!-- KID value for primary signing certificate --> <SigningCertificateKid>1pbTEt6v6_o0WpPFzmNXj6ediKw</SigningCertificateKid> <SigningKeystore> <Location>${carbon.home}/repository/resources/security/wso2carbon-signing.jks</Location> <Password>wso2carbon</Password> <KeyPassword>wso2carbon</KeyPassword> </SigningKeystore> </Server>
- Open the
<WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml
file:Add the following handler as the first handler:
<handler class="com.wso2.finance.open.banking.gateway.common.APIPropertiesHandler"> <property name="xWso2ApiSpec" value='$apiObj.additionalProperties.get("ob-spec")'/> <property name="xWso2ApiVersion" value='$apiObj.additionalProperties.get("ob-api-version")'/> <property name="xWso2ApiType" value='$apiObj.additionalProperties.get("ob-api-type")'/> </handler>
Add the TPP validation handler after the
#if($apiObj.additionalProperties.get("ob-spec") == "uk")
configuration as follows:#if($apiObj.additionalProperties.get("ob-spec") == "uk") ## TPP validation service handler <handler class="com.wso2.finance.open.banking.gateway.common.TPPValidationHandler"/>
- Republish your Accounts, Payments, CoF, and DCR APIs with the
ob-spec, ob-api-version,
andob-api-type
properties. For more information see, Deploying APIs for UK. - Open each API xml file(Accounts, Payments, CoF, and DCR APIs) in
<WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api
and make sure that bothAPIPropertiesHandler
andTPPValidationHandler
are available.
Integrating a Custom Certificate Validation Service
If you want to integrate a custom validation service rather than OBIE, you can configure as follows:
Extend the following interface and implement it for the required certificate validation service.
package com.wso2.finance.open.banking.gateway.service; public interface TPPValidationService { /** * Validate the status of a TPP * * @param peerCertificate Certificate of the TPP * @param requiredPSD2Roles Roles that are required to be validated with the TPP validation service according to * the current flow * @param metadata Metadata information * @return * @throws TPPValidationException */ boolean validate(X509Certificate peerCertificate, List < PSD2RoleEnum > requiredPSD2Roles, Map < String, Object > metadata) throws TPPValidationException; /** * Get the cache key used for the caching the response. Implementation should return an appropriate ID that is * unique to the API flow. * * @param peerCertificate Certificate of the TPP * @param requiredPSD2Roles Roles that are required to be validated with the TPP validation service according to * the current flow * @param metadata Metadata information * @return * @throws TPPValidationException */ String getCacheKey(X509Certificate peerCertificate, List < PSD2RoleEnum > requiredPSD2Roles, Map < String, Object > metadata) throws TPPValidationException; }
Add the following configurations in <
WSO2_OB_APIM_HOME>
/repository/conf/finance/open-banking.xml
under the<CertificateManagement>
section mentioning the fully qualified class name of the extended class under<TPPValidationImplClass>
.<TPPValidationService> <CacheExpiry>3600</CacheExpiry> <TPPValidationImplClass></TPPValidationImplClass> <ScopeRegexPatterns> <AISP>accounts+</AISP> <PISP>payments+</PISP> <CBPII>fundsconfirmations+</CBPII> </ScopeRegexPatterns> </TPPValidationService>
Make sure you have the following handler as the first handler under the
<Handlers>
section in the<WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml
file. Otherwise add the handler.<handler class="com.wso2.finance.open.banking.gateway.common.APIPropertiesHandler"> <property name="xWso2ApiSpec" value='$apiObj.additionalProperties.get("ob-spec")'/> <property name="xWso2ApiVersion" value='$apiObj.additionalProperties.get("ob-api-version")'/> <property name="xWso2ApiType" value='$apiObj.additionalProperties.get("ob-api-type")'/> </handler>
Add the
TPPValidationHandler
handler right after the#if($apiObj.additionalProperties.get("ob-spec") == "uk")
configuration in the<WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml
file.#if($apiObj.additionalProperties.get("ob-spec") == "uk") ## TPP validation service handler <handler class="com.wso2.finance.open.banking.gateway.common.TPPValidationHandler"/>
- Republish your Accounts, Payments, CoF and DCR APIs using publisher. Make sure that you have added the
ob-spec, ob-api-version
andob-api-type
properties before republishing the APIs. - Open each API xml file (Accounts, Payments, CoF and DCR APIs) in
<WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api
directory and make sure that bothAPIPropertiesHandler
andTPPValidationHandler
are added under the<handlers>
section.
Dynamic Client Registration (DCR)
- The TPP must generate a Software Statement Assertion (SSA) in the OB Directory.
- The TPP must associate transport and application layer certificates with the Software Statement.
- Once associated, the certificates are available in the SSA under the
software_jwks_endpoint
parameter. 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 thesoftware_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)
- The TPP must generate a Software Statement Assertion (SSA) in the OB Directory.
- The TPP must associate transport and application layer certificates with the Software Statement.
- Once associated, the certificates are available in the SSA under the
software_jwks_endpoint
parameter. - 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 method | Description |
---|---|
Private Key JWT | Sign JWT using QSealC or OBSealC. The signing certificate needs to be mentioned under |
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 |
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 requests. To enable to MTLS in the API invocations, see Mutual Transport Layer Security.
Account Information Service Provider, Payment Initiation Service Provider, and Card-Based Payment Instrument Issuer are roles for a TPP. This role is validated so that only a particular TPP is allowed to invoke an API. To enable TPP-role validations in the API invocations, see Mutual Transport Layer Security.