This documentation is for WSO2 Open Banking version 1.5.0. View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Financial API (FAPI) group in the Open ID foundation has created a security profile that certifies both the Account Servicing Payment Service Providers (ASPSPs) and Third Party Providers (TPPs) have correctly configured client and server instances in their open banking implementation. This is the security profile that Open Banking Implementation Entity (OBIE) recommends to ensure API security. It consists of the standards for grant types, authentication and authorisation flows, and eIDAS. For more information on eIDAS, see eIDAS Implementation for PSD2 Compliance.

Let’s see how WSO2 Open Banking supports the security profile:

Table of Content Zone
minLevel2
excludeJWS validation support for Waiver 007
locationtop

Transport layer security

Mutual Transport Layer Security (MTLS)

WSO2 Open Banking uses MTLS to check if:

  • the message context contains the transport certificate to make sure that the MTLS handshake is successful at the gateway
  • the transport certificate bounds with the application when invoking the APIs

through the following handlers:

HandlerDescription
  • MTLSValidationHandler

ensures that mutual TLS has taken place by checking if the transport certificate is available as a property in the Axis2 message context.

Add  MTLSValidationHandler at the start of the  <handlers>  section in the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml  file.

Code Block
<handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/>
  • MTLSClientTokenValidationHandler

Anchor
enableMTLS
enableMTLS
validates the subject domain name of the certificate during API invocations with the certificate information gathered during the registration.

Enable MTLSClientTokenValidationHandler under handler <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler> in the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file.

Code Block
<handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSClientTokenValidationHandler"/>

Anchor
eIDASrolevalidation
eIDASrolevalidation

In addition, this handler is able to validate the TPP role according to eIDAS. If you need to enable the TPP role validation, uncomment the following properties under the handler. Under the "value" parameter, set the scope that you give in the WSO2 Open Banking API Publisher when publishing the relevant API:

Code Block
 <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSClientTokenValidationHandler">
        <property name="pspRoleValidationEnabled" value="true"/>
        <property name="paymentInitiationScopes" value="payments"/>
        <property name="accountInformationScopes" value="accounts"/>
        <property name="cardBasedPaymentInstrumentsScopes" value="fundsconfirmations"/>
</handler>
  • MTLSCertValidationHandler
    Anchor
    MTLSCertValidationHandler
    MTLSCertValidationHandler

ensures that the transport certificate that is sent is valid, by validating the signature of the certificate. The signature of the certificate is validated using the public issuer certificate that is available in the client trust store.

Note

If Mutual Transport Layer Security (MTLS) is terminated before the request reaches the Gateway, retrieve the TPP's certificate from the MTLS session and include as a transport certificate header. By default, the gateway expects ssl.client.auth.cert.X509 as the transport header. Include the value for the transport certificate header in TransportCertificateHeader under CertificateManagement element of <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml and  <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml . See the sample configuration below.

Expand
titleClick here to see how to enable MLTS...
Code Block
languagexml
 <CertificateManagement>
        <!-- In order to enable the client certificate validation feature (Certificate Expiry, Signature and
        Revocation validation during MTLS), the following module needs to be engaged under the "Global Engaged
        Modules" section in the axis2.xml file.

        <module ref="mtlscertvalidator"/>
        -->

        <!--Set the value of the transport certificate header sent in the request if MTLS is terminated before the
        gateway default value is ssl.client.auth.cert.X509-->
        <TransportCertificateHeader>ssl.client.auth.cert.X509</TransportCertificateHeader>
</CertificateManagement>
Warning

The load balancer should not allow the TPP to send its certificate as a transport certificate header that is configured in the open-banking.xml under <TransportCertificateHeader> element. 

If such header was found in the TPP’s request, it is mandatory to remove that header from the TPP’s request. This is applicable even when the MTLS session is not terminated at the load balancer.


  • Make the transport header configurable by adding the following configurations under the <CertificateManagement> element in the <WSO2_OB_APIM_Home>repository/conf/finance/open-banking.xml file:
