Running the Functional Conformance Suite for UK

The  Open Banking Implementation Entity ( OBIE) Functional Conformance Certificate allows WSO2 Open Banking to demonstrate that the solution has successfully implemented all required functional elements of the OBIE Read/Write API specifications, passing all tests performed by the Functional Conformance Tool.

This document contains the following topics:

Configuring the solution 

1. Set the RenewTokenPerRequest property to false in <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml as follows:

   <RenewTokenPerRequest>false</RenewTokenPerRequest>

2. In <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml, update the <WSO2_OB_APIM_HOST> placeholder with the hostname of the API Manager server for IDTokenIsuuerID:

   <IDTokenIssuerID>https://<WSO2_OB_APIM_HOST>:8243/token</IDTokenIssuerID>

3. Change the MaximumFuturePaymentDays value to 365 in <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml as follows:

   <PaymentRestrictions>
   	<MaximumFuturePaymentDays>365</MaximumFuturePaymentDays>
   </PaymentRestrictions>

4. Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml and <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml files and set the following configuration to false:

   <ValidateAccountIdOnRetrieval>true</ValidateAccountIdOnRetrieval>

5. The Functional conformance suite invokes the endpoints exposed by the host machine. Therefore, you need to add a hostname to the  Docker-bridge interface.  Thereby, both WSO2 Open Banking Identity and Access Management (WSO2_OB_KM_HOST) and WSO2 Open Banking API Management (WSO2_OB_APIM_HOST) servers can be accessed via the server hostnames and Docker-bridge hostname (DOCKER_SEVER_HOST).

   1. Create a new server key and a certificate including the following parameters:

      1. server hostname as Common Name (CN).

      2. DOCKER-BRIDGE_SEVER_HOST as Subject Alternative Name (SAN).  See the sample given below:

         [req]
         distinguished_name = req_distinguished_name
         x509_extensions = v3_req
         prompt = no
         [req_distinguished_name]
         C = US
         ST = VA
         L = SomeCity
         O = MyCompany
         OU = MyDivision
         CN = <WSO2_OB_APIM_HOST>
         [v3_req]
         keyUsage = keyEncipherment, dataEncipherment, digitalSignature
         extendedKeyUsage = serverAuth, clientAuth
         subjectAltName = @alt_names
         [alt_names]
         DNS.1 = <DOCKER-BRIDGE_SEVER_HOST>

         openssl req -x509 -nodes -days 3560 -newkey rsa:4096 -keyout wso2carbon.key -out wso2carbon.crt -config req.conf -extensions 'v3_req'

   2. Create a new keystore with the generated certificate. Please use the same keystore password (KEYSTORE_PASSWORD) that you have already configured for the existing keystore:

      openssl pkcs12 -export -in wso2carbon.crt -inkey wso2carbon.key -name <KEYSTORE_PASSWORD> -out <WSO2_OB_APIM_HOST>.p12

   3. Import the generated server certificate (step a) to client truststore of both WSO2_OB_KM_HOST and WSO2_OB_APIM_HOST servers:

       keytool -importcert -file wso2carbon.crt -keystore client-truststore.jks -alias "<WSO2_OB_APIM_HOST>"

Configuring JWS validation

1. Open the open-banking.xml files and do the following configurations:
   • <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml
   • <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml

2. Configure <SigningConfiguration> under the <UK> tag as follows: 

   <UK>
   	<SigningConfiguration>
   		<!-- Enable Signing -->
   		<Enable>true</Enable>
   		<OBIE>
   			<!--
               Trusted Anchor Configuration
               openbanking.org.uk specific Trust Anchor definitions
               -->
   			<TrustedAnchors>
   				<!-- Trust Anchor used in signing JOSE -->
   				<Signing>openbanking.org.uk</Signing>
   				<!--
                   Multiple values supported with `|` delimiter
                   IE - trustanchor.org|trustanchor.org.uk
                   -->
   				<Validation>openbanking.org.uk</Validation>
   			</TrustedAnchors>
   			<!-- OBIE Organization Id -->
   			<OrganizationId>{org_id in the SSA or Organizational Unit of the certificate Owner}</OrganizationId>
   		</OBIE>
   		<!-- Default Singing Algorithm is PS256, to support others uncomment line below -->
   		<!--<Algorithm>RS256</Algorithm>-->
   		<!-- The following specified APIs will be mandated for message signing. -->
   		<MandatedAPIs>
   			<APIContext>/open-banking/v3.0/event-notification/</APIContext>
   			<APIContext>/open-banking/v3.0/pisp/</APIContext>
   			<APIContext>/open-banking/v3.1/event-notification/</APIContext>
   			<APIContext>/open-banking/v3.1/pisp/</APIContext>
   		</MandatedAPIs>
   	</SigningConfiguration>
   

3. Add the following configurations under the <SigningConfiguration> tag: 

   <!-- The following specified APIs will be associated with response signing. -->
   <ResponseSignatureRequiredAPIs>
   	<APIContext>/open-banking/v3.0/pisp/</APIContext>
   	<APIContext>/open-banking/v3.1/pisp/</APIContext>
   </ResponseSignatureRequiredAPIs>

4. Find the following tags and define the alias and kid values for the primary signing certificates:

   <OBIdentityRetriever>
       <Server>
           <SigningCertificateAlias><production-key alias></SigningCertificateAlias>
           <SigningCertificateKid><production kid></SigningCertificateKid>
       </Server>
   </OBIdentityRetriever>

5. Follow the API Security - JSON Web Signature (JWS) documentation and configure JWS validation support for Waiver 007.

6. Combine the signing certificate and key to a pk12 format file using the command below: 

   openssl pkcs12 -export -in <pem file> -inkey <key file> -name <alias> -out CertAndKey.p12

7. Create a new keystore file: 

   keytool -genkey -alias <keystore alias> -keyalg RSA -keystore <keystore name>.jks -keysize 2048

8. Import the p12 files to the new keystore. 

   keytool -importkeystore -deststorepass <keystore password> -destkeystore <keystore name>.jks -srckeystore CertAndKey.p12 -srcstoretype PKCS12

9. Add the new keystore to the client-truststore.
   1. Go to the <WSO2_OB_KM_HOME>/repository⁩/⁨resources⁩/security directory.

   2. Export the public certificate of the keystore to a .pem file. 

      keytool -export -alias <alias> -keystore <keystore_name>.jks -file <keystore_name>.pem

   3. Import the .pem file to client-truststore.jks. 

      keytool -import -alias <alias> -file <keystore name>.pem -keystore client-truststore.jks -storepass wso2carbon

   4. Go to the <WSO2_OB_APIM_HOME>/repository⁩/⁨resources⁩/security directory and repeat the above steps. 
10. Duplicate and place the new keystore in the following locations:
    
    • <WSO2_OB_KM_HOME>/repository⁩/⁨resources⁩/security
    • <WSO2_OB_APIM_HOME>/repository⁩/⁨resources⁩/security
11. Configure the new keystore file in carbon.xml files:
    
    • <WSO2_OB_KM_HOME>/repository/conf/carbon.xml
    • <WSO2_OB_APIM_HOME>/repository/conf/carbon.xml 

      
      

      <KeyStore>
          <!-- Keystore file location-->
          <Location><<WSO2_OB_KM_HOME>/repository⁩/⁨resources⁩/security/<new_keystore.jks></Location>
          <!-- Keystore type (JKS/PKCS12 etc.)-->
          <Type>JKS</Type>
          <!-- Keystore password-->
          <Password><new keystore password></Password>
          <!-- Private Key alias-->
          <KeyAlias><new private key alias></KeyAlias>
          <!-- Private Key password-->
          <KeyPassword><new private key password></KeyPassword>
      </KeyStore>
      

12. Organization JWKS URL configuration:
    
    1. Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file.

    2. Update <OAuth2JWKSPage> with the JWKS URL retrieved from the Open Banking directory: 

       <OAuth2JWKSPage><org_jwks_endpoint in the SSA></OAuth2JWKSPage>
       

Running the solution

1. Start WSO2 Open Banking API Manager and WSO2 Identity Access Management servers.

2. Deploy Account and Transaction API v3.1.2, Payment Initiation API v3.1.2, and Confirmation of Funds API v3.1.1.

   If you’re using the Dynamic Client Registration v3.2 API, skip to Setting up the test suite.

3. Sign in to the API Developer Portal as a TPP at https://<WSO2_OB_APIM_HOST>:9443/store.

4. Change the redirect URL of the application to “https://< DOCKER-BRIDGE_SEVER_HOST>:8443/conformancesuite/callback”.

Setting up the test suite

1. Run the following command in a terminal to pull and run the image:

   docker run --add-host=<DOCKER-BRIDGE_SEVER_HOST>:<docker0 ip> -it --name=fsuite -p 8443:8443 -e LOG_LEVEL=debug -e LOG_TRACER=true -e LOG_HTTP_TRACE=true -e DISABLE_JWS=FALSE "openbanking/conformance-suite:[TEST_SUITE_VERSION]"

2. To add the certificates to the container, go to < WSO2_OB_APIM_HOME>/repository/resources/security and execute the below command to generate the pem file for <WSO2_OB_APIM_HOST>.crt:

   openssl x509 -inform DER -in wso2carbon.crt -out <WSO2_OB_APIM_HOST>.pem -outform PEM

3. Log in to the container:

   docker exec -it fsuite /bin/bash

4. Add the <WSO2_OB_APIM_HOST>.pem certificate to the following locations using the below command:

   1. /usr/local/share/ca-certificates/<WSO2_OB_APIM_HOST>.pem

      docker cp <WSO2_OB_APIM_HOST>.pem fsuite:/usr/local/share/ca-certificates/<WSO2_OB_APIM_HOST>.pem

   2. etc/ssl/certs/<WSO2_OB_APIM_HOST>.pem

      docker cp <WSO2_OB_APIM_HOST>.pem fsuite:/etc/ssl/certs/<WSO2_OB_APIM_HOST>.pem

5. Copy  wso2carbon.jks to the same locations as in step 4.

6. Run the following command:

   update-ca-certificates

7. Stop the container using the following command:

   docker stop fsuite

8. Restart the container:

   docker start -a fsuite

9. Access the test suite at https://localhost:8443 .

10. Select Open Banking test suite and start the test.

    

11. In the Discovery step, update the following values in the JSON file separately for each time the conformance suite runs for Account and Transaction API, Payment Initiation API, and Confirmation of Funds API.

    1. Account and Transaction API:

       A sample endpoint configuration for the Account and Transaction API is available here.

       discoveryItems
       apiSpecification name	Account and Transaction API Specification
       openidConfigurationUri	The OpenID Connect discovery endpoint. For example: https://<DOCKER_SEVER_HOST>:8243/.well-known/openid-configuration
       resourceBaseUri	Production/Sandbox URL for the API. For example: https://<DOCKER_SEVER_HOST>:8243/open-banking/v3.1/aisp

    2. Payment Initiation API:

       A sample endpoint configuration for the Payment Initiation API is available here.

       discoveryItems
       apiSpecification name	Payment Initiation API
       openidConfigurationUri	The OpenID Connect discovery endpoint. For example: https://<DOCKER_SEVER_HOST>:8243/.well-known/openid-configuration
       resourceBaseUri	Production/Sandbox URL for the API. For example: https://<DOCKER_SEVER_HOST>:8243/open-banking/v3.1/pisp

    3. Confirmation of Funds API:

       A sample endpoint configuration for the Confirmation of Funds API is available here.

       discoveryItems
       apiSpecification name	Confirmation of Funds API
       openidConfigurationUri	The OpenID Connect discovery endpoint. For example: https://<DOCKER_SEVER_HOST>:8243/.well-known/openid-configuration
       resourceBaseUri	Production/Sandbox URL for the API. For example: https://<DOCKER_SEVER_HOST>:8243/open-banking/v3.1/cbpii

12. Click Next and proceed to the Configuration stage.

13. Add the following mandatory configurations in the form/JSON file.

    A sample TestData_Configure.json is available here.

    Client
    Private Signing Key (.key):	The Private Signing Key certificate of the client/application created in the section above .
    Public Signing Certificate (.pem):	The Public Signing Certificate of the client/application created in the section above.
    Private Transport Key (.key):	The Private Transport Key certificate of the client/application created in the section above.
    Public Transport Certificate (.pem):	The Public Transport Certificate of the client/application created in the section above.
    Account IDs	The Account IDs of the account resources that the customer (PSU) has consented to provide to the client/application.
    Statement IDs	The Statement IDs of the statement resources that the customer (PSU) has consented to provide to the client/application.
    Client ID	Consumer key of the client/application created in the section above.
    Client Secret	Consumer secret of the client/application created in the section above.
    tpp_signature_kid	The KID value of the signing certificate.
    tpp_signature_issuer	Certificate Owner (Eg: CN=sgsMuc8ACBgBzinpr8oJ8B, OU=0015800001HQQrZAAX, O=OpenBanking, C=GB)
    tpp_signature_tan	Trust Anchor used in signing JOSE (Eg: openbanking.org.uk)

    Well-Known
    OAuth 2.0 response_type	A JSON array containing a list of the OAuth 2.0 response_type values that this OP supports. Dynamic OpenID Providers MUST support the code, id_token, and the token id_token Response Type values
    Request object signing algorithm	The algorithm used to sign requests objects
    Resource Base URL	The base URL of the WSO2 OB APIM server. For example: https://<WSO2_OB_APIM_HOST>:8243

    Payments
    Identification	Beneficiary account identification
    Name	Name of the account, as assigned by the account servicing institution. Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account.
    International Identification	The international beneficiary account identification
    International Name	International name of the account, as assigned by the account servicing institution. Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account.

    Confirmation of Funds
    Schema Name	Name of the identification scheme.
    Identification	Account identification, which is known by the account owner.
    Name	The name of the account, as assigned by the account servicing institution. Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account.

14. Click Next and run the suite.