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/.

API Security for Berlin

Owned by Former user (Deleted)
Last updated: Jun 11, 2021 by Former user (Deleted)Version comment
5 min read

API Security in WSO2 Open Banking explains how Regulatory Technical Standards (RTS) have elaborated with 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 certificates can be categorised as follows

  • Qualified Website Authentication Certificates (QWAC) to secure the transport layer
  • Qualified Certificates for Electronic Seals (QSealC) to secure the application layer

This document contains the following sections:

PSP certificate registration

Authorisation of a Payment Service Provider (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.

  • PSP submits a certificate that needs to be registered to Trusted Service Provider (TSP) with the required documentation including the PSD2 specific attributes. 

  • The TSP performs an identity validation as required by its certificate policy.

  • The TSP validates PSD2 specific attributes using the information provided by the 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 the NCA.

Qualified Certificates for Website Authentication (QWAC)

QWAC secures 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)

During API invocations, PSPs must use their QWAC to establish a secure TLS channel and protect the transport layer communication from potential attackers on the network. 

The WSO2 Open Banking solution validates the following aspects of the eIDAS QWAC.

  • The certificate is technically correct and is not expired.

  • The certificate is qualified. 

  • The PSD2 information in the certificate such as the PSD2 roles, Authorisation Number, etc. match with the API being invoked.

  • The certificate is not revoked using Certificate Revocation Lists (CRL) or Online Certificate Status Protocol (OCSP) validations. For more information, see the certificate revocation validation section.

Qualified Certificate for Electronic Seal (QsealC)


The Qualified Certificates for Electronic Seal (QsealC) feature is currently WIP.

QSealC provides evidence with a legal assumption of authenticity 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. 

  • A TPP signs the payload of an API invocation request using the private key of its QSealC and sends the signed request along with the QSealC. 

  • The ASPSP extracts the QSealC from the request header and verifies whether the organizational identifier of the QWAC matches with the organizational identifier specified in the QSealC. 

  • The ASPSP performs the certificate revocation validation using OCSP and CRL information included in the QSealC.

  • Once the certificate validation is successful, the ASPSP performs signature validation using the public key contained in the QSealC.

Certificate revocation validation

A certificate is issued by a trusted organization under European Union (EU) legislation, commonly known as a Certificate Authority (CA). It is called a Trust Service Provider (TSP). These certificates are expected to be in use for their entire validity period. However, certain circumstances may cause a certificate to become invalid prior to the expiration of the validity period. For example, a compromise or suspected compromise of the corresponding private key may cause a certificate to become invalid prior to the expiration.  

The following diagram shows how the TSP revokes the certificate:

For qualified certificates (QWACs and QSealCs), a revocation request can originate from the National Competent Authority, which has authorised or registered the PSP. The TSP revokes the certificate based on a verifiably authentic revocation request. 

Under such circumstances, the issuing CA needs to revoke the certificate prior to the scheduled expiry date so that the certificate would no longer be trusted. There are two protocols to check whether a given certificate is revoked by its issuer. 

  • Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing CA.

  • Online Certificate Status Protocol(OCSP) is an internet protocol used for obtaining the revocation status of a digital certificate based on the certificate serial number. The OCSP validation is faster compared to the CRL validation

In WSO2 Open Banking, the revocation status of a certificate is verified primarily using the OCSP validation. If the OCSP validation is unsuccessful, the revocation status is verified using the CRL information. The certificate is rejected if none of these protocols is successful or if the required revocation information is not found on the certificate.

Enable certificate revocation validation

This section explains how to enable the certificate revocation validation feature. Make sure that the following configurations are added in the relevant locations.



  • The mtlscertvalidator module needs to be engaged under the Globally Engaged Modules section in the <WSO2_OB_APIM_HOME>repository/conf/axis2/axis2.xml file.

    <module ref="mtlscertvalidator"/>

  • <CertificateManagement> configurations in the <WSO2_OB_APIM_HOME>repository/conf/finance/open-banking.xml under the server root element.

    <CertificateManagement>
	<!--Set the value of the transport certificate header sent in the request if MTLS is terminated