Code Block
<!-- Enable sending client cert as a transport header when TLS is terminated before reaching
Gateway-->
<ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>
 
<!-- Validate the issuer of the certificate when the client cert is received as a transport header-->
 <TransportCertIssuerValidationEnabled>true</TransportCertIssuerValidationEnabled>
Warning

If the APIs are already published, the above should be added to the  <handlers>  property in the synapse configurations of the published APIs, which are located in the  <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api  file.

Qualified Web Authentication Certificates (QWAC)

During API invocations, PSPs can use their eIDAS Qualified Web Authentication Certificates (QWAC) to establish a secure Transport Layer Security (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 QWAC if it is used for an API invocation:

  1. The certificate is technically correct and is not expired.

  2. The certificate is qualified. 

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

  4. The certificate is not revoked using Certificate Revocation Lists (CRL) or Online Certificate Status Protocol (OCSP) validations.


Application layer security

Following are the security mechanisms used in WSO2 Open Banking to ensure Application layer security.

Qualified Certificate for Electronic Seal (QSealC)

WSO2 Open Banking allows using QSeal certificates as signing certificates in application layer security to ensure protecting the data or messages from potential attackers during or after the communication. See Dynamic Client Registration v3.2, Manual Client Registration, Using Signup Workflows to find how signing certificates are used for TPP Onboarding.

For more information on QSealC, QWAC, and eIDAS Implementation to support PSD2 Compliance, see eIDAS Implementation for PSD2 Compliance.

JSON Web Signature (JWS)

In WSO2 Open Banking, JWS is valid only if the algorithm used for JWS is acceptable for the application. The acceptable algorithms are configured in the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml and <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml files under <SigningConfiguration> parameter. Click here to find the configurations effective to the open-banking.xml file.

To create a JWS, see the instructions in the Open Banking Security Profile.

In WSO2 Open Banking, the JWS is used only when invoking the payments API. Given below is a sample header for a payment submission API call:

Code Block
POST /domestic-payments HTTP/1.1
Authorization: Bearer <USER_ACCESS_TOKEN>
x-idempotency-key: FRESNO.1317.GFX.22
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
Multiexcerpt
MultiExcerptNameJWS W007
JWS validation support for Waiver 007
Info

This is available only as a WUM update and is effective from July 06, 2020 (07-06-2020). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

JWS signature validation supports Waiver 007 with the update above. To use this feature, follow the instructions below.

  1. Open <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml.

    1.  Add the following under <handlers xmlns=" http://ws.apache.org/ns/synapse "> as the first handler.  

      Code Block
      languagexml
      ## API properties handler to add the required properties to the message context
      <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>
    2. Make sure the handler given blow is available in the velocity_template.xml file under Accounts, Payment and COF APIs. 

      Code Block
      languagexml
      <handler class="com.wso2.finance.open.banking.gateway.jws.UKJwsSignatureHandler"/>
  2. Add the following handler as the last handler in the <WSO2_OB_APIM_HOME>/repository/conf/synapse-handlers.xml file. 

    Code Block
    languagexml
    <handler name = "UkJwsResponseSignatureHandler" class="com.wso2.finance.open.banking.gateway.jws.UkJwsResponseSignatureHandler"></handler>
  3. Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file

    1. Add the following configurations under the <SigningConfiguration> tag.  

      Code Block
      languagexml
      <!-- The following specified APIs will be associated with response signing. -->
      <ResponseSignatureRequiredAPIs>
      	<APIContext>/open-banking/v3.0/pisp/</APIContext>
      	<APIContext>/open-banking/v3.1/pisp/</APIContext>
      </ResponseSignatureRequiredAPIs>
    2. Configure the following properties.

      Code Block
      languagexml
      <OBIdentityRetriever>
          <!--
                 Server Key configuration
                 used for singing purposes IE - message signing
             -->
          <Server>
              <!-- alias the certificate used for signing (in repository/resources/security/wso2carbon.jks)-->
              <SigningCertificateAlias>wso2carbon</SigningCertificateAlias>
              <!-- KID value for primary signing certificate that is exposed by the JWKS endpoint under OIDC well-known endpoint (by default https://localhost:8243/.well-known/openid-configuration) -->
              <SigningCertificateKid></SigningCertificateKid>
          </Server>
      </OBIdentityRetriever>
  4. Republish the APIs. 
    1. Sign in to the API Publisher (https://<WSO2_OB_APIM_HOST>:9443/publisher).
    2. Click the thumbnail of the API to  Browse API.
    3. Go to the  Edit API  tab.
    4. By default, you are directed to the Design tab. Go to the  Manage  tab.
    5. Make sure the ob-api-version  property is available in your API.
      1. Expand    API Properties.

      2. Add the following values as  Additional properties  if it's not available and click + to save.

        Property Nameob-api-version
        Property Value3.1.1
        Note

        Set the value of the ob-api-version property according to the version of the API. See the version mentioned in the swagger file.

        For example:
         

    6. Click    Save & Publish. 

Financial-API (FAPI) headers

WSO2 Open Banking uses a set of REST APIs known as Financial APIs (FAPI) that provide account and transactional information in JSON format. FAPI endpoints are OAuth 2.0 protected due to the sensitive information it consists of. Therefore, FAPI headers ensure that only the resource owner who submitted the user access token can retrieve information.

There are two scenarios using Financial API (FAPI) headers in WSO2 Open Banking. 

  1. x-fapi-interaction-id
    x-fapi-interaction-id is sent in the API requests in order to identify them uniquely. As for an example, see the sample request header generated to invoke POST /file-payments :

    Code Block
    POST /file-payments HTTP/1.1Authorization: Bearer <USER_ACCESS_TOKEN>
    x-idempotency-key: FRESCO.21302.GFX.20
    x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
    x-fapi-financial-id: OB/2017/001
    x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
    x-fapi-customer-ip-address: 104.25.212.99
    x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
    Content-Type: application/json
    Accept: application/json
  2. x-idempotency-key
    Multiexcerpt include
    SpaceWithExcerptOB140
    MultiExcerptNameIdempotencyKey
    PageWithExcerptOB140:Integrating with the Core Banking System

Token endpoint security

To manage the TPP interaction with the resources exposed via the banks’ APIs, WSO2 Open Banking uses:

  • Client credentials grant type
  • Authorisation code grant type

WSO2 Open Banking uses Client credentials grant type when a TPP generates an application access token in order to access the API resources in both Accounts and Payments APIs. A sample cURL command to generate the application access token looks as follows:

Multiexcerpt include
SpaceWithExcerptOB140
MultiExcerptNameapplicatinAccesstoken
PageWithExcerptOB140:Domestic Payments v3.1.1
Expand
titleClick here to find the parameter descriptions...
ParameterDescription
grant type

Grant type used to generate an application access token.

The above example is for an application access token generated using Client Credentials grant type. For more information, see Generate application access token.

scope
Limit of access for the application access token/clientId.


Note

A TPP can request to enable an application access token/clienId to access Accounts/Payments API, or both by specifying the scope parameter.

client_assertion_type

The type used to pass the client assertion. WSO2 uses the self-signed JSON Web Token (JWT). The format of the client assertion looks as follows:

Code Block
{ 
"alg": "<<This will be the algorithm used for signing>>", 
"kid": "<<This will be the certificate fingerprint>>", 
"typ": "JWT" 
} 

{ 
"iss": "<<This is the issue of the token, e.g., client ID of your application>>", 
"sub": "<<This is the subject identifier of the issuer, e.g., client ID of your application>>", 
"exp": <<This is epoch time of the token expiration date/time>>, 
"iat": <<This is epoch time of the token issuance date/time>>, 
"jti": "<<This is an incremental unique value>>", 
"aud": "<<This is the audience that the ID token is intended for, e.g., https://<<WSO2_OB_APIM_HOST>>:8243/token>>" 
} 

<signature>
client_assertion The value of the client assertion, generated using the format shown in the above step.

WSO2 Open Banking also uses the Authorization Code grant type to ensure token endpoint security. When a TPP attempts to access accounts or payment information; WSO2 Open Banking requests the bank customer to authorise the TPP by granting the consent for the TPP to access that account or payment information. Once the PSU grants the consent only, the PSU is redirected to the redirect URL of the TPP with the authorization code. Using the generated authorisation code, the TPP can generate the user access token. For instructions on generating a user access token, see Generate user access token.

See Authorisation endpoint security that discusses security enhancements for Authorisation code grant type.

Refresh tokens

Refresh tokens are used to get a new user access token from the authentication server in order to access a specific resource. The most common use case is generating a refresh token when the user access token is expired. For the sample curl command, See generating user access token under UK Accounts flow.

WSO2 Open Banking supports Private Key JWT and MTLS to secure the token endpoint that is used by TPPs to obtain the application and access tokens. 

Private Key JWT is the default token endpoint authenticator used in WSO2 Open Banking. If you need to change the token endpoint authenticator to the MTLS, follow the below instructions:

Expand
titleClick here to find how to enable MTLS authenticator...
  1. Define the following in <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file under the property:

    Code Block
    languagexml
    <!-- Open Banking Mutual TLS Authenticator -->
    <EventListener  enable="true"
                   name="com.wso2.finance.open.banking.mtls.authenticator.OBMutualTLSClientAuthenticator" 
                   orderId="26" type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"/>
  2. Add the following handler to the <OB_APIM_ROOT>/repository/deployment/server/synapse-configs/default/api/ _TokenAPI.xml file, under the <handlers> section.

    Code Block
    <handler class="com.wso2.finance.open.banking.mtls.validator.handler.GatewayClientAuthenticationHandler"/>
    <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/>
  3. The request intercepts at the gateway from a custom handler (GatewayClientAuthenticationHandler), and the certificate is sent as a header to the authenticator in Identity Server. 

    The signature of the certificate is validated against the application certificate or JWKS endpoint stored in the Service Provider. When JWKS is used for verification, the transport certificates are retrieved from JWKS and cached for future verification. Configuration for caching and JWKS retrieval for TLS Client Auth can be found in open-banking.xml under <OBIdentityRetriever> parameter.

Once you enable MTLS for token endpoint authentication, the user access token request looks as follows:

Note

Make sure you use the transport certificate and the private key in the request.

Code Block
curl -k -d "grant_type=client_credentials&scope=accounts&client_id=<clientId>" -H "Content-Type: application/x-www-form-urlencoded" --cert cert.crt --key key.key -X POST https://localhost:8243/token

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:

Note

Note that you have to enable MTLS token binding and configure the client certificate header name in <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml as described here.

To enable introspection for the data provider, open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file and make sure that the following config under <Server> element is set to true:

Code Block
languagexml
<Introspection>
    <EnableDataProviders>true</EnableDataProviders>
</Introspection>



Authorisation endpoint security

WSO2 Open Banking enhances the security of the authorisation code grant type in authorisation endpoint security with request object and response type attributes.

The request object that is used to get TPP user's information looks as follows once decoded:

Multiexcerpt include
SpaceWithExcerptOB140
MultiExcerptNameauthorisationRequestUsingHybridFlow
PageWithExcerptOB140:File Payments v3.1.1

Expand
titleClick here to find the parameter descriptions...
ParameterDescription
openbanking_intent_idThe consent id of the originating request.
response_type

The type of authorisation supports in the well-known configuration endpoint.

Possible values are code id_token, code id_token token, or code.

redirect_uriThe URI that the bank customer must be redirected after the authorisation.
stateRestore the state of the application.
expThe expiration of the user access token or application access token.
nonceThe nonce generated by the application/user access token.
client_idThe id that the bank issues to the TPP.

The sample redirect URL for the bank customer to authorise the payment consent looks as follows:

Multiexcerpt include
SpaceWithExcerptOB140
MultiExcerptNamecURLcommandAuthoriseRequestHybridFlow
PageWithExcerptOB140:File Payments v3.1.1


Sources of Information