Running the Functional Conformance Suite

An Open Banking Implementation Entity ( OBIE) Functional Conformance Certificate allows an implementer to demonstrate that they have 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. Do the following changes in WSO2 Open Banking Key Manager(WSO2_OB_KM).

   1. Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file. Set the RenewTokenPerRequest property to false.

      The RenewTokenPerRequest configuration provides the ability to renew the access token and refresh token per each token request. It also revokes the previously available active token for a matching clientId, user and scopes combination. 

      <RenewTokenPerRequest>false</RenewTokenPerRequest>

   2. Open the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file. Update the <WSO2_OB_APIM_HOST> placeholder with the hostname of the API Manager server. 

      The IDTokenIssuerID property sets the IssuerID of the IDToken

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

   3. Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and set the MaximumFuturePaymentDays value to 365 days.

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

2. Configure the certificates.
   

   Go to <WSO2_OB_APIM_HOME>/repository/resources/security/  directory and execute the following commands.

   1. Create a new alias for wso2carbon.jks.

      keytool -genkey -alias <WSO2_OB_APIM_HOST> -keyalg RSA -keysize 2048 -validity 3950 -keystore wso2carbon.jks

   2. Create a certificate using the alias created in the step above and import it to the client-truststore.

      keytool -export -alias <WSO2_OB_APIM_HOST> -file <WSO2_OB_APIM_HOST>.crt -keystore wso2carbon.jks

   3. Import the certificate to the client-truststore.

      keytool -import -trustcacerts -alias <WSO2_OB_APIM_HOST> -file <WSO2_OB_APIM_HOST>.crt -keystore client-truststore.jks 

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 Key Manager and API Manager servers.

2. Deploy Account API v3.1.0 and Payment API v3.1.0.

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

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

4. Create an application.

5. Subscribe to the APIs deployed in step 4.

6. Create the public certificate of the signing certificate and generate keys.

Setting up the test suite

1. Execute 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. Add the certificates to the container.
   

   1. Go to <WSO2_OB_APIM_HOME>/repository/resources/security and execute the command below to generate the pem file for <WSO2_OB_APIM_HOST>.crt

      openssl x509 -inform der -in <WSO2_OB_APIM_HOST>.crt -out <WSO2_OB_APIM_HOST>.pem

   2. Log in to the container

      docker exec -it fsuite /bin/bash

   3. Add the <WSO2_OB_APIM_HOST>.pem certificate to the following locations:

      - /usr/local/share/ca-certificates/<WSO2_OB_APIM_HOST>.pem
- /etc/ssl/certs/<WSO2_OB_APIM_HOST>.pem

   4. Run the following command.

      update-ca-certificates

   5. Stop the container.

      docker stop fsuite

   6. Restart the container

      docker start -a fsuite

3. Access the test suite at https://<WSO2_OB_APIM_HOST>:8443
4. Select Open Banking test suite and start the test.
   

5. In the Discovery step, update the following values in the JSON file. 

   A sample configure.json is available here.

   

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

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

6. Click Next and proceed to the Configuration stage.

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

   
   

   A sample 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.
   x-fapi-financial-id	The unique id of the ASPSP to which the request is issued. The unique id will be issued by OB. For example: open-bank

   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.

   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)

8. Click Next and run the suite.