This documentation is for WSO2 Open Banking version 1.3.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

Hybrid Flow

According to the Open Banking security profile, it is recommended to use the OpenID Connect (OIDC) Hybrid grant type. Hybrid flow uses both the Client Credentials and Authorization Code grant types.

  • Client Credentials grant type allows you to get a token using the client id. The following endpoints require an application access token obtained using the Client Credentials grant type.
    • Payments :
      POST /payments
      GET /payment-submissions/{PaymentSubmissionId}
    • Accounts:
      POST /account-requests
  • Authorization code

          The authorization code obtained by Third Party Service Provider (TPP) after the Payment Service User (PSU) authorizes the consent, is exchanged for a user access token.


Token endpoint authentication methods

The security profile states the following authentication methods.

  • Mutual Transport Layer Security (MTLS ) Client Authentication

  • Client Secret Basic or Client Secret POST

  • Private Key JWT

Out of the above, the recommended methods in the specification are TLS Client authentication and Private Key JWT.


MTLS Client Authentication

The POST request is authenticated using the transport certificate. The transport certificate should be sent in the authentication request. See the example below.


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 


Add the following configurations.

  1. Define the following in <OB_KM_ROOT>/repository/conf/identity/identity.xml file under the property:

    <!-- Open Banking Mutual TLS Authenticator -->
    <EventListener  enable="true"
                   name="com.wso2.finance.open.banking.mtls.authenticator.OBMutualTLSClientAuthenticator" 
                   orderId="26" type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"/>
  2. Add the following in<OB_APIM_ROOT>/repository/deployment/server/synapse-configs/default/api/ _TokenAPI.xml, under the handlers section.

    <handler class="com.wso2.finance.open.banking.mtls.validator.handler.GatewayClientAuthenticationHandler"/>
  3. 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.

Private key JWT Authentication

The request is authenticated using a JWT that is sent in the request. The JWT is signed using the signing keys of the TPP. The signature is verified using the keys retrieved from jwks endpoint or the Service Provider certificate. Find below example on a JWT authentication.

{
 “alg” : “<<This will be the algorithm used for signing>>”,
 “kid” : “<<This will be the certificate fingerprint>>”,
 “type” : “JWT”
}

{
 “iss” : “<<This is the issue of the token, e.g., client ID of your application>>”,
 “sub” : “<<This is the subject identifier of the token, 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_OBAM_HOST>>:8243/token>>”
}
<signature>


See the below example on cURL command for the POST request.

Curl -v POST -H “Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1” -k -d
“Grant_type=client_credentials&scope=accounts&client_assertion_type=urn%Aietf%3Aparams%3Aoauth%Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<pass the signed key generated in the above>>&redirect_uri=<<The callback URL of your application>>” https://<<WSO2_OBAM_HOST>>:8243/TOKENAPI/v1.0.0/


Transport Level Security

It is recommended by Open Banking security profile to ensure mutual TLS. In order to ensure that MTLS has occurred, WSO2 Open Banking solution uses the handlers as follows.

  • MTLSValidationHandler
    This handler ensures that mutual TLS has taken place by checking if the transport certificate is available as a property in the Axis2 message context.
  • MTLSClientTokenValidationHandler
    This handler ensures that the transport certificate sent in the request when  invoking a particular resource. The procedure is the same as the transport certificate that was used to  a token.
  • MTLSCertValidationHandler
    This handler allows a transport certificate to be sent as a header in the request, in situations where MTLS is terminated before reaching the APIM gateway. This 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.

    • An ASPSP should include the transport certificate in a header if MTLS is terminated before reaching the APIM gateway. Configure the header name for the transport certificate in the <WSO2_OB_APIM_Home>repository/conf/finance/open-banking.xml file under the <TransportCertificateHeader> property. 

      Add the following property as the last module under Global Engaged Modules in the <APIM_HOME>/repository/conf/axis2 file.

      <module ref=mtlscertvalidator/>

      An improvement is sent via WUM to make the transport header configurable. This is effective from September 3, 2019 (09-03-2019). Apply the following configurations in order to update the solution.

    • Add the following configurations under the server root element in the <WSO2_OB_APIM_Home>repository/conf/finance/open-banking.xml file.

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

PSD2 eIDAS attributes validation

Validating PSD2 authorization number

A PSD2 authorization number or an identifier is recognized by the NCA by placing it as the organizational identifier attribute under the subject name field in the PSD2 eIDAS certificate. The structure of an authorization number is formed with the following:

  • Legal person identity type reference
  • Country code that represents the NCA country
  • NCA identifier and PSP identifier

If Mutual TLS is enforced during API invocation, the WSO2 Open Banking solution can validate the organization identifier present in the PSD2 eIDAS certificate with the organizational id associated with the PSP application.

To enable the PSD2 authorization number validation in WSO2 Open Banking, add the following handler in the relevant API synapse configuration file in the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api directory.

Place the handler under the synapse handlers, after org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler.

<handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSClientTokenValidationHandler"/>

To enforce Mutual TLS for the APIs, the above handler needs to be engaged with the <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/> handler.

Validating Role of the PSP

The role of the PSP is declared by NCA via their public registry. The PSP may have one or more of the following roles:

  • Account Servicing Payment Service Provider (ASPSP)
  • Payment Initiation Service Provider (PISP)
  • Account Information Service Provider (AISP)
  • Payment Service Provider issuing Card-Based Payment Instruments Issuer (CBPII)

The PSD2 eIDAS certificates issued for a PSP contains the roles assigned to the PSP. If Mutual TLS is enforced during API invocation, the WSO2 Open banking solution can validate whether the role of the PSP matches with the scopes attached with the API.

To enable the PSD2 role validation in WSO2 Open Banking, add the following handler in the relevant API synapse configuration file in the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api directory.

Place the handler under the synapse handlers, after org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler.  A comma-separated scopes list can be assigned to each of the PSD2 roles. The sample configurations contain the scopes for accounts, payments and confirmation of funds APIs.

If the following handler is already engaged, update its properties as follows:

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

To enforce Mutual TLS for the APIs, the above handler needs to be engaged with the <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/> handler.

  • No labels