JWS Response Signing

The WSO2 Open Banking Accelerator provides the JWS Response Signing executor if you want to sign the API responses sent from the bank. Signing ensures the API consumers that the received responses are not tampered. Furthermore, using the JWS Response Signing executor, you can handle different content types, retrieve public signing keys, and generate a detached JWS with the generated JWS header and JWS signature.

You can implement this executor to perform the following:

  • Configure the signing algorithm
  • Retrieve critical claims
  • Retrieve HTTP header name
  • Handle errors for responses that require signing

You can implement a custom JWS Response Signing executor by extending the following class:

com.wso2.openbanking.accelerator.gateway.executor.jws.JwsResponseSignatureHandlingExecutor

Given below is a brief explanation of the methods you need to implement.

getSignatureHeaderName method

This method lets you retrieve the header name of the HTTP header that contains the JWS Signature. 

/**
* Method to identify the HTTP Header name of the JWS sent.
*/
public String getSignatureHeaderName() {
   return "x-jws-signature";
}

The returned value is assigned to a private variable named SIGNATURE_HEADER_NAME, which is useful in setting response headers.

getCriticalHeaderParamters method

This method lets you retrieve the critical claims with their values in the form of a hash map.

/**
* HashMap to be returned with crit header keys and values.
* can be extended at toolkit level.
*
* @return HashMap crit header parameters
*/
public HashMap<String, Object> getCriticalHeaderParameters() {

   return new HashMap<>();
}

getSigningAlgorithm method

This method lets you retrieve the algorithm that is used to sign the response. 

/**
* JWSAlgorithm to be returned in the JWS header when signing.
* can be extended at toolkit level.
*
* @return JWSAlgorithm the signing algorithm defined to use in configs
*/
public JWSAlgorithm getSigningAlgorithm()  {

   String alg = OpenBankingConfigParser.getInstance().getMessageSigningAlgorithm();
   return JWSAlgorithm.parse(alg);
}

isApplicable method

This method lets you identify the responses that need to be signed. This method returns the configuration to enable or disable message signing.

This behaviour can be changed by overriding the method in an extended class.

/**
* Provide the child classes to decide whether the signature generation is required.
*
* @param obapiResponseContext OB response Object
* @return boolean returns if request needs to be signed
*/
public boolean isApplicable(OBAPIResponseContext obapiResponseContext) {

   return OpenBankingConfigParser.getInstance().isMessageSigningEnabled();
}

Once implemented, build a JAR file for the project.

Configuring a custom JWS Response Signing Executor

  1. Place the above-created JAR file in the <APIM_HOME>/repository/components/lib directory.
  2. Open the <APIM_HOME>/repository/conf/deployment.toml file.

  3. Add the Fully Qualified Name (FQN) of the created executor under the open_banking.gateway.openbanking_gateway_executors.type.executors tag with a priority of 999. For example:

    [[open_banking.gateway.openbanking_gateway_executors.type.executors]]
name = "com.wso2.openbanking.accelerator.gateway.executors.jws.JwsResponseSignatureHandlingExecutor "
priority = 999

  4. Enable signing and define the signing algorithms for the JWS response header:

    [open_banking.signing]
enable = true
allowed_algorithm="PS256"

  5. Add the following tags to define the alias and the kid value of the signing certificate. The unique kid value is used to identify the corresponding public key for the validation at the API consumer's side.

    [open_banking.ob_identity_retriever.server]
signing_cert_alias="wso2carbon"
sandbox_signing_cert_alias= "wso2carbon"
signing_cert_kid="1234"
sandbox_signing_cert_kid= “5678”

  6. Configure the JWKS size limit and timeout and values by adding the following: 

    [open_banking.ob_identity_retriever.jwks_retriever]
size_limit=51200
connection_timeout=2000
read_timeout=2000

  7. Save the above configurations and restart the API Manager server.

Top