How to use mutual TLS

Rabobank protects its APIs with an extra layer of security. Clients or apps that want to interact with our mutual TLS enabled APIs should have an X-509 certificate. The traffic is encrypted over TLS.

To interact with mutual TLS protected APIs, you should follow the below listed steps:

  1. Get an X.509 certificate.
  2. Register the certificate on the Rabobank Developer Portal.
  3. Configure your client software to use the certificate during the TLS handshake.

Step 1: Get an X-509 certificate

For PSD2 APIs, you are required to use a Qualified Certificate for Website Authentication (QWAC certificate, issued by a qualified trust service provider of your choice).

For the sandbox environment you can use the example certificate, see: Signing requests for PSD2 APIs.

Step 2: Register the certificate on the Rabobank Developer Portal

Info: Register your app before registering the TLS certificate. You can only register one TLS certificate per app.

To register the certificate:

  1. Log into the Rabobank developer portal.
  2. Click My Apps.
  3. Select the app that should make the TLS protected requests.
  4. Click Edit.
  5. Click the TLS Certificate field and upload your TLS client certificate. This certificate must be in PEM format. For more information, see RFC7468.
  6. Click Submit.

Step 3: Configure your client software to use the certificate during the TLS handshake

Note: This step assumes you have already subscribed your app to the product containing the API that requires an X-509 client certificate.

Before your application can call the API, you should configure your software to use the private key and certificate.

Make sure to add the following CA's used by Rabobank to your trust store before making the connection:

  • digicert
  • quovadis
  • sectigo

Set up MTLS connection

To set up an MTLS connection you are required to send your client certificate including the certificate chain, this is a sequence (chain) of certificates in the X.509v3 PEM or DER format.

The client certificate must be first in the certificate sequence. Each following certificate should directly certify the one preceding it. This is because certificate validation requires that root keys to be distributed independently.

The self-signed certificate specifying the root certificate authority is optional and may be omitted from the chain.

Source: RFC 5246 7.4.2 - https://www.ietf.org/rfc/rfc5246.txt

See TLS error codes for expected error responses.

You can test the configuration as shown in the example below: 

curl 'RABOBANK_ENDPOINT_URL' \
--header 'x-ibm-client-id: CLIENT_ID'
--key PATH_TO_KEY_FILE
--cert PATH_TO_CERT_FILE 
FieldDescription
RABOBANK_ENDPOINT_URLThe endpoint of the API you want to call.
CLIENT_IDThe client ID of your application.
PATH_TO_KEY_FILEPath to the key file on your system that belongs to your certificate.
PATH_TO_CERT_FILEPath of your client certificate on your system.

Replace TLS certificate

You can replace your TLS certificate using the following steps:

  1. Navigate to the Rabobank developer portal → Sign in to your account → My Apps. 
  2. Select the application for which you want to replace the TLS certificate.
  3. Click Edit and upload your TLS certificate in PEM format.

    Rabobank only supports one TLS certificate, any existing certificate should be removed. It is not possible to upload two TLS certificates at the moment.

  4. Click Save.

SNI

Server Name Indication (SNI) is an extension for the TLS protocol to indicate a hostname in the TLS handshake (source wiki).

Transport Layer Security Server Name Indication (TLS SNI) allows clients to include the name of the host they are trying to contact (the "server name") in a request, which allows the server to select and respond with a proper certificate.

To make the TLS connection with the provided hosts secure, all existing (migrating) and/or new customer(s) are required to enable SNI in their client software before interacting with the following Rabobank hostnames:

Sandbox:

  • api-sandbox.rabobank.nl

Production

  • api.rabobank.nl

Note: A TPP not using SNI is most likely to get connection related error messages, for example, 500 internal server error.