Running the Security Conformance Suite for UK

Claim configurations

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://<WSO2_OB_KM_HOST>/carbon.

2. In the Main menu,  click Claims > Add > Add Local Claim.

3. Create the following local claims:

   Claim URL	Display Name
   http://wso2.org/claims/open_banking_intent_id	Open Banking Intent ID
   http://wso2.org/claims/accounts	Accounts
   http://wso2.org/claims/payments	Payments

   The Mapped Attributes in the local claim configuration should be the Display Name in the camel case.

   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 URL	Mapped Local Claim
   http://wso2.org/claims/open_banking_intent_id	openbanking_intent_id
   http://wso2.org/claims/accounts	accounts
   http://wso2.org/claims/payments	payments

6. Click Home > Manage > OIDC Scopes > Add.

7. Add the following OIDC scopes:

   Scope Name	OIDC Claims
   accounts	accounts
   payments	payments

open-banking.xml configurations

1. To run the Security Conformance Suite, you need  2 different signing/transport certificates and corresponding SSAs.

   • Combine the signing certificate and key to pk12 format using the command below. Repeat this step for both the certificate sets. 

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

2. Create a new keystore file: 

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

3. Import the  p12  files to the new keystore. Repeat this step for both the  p12  files. 

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

4.  Duplicate and place the new keystore in the following locations:
   • <WSO2_OB_KM_HOME>/repository⁩/⁨resources⁩/security

   • <WSO2_OB_APIM_HOME>/repository⁩/⁨resources⁩/security

5. Add the new keystores to the client-truststores. 
   1. Go to the <WSO2_OB_IAM_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. 
6. Configure the new keystore file.

   1. Open the <WSO2_OB_KM_HOME>/repository/conf/carbon.xml file and configure the new keystore file as follows: 

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

   2. Open the <WSO2_OB_APIM_HOME> /repository/conf/carbon.xml  file and configure the new keystore by following the step above.

7. Define the  alias  and  kid  values for the primary signing certificates 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> 
   		<SigningCertificateKid><production kid></SigningCertificateKid> 
   	</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 Adaptive Authentication script

1. Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/common.auth.script.js file.

2. Remove the existing content and add the following:  

   var psuChannel = 'Online Banking';
   
   function onLoginRequest(context) {
       reportingData(context, "AuthenticationAttempted", false, psuChannel);
   
       executeStep(1, {
           onSuccess: function (context) {
               var supportedAcrValues = ['urn:openbanking:psd2:sca', 'urn:openbanking:psd2:ca'];
               var selectedAcr = selectAcrFrom(context, supportedAcrValues);
   		    context.selectedAcr = selectedAcr;
           },
           onFail: function (context) { //basic auth fail
               //retry
           }
       });
   }
   
   

3. Restart the API Manager server.

Configuring the applications

The test suite has to run from 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:

   Field	Value
   Callback URL	Application 1	https://<TEST_SUITE_HOST>:<TEST_SUITE_PORT>/test/a/<ALIAS>/callback
   	Application 2	https://<TEST_SUITE_HOST>:<TEST_SUITE_PORT>/test/a/<ALIAS>/callback?dummy1=lorem&dummy2=ipsum For Application 2, avoid using regular expressions in the Callback URL.
   Application Certificate	Client 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.

   • The kid value should be the specific kid value of the corresponding signing certificate in the JWKS.

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

   Key	Value
   discoveryURL	https://<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.

   Key	Value
   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:

      Key	Value
      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 this tool.

   2. Fill in the MTLS and MTLS2 sections with the following parameters:

      For live environments with 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. Click here to try out the tool

      Key	Value
      key	Content of .key file of the transport certificate with line breaks replaced with literal \n
      cert	Content of .crt file of the transport certificate with line breaks replaced with literal \n
      ca	Content of rootCA .crt file of the transport certificate with line breaks replaced with literal \n

Starting the suite

Starting the suite locally

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. If you are using a Linux environment:

   • Add the hostname mapping using the  extra_hosts: tag to the docker-compose.yml file in conformance-suite. Replace the given placeholders with the hostname and the IP address of the Docker bridge.

   httpd:
     build:
       context: ./httpd
     ports:
      - "8443:8443"
     extra_hosts:
      - "<DOCKERBRIDGE_HOST>:<DOCKERBRIDGE_IP>"
     depends_on:
      - server

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

6. Execute the following commands to build the docker image. 

   docker-compose build

7. Start the docker container.

   docker-compose up

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

Starting the suite online

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

Running the tests

1. Copy the sample JSON configurations  here to a text editor. 

   A sample JSON 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 and a client authentication type.
   

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

• https://openid.net/certification/instructions/