API Security in WSO2 Open Banking explains the elaboration of Regulatory Technical Standards (RTS) with Payment Service Directive 2 (PSD2). It enhances consumer protection, promotes innovation and improves the security of payment services across the European Union. As mentioned in the Berlin Group implementation guide, eIDAS certification is used for QWAC in the transport layer and for QSeal in the application layer. In this section, it describes how transport and application layer security is involved in the below steps. These steps secure the APIs used in WSO2 Open Banking. Let’s see how it is done.
PSP Certificate registration
An authorization of PSP has to be approved/rejected by the National Competent Authority (NCA) that is responsible for payment services in their country. Following are the steps of PSP certificate registration.
TSP) with the required documentation including the PSD2 specific attributes. For more information on the attributes that WSO2 Open Banking solution validates, refer PSD2 certificate specific attributes validation.PSP submits a certificate that needs to be registered to Trusted Service Provider (
The TSP performs an identity validation as required by its certificate policy.
The TSP validates PSD2 specific attributes using the information provided by NCA.
The TSP issues the qualified certificate in compliance with the profile requirements given by the PSU.
PSP receives the certificate that is now approved by NCA.
A WUM update introduces certificate revocation validation in the WSO2 Open Banking 1.3.0 solution. This is effective from September 3, 2019 (09-03-2019). Apply the following configurations in order to update the solution.
Certificate revocation validation
WSO2 Open Banking solution uses two types of certificates. Namely, Certificates for Website Authentication (QWAC) and Certificates for Electronic Seals (QsealC) that are trusted certificates by ensuring the validity against certificate status services. Certificate status services are Online Certificate Status Protocol (OCSP) and Certificate Revocation List (CRL) provided by the TSP. A revocation can happen through a qualified TSP or a revocation request can originate from the NCA, which has authorized or registered the payment service provider.
Below diagram shows how the TSP revokes the certificate.
- Update the axis2.xml file
Global Engaged Modulessection in the
- Update the open-banking.xml file
Add the following configurations under the
Server root element in the
Certificates for Website Authentication (QWAC)
QWAC is used to secure communication by identifying and authenticating the communicating parties. Parties involved in the communication who are identified and authenticated by QWAC:
- Payment initiation service providers (PISP)
- Account information service providers (AISP)
- Payment service providers issuing card-based payment instruments (PIISP)
- Account servicing payment service providers (ASPSP)
QWAC must be used to establish a secure TLS channel and protect the communication (in the transport layer) from potential attackers on the network. QWAC ensures the person or the system connecting to the website. But it cannot prove the legally assumed evidence of a transaction to the third party.
The WSO2 Open Banking validates roles of TPP (Third Party Providers) according to the PSD2. During an API call, this validation restricts TPPs accessing APIs if the roles are not mentioned in eIDAS QWAC (Transport layer certificate). The validation checks following aspects of the eIDAS QWAC.
You need to get the latest product updates for your product to use TPP role verification in the current version of WSO2 Open Banking. This feature is available as a product update from April 8, 2019 (04-08-2019) onwards.
- If the certificate is technically correct and has not expired.
- If the certificate is qualified.
- If the certificate contains the required PSD2 information. (i.e., PSD roles, Authorization Number, NCA etc.)
- If the certificate has not been revoked since it was issued by using CRL or OCSP checks.
Steps below describe how to enable the eIDAS QWAC validations during API calls.
Download the latest WUM product for the WSO2 Open Banking API Manager instance. For WUM instructions, see WUM Updates.
This update is effective for the WSO2 Open Banking API Manager instance from 2.6.0 and onwards. To utilise this update, download
Add the following configurations to the
velocity-template.xml file in the
<WSO2_OBAM_HOME>/repository/resources/api_templates/velocity_template.xml in order to enable ClientCertValidationHandler.
Log in to API Publisher as a publisher at
- Click Edit on the existing API.
- Click Manage.
- Click API Properties and enter values under property: psd2Role. See the table below to find the TPP roles for the respective APIs.
|API||psd2Role parameter value|
|Accounts and Transactions API||AISP|
|Payments Initiation API||PISP|
|Funds Confirmation API||PIISP|
Restart the WSO2 Open Banking API Manager instance and try API calls with the certificates.
Certificates for Electronic Seals (QsealC)
QsealCs is used to provide evidence with a legal assumption of authenticity (including identification and authentication of the source) and integrity of a transaction. QsealC ensures the application layer security to protect the data or messages from potential attackers during or after the communication. The receiver of the sealed data can determine who sealed the data. This can also be proven to a third party even after the communication has ended. The evidence of the transaction can be provided by QsealC with legal assumption and can protect the authenticity and integrity of data when relayed through third parties.
A certificate can be either for website authentication or electronic seals, but not both. Therefore, these two types of certificates are not interchangeable. The following diagram elaborates on the flow followed by WSO2 on extracting the certificate through the request header and invoking the URLs provided in the certificate extension for CRL and OCSP. Confirm the validity of a certificate by analyzing the response status. The information about OCSP and CRL are included in the certificate as extensions.
PSD2 certificate specific attributes validation
As in step 1 of PSP certificate registration, there are PSD2 specific attributes that NCA validate to authorize a PSP. Following are the PSD2 specific attributes that are validated by WSO2 Open Banking solution:
Validating PSD2 authorization number/identifier identified by the NCA
authorization number or an
identifier is recognized by the NCA by placing it as
organizationIdentifier attribute under the
subject name field in the QsealC certificate. An
authorization number can form a structure including:
- Legal person identity type reference
- Country code that represents the NCA country
- NCA identifier and PSP identifier
authorization number is not issued by the NCA, then another identifier that is recognized by NCA is used as the
Validating Role of the PSP
The role of the PSP is declared by NCA via their public registry. The PSP may contain one or more of the following roles.
Account Servicing Payment Service Provider (ASPSP)
Payment Initiation Service Provider (PISP)
Account Information Service Provider (AISP)
Payment Service Provider issuing Card-Based Payment Instruments Issuer (CBPII)
Each role is represented by a role identifier and a role name. Any other role that is not defined, has to be defined and registered by an EU recognized organization. WSO2 Open Banking solution validates the role by validating the Object Identifier (OID) attributes to make sure that the registered role is passed through the certificate. OID attributes are stored in QCStatement within the QCstatements extension.
Validating Issuer of the certificate
The name and the identifier of the competent authority are also validated to ensure the issuer of the certificate.
NCA of a country validates the PSD2 specific attributes. Therefore,
Name of the NCA includes in the certificate itself for the identification purpose.
ID of NCA contains a structure including the country code of NCA representing country and the NCA identifier.