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

WSO2 Open Banking 1.3.0 supports OpenID Conformance suite v3.2.1. 

The conformance suite consists of security standards that are defined by the Open ID Foundation (OIDF). It maximises the security of the APIs, providing a robust data flow in Open Banking. An advantage of using OIDF security standards is that the Account Servicing Payment Service Provider (ASPSP) can attest the affiliated payment service providers through a self-certification process. The WSO2 Open Banking solution supports users to comply with a conformance suite that can be configured by the ASPSP.

The following configurations guide you to set up the WSO2 Open Banking solution to specification standards for conformance.

Self-certificate generation

Generate self-signed certificates for development purposes or when the Open Banking directory is not accessible.


This step is not necessary for Open Banking directory certificates.


Root certificate generation

Generate a root certificate by following the steps below. You can use a root certificate to sign client certificates instead of the Open Banking directory certificate.


Parameter NameDescriptionValue
<root_ca_name>Name for root Certification Authority (CA) certificaterootCA


  1. Generate a private key for the root certificate.

    openssl genrsa -des3 -out <root_ca_name>.key 4096
  2. Generate a public certificate for the root certificate.

    openssl req -x509 -new -nodes -key <root_ca_name>.key -sha256 -days 1024 -out <root_ca_name>.crt

Client certificate generation

The following steps can be followed to generate certificates for a client application, which are signed by the previously generated root certificate.

Parameter NameDescriptionValue
<client_name>Unique name for the clienttpp.com
<root_ca_name>Name for root CA (generated in the prior step)rootCA
  1. Generate a private key for the client.

    openssl genrsa -out <client_name>.key 2048
  2. Create a Certificate Signing Request (CSR) for the client. 

    openssl req -new -key <client_name>.key -out <client_name>.csr
  3. Generate a client certificate with a CSR.

    openssl x509 -req -in <client_name>.csr -CA rootCA.crt -CAkey <root_ca_name>.key -CAcreateserial -out <client_signed_cert_name>.crt -days 50000 -sha256

This process can be repeated for any number of clients.

Open Banking API Manager configurations

Axis2 configurations

  1.  In the <WSO2_OBAM_HOME>/repository/conf/axis2/axis2.xml  file, add the following attributes under the <transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener"> property.

    <parameter name="HttpsProtocols">TLSv1.2</parameter> <parameter name="PreferredCiphers">TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</parameter>

    Restart the API Manager server in order to make the changes permanently.

Mutual TLS configuration

Configure the Mutual Transport Layer Security (MTLS) validation handlers in the synapse configurations. It ensures that the authenticated client uses the pre-registered transport certificate to communicate with the API.

  1. Import the root/issuer certificate to the Open Banking Key Manager (OBKM) and Open Banking API Manager (OBAM) client trust stores. Open the following directories and run the command per certificate.

    • <WSO2_OBAM_HOME>/repository/resources/security

    • <WSO2_OBKM_HOME>/repository/resources/security

      keytool -import -alias <unique alias> -file <certificate file> -keystore client-truststore.jks -storepass wso2carbo
  2. In the <WSO2_OBAM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file, add the MTLS validation handler to the token API.

    <handler class="com.wso2.finance.open.banking.mtls.validator.handler.GatewayClientAuthenticationHandler"/> <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/>
  3. In the <WSO2_OBAM_HOME>/repository/deployment/server/synapse-configs/default/api file, add the mutual TLS validation handler and mutual TLS client token validation handler for each resource API (All read/write APIs).

    The above handlers can be added under the <handlers> property in the <WSO2_OBAM_HOME>/repository/resources/api_templates/velocity_template.xml file, which automatically integrates the handlers in the APIs published afterwards.

    1. Add the following handler, 

      <handler class="com.wso2.finance.open.banking.mtls.validator.handler.MTLSValidationHandler"/>
    2. Add following handler under the <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler> property,

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

Update the <ScopeWhitelist> property in the <WSO2_OB_APIM_HOME>/repository/conf/api-manager.xml by adding <Scope>^TIME_.*</Scope>:

<ScopeWhitelist>
            <Scope>openid</Scope>
            <Scope>extended_transaction_history</Scope>
            <Scope>^OB_.*</Scope>
            <Scope>^x5t.*</Scope>
            <Scope>^TIME_.*</Scope>