before the gateway. Default value has been set to ssl.client.auth.cert.X509-->
	<TransportCertificateHeader>ssl.client.auth.cert.X509</TransportCertificateHeader>
	
	<!-- Expiry time for the cache (in seconds) for storing the validation result of the certificates-->
	<ClientCertificateCacheExpiry>3600</ClientCertificateCacheExpiry>
	
	<!-- Enable/Disable certificate OCSP and CRL validation. Default value has been set to true -->
	<CertificateRevocationValidationEnabled>true</CertificateRevocationValidationEnabled>
</CertificateManagement>

    An improvement to the certificate revocation validation is sent via WUM to extend the revocation validation. This is effective from September 3, 2019 (09-03-2019). Apply the following configurations in order to update the solution.

    • Add the following configurations under the <CertificateManagement> element in the <WSO2_OB_APIM_HOME>repository/conf/finance/open-banking.xml file.

      <ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>

<!-- Validate the issuer of the certificate when the client cert is received as a transport header -->
<TransportCertIssuerValidationEnabled>true</TransportCertIssuerValidationEnabled>


<!--Manager class implementation responsible for verifying certificate revocation status-->
<RevocationValidationManagerImplClass>com.wso2.finance.open.banking.mtlscert.validator.service.CertRevocationValidationManagerImpl</RevocationValidationManagerImplClass>


<!-- Retry count for validating certificate OCSP and CRL revocation status -->
<CertificateRevocationValidationRetryCount>3</CertificateRevocationValidationRetryCount>


<!-- List of issuer DNs whose issued certificates needs to be skipped from certificate revocation
    validation.
    e.g. <IssuerDN>CN=Test Pre-Production Issuing CA, O=Test, C=GB</IssuerDN>
    -->
<RevocationValidationExcludedIssuers>
	<IssuerDN></IssuerDN>
</RevocationValidationExcludedIssuers>

<!--Truststore dynamic loading interval (in seconds). Default value has been set to 86400 seconds-->
<TrustStoreDynamicLoadingInterval>86400</TrustStoreDynamicLoadingInterval>

  • To enforce regulatory certificates for API invocations, add the following configuration under the  <CertificateManagement>  tag:  

    This is available only as a WUM update and is effective from April 26, 2021 (04-26-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

    <EnforceRegulatoryCertificates>true</EnforceRegulatoryCertificates>

    Once you add the configuration, you can add the eIDAS certificates to the client trust stores.

See eIDAS Implementation for PSD2 Compliance, for more information.

MTLS bound access token 

According to the OAuth 2.0 Authorisation Framework, TPPs can obtain delegated access to protected resources. This is implemented by binding the user access token to the MTLS certificate.

In order to bind the MTLS certificate of the TPP that is sent in the requests to the user access token, follow the instructions given below:

Before following the instructions given below, configure the client certificate header name in <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml as described here.


  1. Locate the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file and update as follows:

    1. Change the GrantTypeHandlerImplClass of the authorization code grant type as follows:

      <SupportedGrantType>
	<GrantTypeName>authorization_code</GrantTypeName>
    <GrantTypeHandlerImplClass>com.wso2.finance.open.banking.identity.extensions.grant.type.handlers.MTLSTokenBindingAuthorizationCodeGrantHandler</GrantTypeHandlerImplClass>
</SupportedGrantType>

    2. Change the GrantTypeHandlerImplClass of the refresh token grant type as follows:

      <SupportedGrantType><GrantTypeName>refresh_token</GrantTypeName> 
<GrantTypeHandlerImplClass>com.wso2.finance.open.banking.identity.extensions.grant.type.handlers.MTLSTokenBindingRefreshGrantHandler</GrantTypeHandlerImplClass>
</SupportedGrantType>

    3. Add the following event listeners under <EventListeners> in <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml:

      <EventListener enable="true" name="com.wso2.finance.open.banking.identity.extensions.introspection.OBIntrospectionResponseInterceptor" orderId="27" type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"/>
 
<EventListener enable="true" name="com.wso2.finance.open.banking.identity.extensions.introspection.OBIntrospectionDataProvider" orderId="28" type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"/>

    4. Add the following configs under <Server> element:

      <Introspection>
    <EnableDataProviders>true</EnableDataProviders>
</Introspection>

  2. Whitelist  the <ScopeWhitelist> property inside the <OAuthConfigurations> section in <WSO2_OB_KM_HOME>/repository/conf/api-manager.xml  as follows:

    <Scope>^x5t.*</Scope>