API Security for Berlin

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.MTLSValidationHandler"/>

<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 attacks on integrity and non repudiation of data.

For more information on QSealC, QWAC, and eIDAS Implementation to support PSD2 Compliance, see eIDAS Implementation for PSD2 Compliance.

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

• OAuth 2.0 Famework