Validate signed responses

In order to guarantee the integrity of API responses, Rabobank digitally signs all responses of the Rabo Identity Services APIs. You can also use this feature to determine the integrity and authenticity of the response.

This functionality relies on JWS (JSON Web Signatures - RFC7515) for computing and signing the response payloads and JWK (JSON Web Keys - RFC7517) for the publication of the key material required to validate the integrity and authenticity of the signed content. Unlike standard JWS tokens, which contain a payload, API responses use detached content(see RFC7515#appendix-F), where the JWS does not include the payload (response body) directly.

This method requires the recipient to reconstruct the exact payload used in the JWS.  

To use the modified object, the recipient reconstructs the JWS by re-inserting the payload representation into the modified object and uses the resulting JWS in the usual manner.

This method does not require support from JWS libraries, as applications can use this method by modifying the inputs and outputs of standard JWS libraries.

 Follow the listed steps to validate the integrity and authenticity of your signed response payload:

Obtain the JSON Web Key

All Rabo Identity Services API(s) facilitate an endpoint exposing the JSON Web Key, which is used to validate the signature on the response.

Retrieve the JWK by invoking the GET/keys endpoint on your subscribed API. The received response should contain the public part of the cryptographic key structured as JWK. The corresponding private key is used by the platform to compute the signature for the API response content.

{
"keys": [
{
"kty": "RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e": "AQAB",
"alg": "RS256",
"kid": "12345"
}
]
}

For efficiency and performance improvements, the retrieved JWK can be cached locally and reused for further API response signature validation. A new key can be retrieved when e.g. the key id (kid) on a signature doesn't match the received key id (kid) in the JWK or based on a refresh schedule The key id (kid) attribute that is delivered as part of the key specification is linked to the response signature and should match the key id specified on the JWS token received as part of the API response.

Retrieve the JWS Signature from the Response Header

The API response includes the X-JWS-Signature header containing a JWS in the compact serialization format with detached content.The signature is computed based on the corresponding payload of the response. 

The header of the X-JWS-Signature value contains a Key ID, referred to as kid. This value should match the kid value in the public part of the JSON Web Key.

The signed JWT itself contains a header and signature part but with an empty payload, this payload should be populated before validating the signature.

X-JWS-Signature=<jose-header>..<signature>

Compute and Encode the Missing Payload

Extract the response body and encode it using Base64Url encoding:

jws_payload = BASE64URL(response_body)
  • Use Base64Url encoding, which differs slightly from standard Base64 encoding.
  • Make sure you don't transform or alter the response body before encoding step as it results in a different encoded value that does not match the received signature

Reconstruct the Full JWS

Combine the received X-JWS-Signature header and the computed payload to reconstruct a full JWS token:

jws_compact = <jose-header>.<jws_payload>.<signature>

This effectively transforms the detached JWS into a normal JWS structure that can be validated in the usual manner.

Validate the JWS Signature

Use the retrieved JWK to validate the reconstructed JWS token. The validation process typically involves:

  • Parsing the JWS compact string.
  • Extracting the header, payload, and signature.
  • Verifying the signature using the retrieved public key.

Below is a generic example of how validation can be implemented:

function validate_jws(response_body, x_jws_signature, jwk):
# Step 1: Compute Base64Url encoded payload
jws_payload = base64url_encode(response_body)

# Step 2: Reconstruct the JWS
jose_header, signature = x_jws_signature.split("..")
jws_compact = jose_header + "." + jws_payload + "." + signature

# Step 3: Retrieve the public key from JWK
public_key = load_jwk(jwk)

# Step 4: Verify the JWS using any appropriate tool/library for your platform
is_valid = verify_jws(jws_compact, public_key)

return is_valid

..