</ScopeWhitelist>


Open Banking Key Manager configurations

identity.xml configurations

  1. IDTokenBuilder configuration:
    Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file. Update the value of the <OpenIDConnect> <IDTokenBuilder> as follows:

    <OpenIDConnect>
    	<IDTokenBuilder>com.wso2.finance.open.banking.idtoken.builder.MultikeyIDTokenBuilder</IDTokenBuilder>
    </OpenIDConnect>
  2. ID Token Signing Algorithm Configuration:

    Change the signing algorithm of the ID Token in the well-known configuration (id_token_signing_alg_values_supported). 

    Open the <WSO2_OBKM_HOME>/repository/conf/identity/identity.xml file. Update the value of the <OpenIDConnect> parameter under the <SignatureAlgorithm> element with the algorithm name. (For example SHA256withPS)

    <OpenIDConnect>
    	<SignatureAlgorithm>SHA256withPS</SignatureAlgorithm>
    </OpenIDConnect>
  3. IDTokenIssuerID configuration:

    Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file and update the <OpenIDConnect> <IDTokenIssuerID> element with the issuer in .well-known config.

    <OpenIDConnect>
    <IDTokenIssuerID><issuer in .well-known config></IDTokenIssuerID>
    </OpenIDConnect>
  4. SupportedGrantType configuration:

    <SupportedGrantTypes>
    	<SupportedGrantType>
    		<GrantTypeName>refresh_token</GrantTypeName>
    		<GrantTypeHandlerImplClass>com.wso2.finance.open.banking.identity.extensions.grant.type.handlers.OBRefreshGrantHandler</GrantTypeHandlerImplClass>
    	</SupportedGrantType>
    </SupportedGrantTypes>
  5. Organisation JWKS URL configuration:

    This step is not necessary if you are not integrating with an external trust anchor.

    In the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file, change the JWKS URL retrieved from the Open Banking directory. 

    <OAuth2JWKSPage><org JWKS URL></OAuth2JWKSPage>
  6. In the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file, set RenewTokenPerRequest to false. 

    When the RenewTokenPerRequest property is true, it enforces a new token per each request, which will revoke any active tokens for the same application and user. Set it to false to continue using the same token.

    <RenewTokenPerRequest>false</RenewTokenPerRequest>

well-known endpoint configuration

  1. Download and extract the well-known-config-resources.zip.
  2. Copy servlet-1.0-SNAPSHOT.jar in to <WSO2_OB_KM_HOME>/repository/components/lib directory.
  3. Copy openid-configuration.json file to <WSO2_OB_KM_HOME>/repository/conf/identity directory. Update the values in openid-configuration.json file according to your requirement.

    A sample openid-configuration.json is available here.

  4. Register the servlet in <WSO2_OB_KM_HOME>/repository/conf/tomcat/web.xml file. Add the following elements before the </webapp> tag.

    <servlet>
      <servlet-name>Discovery</servlet-name>
      <servlet-class>myPackage.Discovery</servlet-class>
    </servlet>
    <servlet-mapping>
      <servlet-name>Discovery</servlet-name>
      <url-pattern>/oidcdiscovery/.well-known/openid-configuration</url-pattern>
    </servlet-mapping>
  5. Restart the WSO2 OB KM server. Go to the following link and see the changes.

    https://<WSO2_OB_KM_HOST>:8243/.well-known/openid-configuration

Claim configurations

If you want the well-known configuration to reflect the claims_supported property with your claims, you should follow the steps below and configure the claims.

Claim configuration exposes the correct Open ID Connect (OIDC) claims and scopes. For more information on claim management, see Claim Management in the WSO2 Identity Server documentation.

  1. Log in to the Key Manager Management Console at https://<OBKM_HOST>/carbon.

  2. In the Main menu, click Claims > Add > Add Local Claim.
  3. Create the following local claims:

    Claim URLDisplay Name
    http://wso2.org/claims/open_banking_intent_idOpen Banking Intent ID
    http://wso2.org/claims/accountsAccounts
    http://wso2.org/claims/paymentsPayments

    The Mapped Attributes in the local claim configuration should be the Display Name in camel case, for example

    • Display Name - Open Banking Intent ID
    • Mapped Attribute - OpenBankingIntentID
  4. Click Claims > Add > Add External Claim to add an external OIDC claim. 

  5. Create the following external local claims.

    State the dialect URI as http://wso2.org/oidc/claim.

    External Claim URLMapped Local Claim
    http://wso2.org/claims/open_banking_intent_idopenbanking_intent_id
    http://wso2.org/claims/accountsaccounts
    http://wso2.org/claims/paymentspayments
  6. Click Home > Manage > OIDC Scopes > Add.

  7. Add the following OIDC scopes:

    Scope NameOIDC Claims
    accountsaccounts
    paymentspayments
  8. Update the <ScopeWhitelist> property in the <WSO2_OB_KM_HOME>/repository/conf/api-manager.xml by adding <Scope>^TIME_.*</Scope>:

    <ScopeWhitelist>
                <Scope>openid</Scope>
                <Scope>extended_transaction_history</Scope>
                <Scope>^OB_.*</Scope>
                <Scope>^x5t.*</Scope>
                <Scope>^TIME_.*</Scope>
    </ScopeWhitelist>

Configuring open-banking.xml

  1. Combine the signing certificate and key to pk12 format using the command below:

    openssl pkcs12 -export -in hcgexuguVb5rYSYVBsl-c9hBPvY.pem -inkey VgQOIBMehPnlLUQw0BFM5S_sig.key -name <production-key alias> -out CertAndKey.p12
  2. Import it to wso2carbon.jks of both Open Banking Key Manager (OBKM) and Open Banking API Manager (OBAM) in the following directories using the command given below:

    • <WSO2_OB_KM_HOME>/repository⁩/⁨resources⁩/security
    • <WSO2_OB_AM_HOME>/repository⁩/⁨resources⁩/security

      keytool -importkeystore -deststorepass wso2carbon -destkeystore wso2carbon.jks -srckeystore CertAndKey.p12 -srcstoretype PKCS12
  3. Follow the sample <OBIdentityRetriever> <Server> configs and define the alias and kid values in the following files:

    • <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml
    • <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml
    <OBIdentityRetriever>
        <Server>
            <SigningCertificateAlias><production-key alias></SigningCertificateAlias>
            <SandboxSigningCertificateAlias><sandbox-key alias></SandboxSigningCertificateAlias>
            <SigningCertificateKid><production kid></SigningCertificateKid>
            <SandboxCertificateKid><sandbox kid></SandboxCertificateKid>
        </Server>
    </OBIdentityRetriever>

Running the conformance suite

The test suite requires configuration in the form of a JSON document with two application details; resource and certificate files.

Configuring the applications

