API Security for UK

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:

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

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

[open_banking.cert_mgt.client_transport_cert_as_header]
enable = true

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

JSON Web Signature (JWS)

JWS validation support for Waiver 007

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

1. The following handler in the <WSO2_OB_APIM_HOME>/repository/conf/synapse-handlers.xml file must be added to the top of the <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml file as follows:

2. By default, signing configuration is set to false in the <OB_IAM_HOME>/repository/conf/finance/open-banking.xml and <OB_APIM_HOME>/repository/conf/finance/open-banking.xml files. In order to change the configurations, open the  <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml file  and configure as in the TOML Configuration:

3. Open the <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml file and configure the following properties.

   [open_banking.ob_identity_retriever]
   server.signing_cert_alias = wso2carbon
   server.signing_cert_kid = 1234
   jwks_retriever.size_limit = 51200
   jwks_retriever.connection_timeout = 2000
   jwks_retriever.read_timeout = 2000

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 Name	ob-api-version
         Property Value	3.1.5

         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:

         

5. Click Save & Publish.

   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

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

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 'client_id=<CLIENT_ID>&grant_type=client_credentials&scope=accounts%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://<<WSO2_OB_APIM_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. 

[oauth.grant_type]
uma_ticket.retrieve_uma_permission_info_through_introspection = true

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.

Once decoded, the request object that is used to get the TPP's information looks as follows:

{
  "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": "<APPLICATION_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=accounts%20openid&redirect_uri=<APPLICATION_REDIRECT_URI>&state=YWlzcDozMTQ2&request=<REQUEST_OBJECT>&prompt=login&nonce=<REQUEST_OBJECT_NONCE>

For an example on authorising a consent, see the authorisation step in the Account and Transaction API flow.

Sources of Information

• Financial-grade API - Part 1: Read-Only API Security Profile
• Financial-grade API - Part 2: Read and Write API Security Profile