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
- Application layer security
- Token endpoint security
- Authorisation endpoint security
- Sources of Information
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.
validates the subject domain name of the certificate during API invocations with the certificate information gathered during the registration.
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
Click here to see how to enable MLTS...
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.
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 Updating WSO2 Products.
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 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_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:
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="as the first handler. ">
Make sure the handler given blow is available in the
velocity_template.xmlfile under Accounts, Payment and COF APIs.
Add the following handler as the last handler in the
Add the following configurations under the
Add the following configurations right below the
</SigningConfiguration>tag and configure them.
- 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 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.
- Click Save & Publish.
- Sign in to the API Publisher (
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.
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
Idempotency key is used as an identifier to check a replication of an action. The use cases of the idempotency key are:
Payment initiation requestClick 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.
- 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.
- There can be two scenarios where the TPP can replicate the idempotency key as below:
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.
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.
- A payment initiation request is made by the TPP with an idempotency key.
Payment submission requestClick 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:
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/clientId 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:
|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:
Define the following in
<WSO2_OB_KM_HOME>/repository/conf/identity/identity.xmlfile under the property:
Add the following handler to the
<OB_APIM_ROOT>/repository/deployment/server/synapse-configs/default/api/ _TokenAPI.xmlfile, 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.
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.
<WSO2_OB_KM_HOME>/repository/conf/identity/identity.xmlfile and update as follows:
authorization codegrant type as follows:
refresh tokengrant type as follows:
Add the following event listeners under
Add the following configs under
Whitelist the <
ScopeWhitelist>property inside the <
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:
|openbanking_intent_id||The consent id of the originating request.|
The type of authorisation supports in the well-known configuration endpoint.
Possible values are
|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: