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.

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
   Loading

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