The test suite has to run in the perspective of two clients. Therefore, two applications are required. Follow the steps and create applications:

  1. Log in to the Open Banking API Manager Store (https://<WSO2_OB_APIM_HOME>9443/store).
  2. Create two applications under the same Third Party Provider (TPP). Use the following configurations:

    FieldValue
    Callback URLApplication 1https://<TEST_SUITE_HOST>:<TEST_SUITE_PORT>/test/a/<ALIAS>/callback

    Application 2https://<TEST_SUITE_HOST>:<TEST_SUITE_PORT>/test/a/<ALIAS>/callback?dummy1=lorem&dummy2=ipsum
    Application CertificateClient certificates (public key) that are signed by the root CA/Issuer CA (prior-acquired or generated). For example, tpp.com.crt.

    If you have integrated with OBIE, use the Dynamic Client Registration v3.2 API. If you're using Manual Client Registration, follow the given steps and create an application.

  3. Generate production keys.
  4. Take note of the generated consumer key and secret.

Configuring the test suite

This section describes how to build the test suite to identify the configuration and application settings of the solution.

  1. Get the Skeleton JSON configuration from Open Banking Developer Zone.

    A sample JSON configuration file is available here.

  2. In the Server section, fill the following values.

    KeyValue
    discoveryURLhttps://<WSO2_OB_APIM_GATEWAY_HOST>:<WSO2_OB_APIM_GATEWAY_PORT>/.well-known/openid-configuration
  3. Set the alias parameter as previously configured in the unique instance value.

  4. Configure the resource section, with the following parameters.

    KeyValue
    resourceUrl AccountsInfoAPI resource URL as shown in the API store
    institution_id <XFAPIFinancialId> specified in the open-banking.xml file (default value is open-bank)
  5. Configure the client and MTLS by following the steps below:

    Client and MTLS correspond to the first application, and client2 and mtls2 correspond to the second application.

    1. Fill in the client and client2 sections with the following parameters:

      KeyValue
      client_id The client ID for the application, as shown in the API Store.
      client_secret The client secret for the application, as shown in the API Store.
      scope OpenID accounts.
      jwks.keys The respective signing JWK set. This can be generated online using utility https://kaveenr.github.io/cert-utils
    2. Fill in the MTLS and MTLS2 sections with the following parameters:

      For live environments with the open banking transport certificates, the pre-filled CA should suffice.

      An online tool is available for converting the transport certificate files to the required line breaks to literal \n format. https://kaveenr.github.io/cert-utils/

      KeyValue
      keyContent of .key file of the transport certificate with line breaks replaced with literal \n
      certContent of .crt file of the transport certificate with line breaks replaced with literal \n
      caContent of rootCA .crt file of the transport certificate with line breaks replaced with literal \n

Starting the suite

Starting the suite locally

For more information on starting the suite locally, go to OpenID Foundation conformance-suite build and run.

  1. Clone the repo https://gitlab.com/openid/conformance-suite, using the command below and build the latest version. 

    If you encounter a permission denied error during cloning, use HTTP cloning instead of ssh.

    git clone https://gitlab.com/openid/conformance-suite.git
  2. Stop all the running docker containers and ensure a clean state. The following command shows the container status. 

    docker ps
  3. Execute the following commands to remove any local files.

    git clean -x -f -d 
    git reset --hard HEAD
  4. Run without installing JDK and Maven.

    MAVEN_CACHE=./m2 docker-compose -f builder-compose.yml run builder

    If you have a local Java development environment:

    mvn clean package
  5. Execute the following commands to build the docker image. 

    docker-compose build
  6. Start the docker container.

    docker-compose up
  7. The test suite is now available locally at  https://localhost:8443/

    When running both the solution and the test suite locally, make sure to use the host machine's IP for Docker.

    For an example: docker.for.mac.localhost


If you get these errors:

  • docker-compose: command not found error, execute the following commands.

    sudo curl -L "https://github.com/docker/compose/releases/download/1.22.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    
    sudo mv /usr/local/bin/docker-compose /usr/bin/docker-compose
    
    sudo chmod +x /usr/bin/docker-compose
  • ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running? If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.

    Execute the command with superuser privileges.

    sudo docker-compose up
Starting the suite online

If you're running WSO2 Open Banking in a local setup you are not able to use the online suite.

Go to https://www.certification.openid.net/ and start the conformance suite online.

Running the tests

  1. Copy the sample JSON configurations in https://gist.github.com/kaveenr/7e0e50b2cbd30f2fd7a592e0d992b86e to a text editor

    A sample JSON configuration file is available here.

    Update the values according to the application you created in the step above. For example: the clientID, clientSecret, API URI, discoveryUrl etc.

  2. Copy and paste the content of the private key (tpp.com.key) in https://kaveenr.github.io/cert-utils/.
  3. Copy the obtained JSON object. Update the value of the keys array element in the JSON configurations with the copied JSON object.
  4. Navigate and log in to the test suite.
  5. Select an appropriate Open Banking test plan.
  6. Copy the content in the modified JSON configuration file and paste the configuration into the JSON tab. 

  7. Click Start Test Plan.

  8. Run each given test in sequence.

  9. Follow the instructions and the suite will prompt if manual intervention is needed.

Troubleshooting

Use the suggested solutions below to solve these errors.

  • Error: The RSA JWK doesn't contain a private part
    Solution: Use https://kaveenr.github.io/cert-utils/ to create keys, or if JWKS URI is used, make sure the tls key is included in the URI.
  • Error: HazelcastSerializationException
    Solution: Disable the clustering deployment.
  • Error: {"error_description":"A valid OAuth client could not be found for client_id: qX1tXeIuYB5k4ixIVEtqiaL3DcY","error":"invalid_client"}
    Solution: Make sure you use the correct clientID in configurations.
  • Error: getBoolean called on something that is not boolean
    Solution: Update the string values in well-known endpoint by replacing them with boolean values. For example true not “true”.
  • Error: “The ExpirationDateTime value has to be a future date”
    Solution: Change the timezone of the machine  to UK timezone

References

  • No labels