API Security for AU

The information security profile is built upon the foundations of the Financial-grade API Read Write Profile (FAPI-RW) and other standards relating to Open ID Connect 1.0 (OIDC). This is the security profile that the Consumer Data Standards (CDS) recommends to ensure API security. It consists of the standards for grant types, authentication and authorisation flows. For more information, see CDS - Security Profile.

The API Security features are not applicable to Phase 1 - Product APIs.

Let’s see how WSO2 Open Banking supports the security profile:

Transport layer security
- Mutual Transport Layer Security (MTLS)
Token endpoint security
- Holder of Key (HoK) validation
Authorisation endpoint security

Transport layer security

Mutual Transport Layer Security (MTLS)

WSO2 Open Banking uses MTLS to check if the message context contains the transport certificate using the following handlers. This is to make sure that the MTLS handshake is successful at the gateway.

Handler Description

MTLSValidationHandler

Ensures that mutual TLS has taken place by checking if the transport certificate is available as a property in the Axis2 message context.

MTLSCertValidationHandler

This handler is applicable if MTLS is terminated at the load balancer level.

The MTLSCertValidationHandler handler 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 Data Recipient'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 TransportCertificateHeader under 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.

Click here to see how to enable MLTS...

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

The load balancer should not allow the Data Recipient to send its certificate as a transport certificate header that is configured in the open-banking.xml under the <TransportCertificateHeader> element.

If such header was found in the Data Recipient’s request, it is mandatory to remove that header from the 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 <WSO2_OB_APIM_Home>repository/conf/finance/open-banking.xml file:

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

[Back to Top]

Token endpoint security

To manage the Data Recipient 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 generating access tokens for the Dynamic Client Registration API. For example:

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=openid&client_assertion=<CLIENT_ASSERTION_JWT>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&redirect_uri=<APPLICATION_CALLBACK_URL>'

Click here to find the parameter descriptions...

Parameter	Description
`grant type`	The 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 Dynamic Client Registration v0.1.
`scope`	Limit of access for the application access token/clientId.
`client_assertion`	The value of the client assertion, generated using the following format: { "alg": "<The algorithm used for signing>", "kid": "<The certificate fingerprint>", "typ": "JWT" } { "iss": "<The issuer of the token, e.g., client ID of your application>", "sub": "<The subject identifier of the issuer which is a unique value, e.g., client ID of your application>", "exp": "<The epoch time of the token expiration date/time>", "iat": "<The epoch time of the token issuance date/time>", "jti": "<An incremental unique value>", "aud": "<The audience that the ID token is intended for, e.g., https://<WSO2_OB_APIM_HOST>:8243/token>" } <signature>
`client_assertion_type`	The type used to pass the client assertion. WSO2 uses the self-signed JSON Web Token (JWT).

The above cURL request results in an access token along with a refresh token and an encrypted id token.

WSO2 Open Banking also uses the Authorization Code grant type to ensure token endpoint security. When a Data Recipient attempts to access a CDS resource; WSO2 Open Banking requests the bank customer to authorise the Data Recipient by granting the consent for the Data Recipient to access that account information. Once the user grants the consent, the user is redirected to the redirect URL of the Data Recipient with the authorization code. Using the generated authorisation code, the Data Recipient 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

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.

curl -X POST \
 https://<WSO2_OB_APIM_HOST>:8243/token \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'cache-control: no-cache' \
 -k --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
 -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION>'

WSO2 Open Banking supports Private Key JWT to secure the token endpoint that is used by Data Recipients to obtain the application and access tokens. Private Key JWT is the default token endpoint authenticator used in WSO2 Open Banking.

Holder of Key (HoK) validation

HolderOfKeyValidationHandler in the API Manager performs this validation to verify that the scope parameter in the access token contains the thumbprint of the TLS certificate sent in the request. For this, the access token needs to be bound with the MTLS certificate.

Mutual Transport Layer Security (MTLS) certificate bound access token

Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and do the following:

Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and do the following:
1. Update the following configuration under <APISecurity><EnableMTLSTokenBinding> to enable this feature.
```
<EnableMTLSTokenBinding>true</EnableMTLSTokenBinding>
```
2. Configure the client certificate header name using the <CertificateManagement><ClientAuthenticationHeader> property as follows:
```
<ClientAuthenticationHeader>x-wso2-mutual-auth-cert</ClientAuthenticationHeader>
```
Add the following handler to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file.
```
<handler class="com.wso2.finance.open.banking.mtls.validator.handler.GatewayClientAuthenticationHandler"/>
```

[Back to Top]

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 Data Recipient's information looks as follows:

{
  "kid": "<Certificate fingerprint>",
  "typ": "JWT",
  "alg": "<Supported algorithm>"
}
{
  "iss": "<Application ID>",
  "aud": "<Audience the ID Token is intended for. For example,https://<WSO2_OB_APIM_HOST>:8243/token>",
  "response_type": "<code:Retrieves authorize code, code id_token: Retrieves authorize token and ID token>",
  "exp": <A JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time>,
  "client_id": "<Application ID>",
  "redirect_uri": "<Redirect URL of the client application>",
  "scope": "<Available scopes are bank:accounts.basic:read, bank:accounts.detail:read, bank:transactions:read, bank:payees:read, bank:regular_payments:read, common:customer.basic:read, and common:customer.detail:read >",
  "state": "af0ifjsldkj",
  "nonce": "<Prevents replay attacks>",
  "claims": {
    "sharing_duration": "<Requested duration for sharing, in seconds>",
    "id_token": {
      "acr": {
        "values": ["urn:cds.au:cdr:3"]
      }
    }
  }
}
<signature>

The sharing_duration claim in the request object defines the validity period of the refresh token. This is to limit the validity of the consent to the defined period.

The sample redirect URL for the bank customer to authorise the payment consent looks as follows:

https://<WSO2_OB_APIM_HOST>:8243/authorize?prompt=login&response_type=code id_token&client_id=<APPLICATION_ID>&redirect_uri=<APPLICATION_REDIRECT_URI>&scope=<AUTHORISATION_SCOPE_AS_PER_REQUEST_OBJECT>&nonce=n-0S6_WzA2Mj
&state=af0ifjsldkj HTTP/1.1&request=<REQUEST_OBJECT>

[Back to Top]