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:
ensures that mutual TLS has taken place by checking if the transport certificate is available as a property in the Axis2 message context.
MTLSValidationHandler at the start of the
<handlers> section in the
validates the subject domain name of the certificate during API invocations with the certificate information gathered during the registration.
MTLSClientTokenValidationHandler under handler
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler> in the
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:
<property name="pspRoleValidationEnabled" value="true"/>
<property name="paymentInitiationScopes" value="payments"/>
<property name="accountInformationScopes" value="accounts"/>
<property name="cardBasedPaymentInstrumentsScopes" value="fundsconfirmations"/>
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
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.
|title||Click here to see how to enable MLTS...|
<!-- 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.
<!--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-->
The load balancer should not allow the TPP to send its certificate as a transport certificate header that is configured in the
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
<!-- Enable sending client cert as a transport header when TLS is terminated before reaching
<!-- Validate the issuer of the certificate when the client cert is received as a transport header-->
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
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:
The certificate is technically correct and is not expired.
The certificate is qualified.
The PSD2 information in the certificate such as the PSD2 roles, Authorization Number, etc. match with the API being invoked.
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_APIM_HOME>/repository/conf/finance/open-banking.xml files under
<SigningConfiguration> parameter. Click here to find the configurations effective to the
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-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 GMT
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.
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
<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")'/>
Make sure the handler given blow is available in the
velocity_template.xml file under Accounts, Payment and COF APIs.
Add the following handler as the last handler in the
<handler name = "UkJwsResponseSignatureHandler" class="com.wso2.finance.open.banking.gateway.jws.UkJwsResponseSignatureHandler"></handler>
Add the following configurations under the
<!-- The following specified APIs will be associated with response signing. -->
Configure the following properties.
Server Key configuration
used for singing purposes IE - message signing
<!-- alias the certificate used for signing (in repository/resources/security/wso2carbon.jks)-->
<!-- 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) -->
- Republish the APIs.
- Sign in to the API Publisher (
- Click the thumbnail of the API to Browse API.
- Go to the Edit API tab.
- By default, you are directed to the Design tab. Go to the Manage tab.
- Make sure the ob-api-version property is available in your API.
Expand API Properties.
Add the following values as Additional properties if it's not available and click + to save.
Set the value of the ob-api-version property according to the version of the API. See the version mentioned in the swagger file.
- Click Save & Publish.
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.
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-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
|PageWithExcerpt||OB140: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:
|PageWithExcerpt||OB140:Domestic Payments v3.1.1|
|title||Click here to find the parameter descriptions...|
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.
Limit of access for the application access token/clientId.
A TPP can request to enable an application access token/clienId to access Accounts/Payments API, or both by specifying the
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>>",
"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>>"
|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 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:
|title||Click here to find how to enable MTLS authenticator...|
Define the following in
<WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file under the property:
<!-- Open Banking Mutual TLS Authenticator -->
Add the following handler to the
<OB_APIM_ROOT>/repository/deployment/server/synapse-configs/default/api/ _TokenAPI.xml file, under the
- 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:
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.
Locate To enable introspection for the data provider, open the
<WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file and Make make sure that the following config under
<Server> element is set to
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:
|PageWithExcerpt||OB140:File Payments v3.1.1|
|title||Click here to find the parameter descriptions...|
|openbanking_intent_id||The consent id of the originating request.|
The type of authorisation supports in the well-known configuration endpoint.
Possible values are
code id_token, code id_token token, or code.
|redirect_uri||The URI that the bank customer must be redirected after the authorisation.|
|state||Restore the state of the application.|
|exp||The expiration of the user access token or application access token.|
|nonce||The nonce generated by the application/user access token.|
|client_id||The id that the bank issues to the TPP.|
The sample redirect URL for the bank customer to authorise the payment consent looks as follows:
|PageWithExcerpt||OB140:File Payments v3.1.1|
Sources of Information