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 UK

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.

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


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.

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

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

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

<handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSClientTokenValidationHandler"/>
  • 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.

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.

 Click here to see how to enable MLTS...
 <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>

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.

This is available only as a WUM update and is effective from September 03, 2019 (09-03-2019). For more information on updating WSO2 Open Banking, see /wiki/spaces/updates/pages/16318500.

  • 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:
<!-- 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>

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 to find how signing certificates are used for TPP Onboarding.

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:

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

JWS validation support for Waiver 007

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.  

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

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

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

      <!-- 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. Add the following configurations right below the </SigningConfiguration> tag and configure them. 

      <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 and click + to save them.

        Property Nameob-api-version
        Property Value3.1.1

        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:

    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-keyIdempotency key is used as an identifier to check a replication of an action. The use cases of the idempotency key are:
    • Payment initiation request

       Click here see how idempotency key is used in the payment initiation request...

      WSO2 Open Banking validates the idempotency key that is sent in the payment initiation request as x-idempotency-key. A payment initiation request can be replicated in situations like security vulnerabilities and network failures. In that case, the x-idempotency-key secures the payment initiation flow as WSO2 Open Banking checks the existing idempotency keys and generates responses accordingly. 

      1. A payment initiation request is made by the TPP with an idempotency key. 
        For each payment initiation request with unique idempotency keys, the WSO2 Open Banking solution responses exclusively.
      2. There can be two scenarios where the TPP can replicate the idempotency key as below:
        1. The TPP sends the same payment initiation request with the same idempotency key - The WSO2 Open Banking solution sends the same response for the consent ID (HTTP 201)  that was initiated for the payment in step 1.

        2. The TPP sends a different payment initiation request with the same idempotency key - The WSO2 Open Banking solution sends an error (HTTP 401) that was initiated for the payment in step 1 as the idempotency key cannot be duplicated for another payment initiation request.

      See the diagram below to understand how the x-idempotency-key in the payment initiation API resource is validated by WSO2 Open Banking.

    • Payment submission request

       Click here to see how idempotency key is used in the payment submission request...

      In Open Banking, the ASPSP is the entity that saves the idempotency key and responds to payment submission requests. Therefore, the ASPSP must consider the following scenarios and respond accordingly:

      • Payment submission requests with duplicated idempotency keys
      • Payment submission requests with duplicated consent IDs 

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:

curl  POST \
  https://<WSO2_OB_APIM_HOST>:8243/token \ 
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
-d 'grant_type=client_credentials&scope=payments%20openid%20&client_assertion=<CLIENT_ASSERTION_JWT>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&redirect_uri=<APPLICATION_CALLBACK_URL>'
 Click 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.


A TPP can request to enable an application access token/clientId 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:

{ 
"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://<<OB_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:

 Click 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:

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

    <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:

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

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:

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>

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:

{
  "kid": "<CERTIFICATE_FINGERPRINT>",
  "alg": "<SUPPORTED_ALGORITHM>",
  "typ": "JWT"
}
{
  "max_age": 86400,
  "aud": "<This is the audience that the ID token is intended for. e.g., https://<WSO2_OB_APIM_HOST>:8243/token>",
  "scope": "accounts openid",
  "iss": "<APPLICATIONT_ID>",
  "claims": {
    "id_token": {
      "acr": {
        "values": [
          "urn:openbanking:psd2:sca",
          "urn:openbanking:psd2:ca"
        ],
        "essential": true
      },
      "openbanking_intent_id": {
        "value": "<CONSENTID>",
        "essential": true
      }
    },
    "userinfo": {
      "openbanking_intent_id": {
        "value": "<CONSENTID>",
        "essential": true
      }
    }
  },
  "response_type": "<code:Retrieves authorize code/code id_token: Retrieves authorize token and ID token>",   
  "redirect_uri": "<CLIENT_APPLICATION_REDIRECT_URI>",
  "state": "YWlzcDozMTQ2",
  "exp": <EPOCH_TIME_OF_TOKEN_EXPIRATION>,
  "nonce": "<PREVENTS_REPLAY_ATTACKS>",
  "client_id": "<APPLICATION_ID>"
}

 Click 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:

https://<WSO2_OB_APIM_HOST>:8243/authorize/?response_type=<RESPONSE_TYPE>&client_id=<APPLICATION_ID>&scope=payments%20openid&redirect_uri=<APPLICATION_REDIRECT_URI>&state=YWlzcDozMTQ2&request=<REQUEST_OBJECT>&prompt=login&nonce=<REQUEST_OBJECT_NONCE>


Sources of Information