API Security

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:

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

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

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

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 Name	ob-api-version
         Property Value	3.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-key
   

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

curl -k  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>'

{ 
"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>

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:

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

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

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>"
}

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

• The Open Banking Security Profile