Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
Showing results for 
Search instead for 
Did you mean: 
Product and Topic Expert
Product and Topic Expert
In order to use mTLS to protect your application, you can directly leverage the capabilities of Cloud Foundry in combination with the SAP BTP Custom Domain service to implement mTLS.

In order to use mTLS to secure the connection between your application and the SAP Authorization and Trust Management service (XSUAA) to get the access token in the client credentials flow, XSUAA provides the related support.

Alternatively, you can use the SAP Application Router to do the mTLS handshake with your backend application and get an access token from XSUAA in the mTLS way.


The structure of the following content:

  • Enable mTLS Directly with Cloud Foundry and Custom Domain to Protect Your Application

    • Client Authentication Flow

    • Sample

    • TLS Configurations in SAP BTP Custom Domain Service (Custom Domain Manager)

  • Enable mTLS to Secure the Connection between Your Application and XSUAA

  • Enable mTLS with SAP Application Router and XSUAA to Protect Your Application


Enable mTLS Directly with Cloud Foundry and Custom Domain to Protect Your Application

Client Authentication Flow

In the Cloud Foundry architecture, Client Authentication (part of mTLS) is implemented as follows:

  • Certificate Validation:

    When an external client or end user accesses an application deployed in Cloud Foundry, the request will be resolved to the IPs of the central load balancer of the landscape setup. Then, the load balancer sends the request to HAProxy, which is used to connect the landscape specific load balancer to the Cloud Foundry Gorouter, and handle SSL termination as well as blocking of embargoed countries. Your application runs in a container at a lower level, the Gorouter finally routes incoming traffic to the hosted application running on a Diego Cell. So, the basic traffic is: End user -> Load Balancer -> HAProxy -> Gorouter -> Application.

    During the phase of client authentication, a client certificate as well as the corresponding private key can be included in a request when accessing an application in a certain domain (configured by SAP BTP Custom Domain service and synchronized to HAProxy). The request is being routed through the HAProxy and where mTLS termination happens upfront. After client and server certificate have been mutually validated, the request is then being routed to your application via HTTPS.

    If this client certificate has been signed by a CA which is known by HAProxy, it is forwarded to the application in the http-header X-Forwarded-Client-Cert, as well as a set of mTLS-specific headers with a X-SSL-Client- prefix (see below). In case of the request not containing a client certificate, the X-Forwarded-Client-Cert header won't be set. If the X-Forwarded-Client-Cert header is manually set by a client, HAProxy overwrites the header by a valid certificate received by HAProxy in the mTLS handshake, if the forwarded_client_cert property is set to sanitize_set. Otherwise, if the HAProxy doesn't know the root CA that sign your client certificate, you can add the root CA in your trust list via the SAP BTP Custom Domain service.

  • Certificate Identity Verification:

    When the request reaches your application, at this point there is no longer a certificate on TLS level (mTLS to be precise). The SSL connection is terminated on the HAProxy. 

    The latter api is then handed specific headers about the certificate (such as the x-ssl-client-verify header) by the HAProxy that have to checked by the did management api to make sure validation was successfull. A filter about the request's origin is applied on top to determine the sending party.

    So your application (e.g. Spring) just receives the information about the X.509 / mTLS certificate in the header added to the request. Therefore it does not make sense to add / configure x509 support to the Spring application, as no real mTLS will ever reach the endpoint. Rather you need to get your application to read out the header and do your logic based on it, for example: check if the CN is whitelisted and sends the appropriate response.

See for more details Cloud Foundry security, Cloud Foundry routing architecture and Manage TLS Configurations.

Headers Forwarded in mTLS Requests

Name Meaning Set On
X-Forwarded-Client-Cert Base64-encoded binary version of the client certificate mTLS connections or if forwarded_client_cert setting allows it (see below)
X-SSL-Client-Session-ID The SSL session ID of the client connection. Useful for debugging purposes. mTLS connections
X-SSL-Client-Verify 0 if the client certificate verification was successful. Otherwise it contains the appropriate OpenSSL return code mTLS connections
X-SSL-Client-Subject-DN Subject distinguished name of the client certificate mTLS connections
X-SSL-Client-Subject-CN Subject common name of the client certificate mTLS connections
X-SSL-Client-Issuer-DN Issuer distinguished name of the client certificate mTLS connections
X-SSL-Client-NotBefore Start date of the client certificate in YYMMDDhhmmss[Z] format mTLS connections
X-SSL-Client-NotAfter Expiration date of the client certificate in YYMMDDhhmmss[Z] format mTLS connections

Options for forwarded_client_cert

Name Meaning
always_forward_only Always forward the XFCC header in the request, regardless of whether the client connection is mTLS
forward_only Forward the XFCC header received from the client only when the client connection is mTLS
sanitize_set Strip any instances of XFCC headers from the client request. Then forward the XFCC header if the connection is mTLS
forward_only_if_route_service Behaves like sanitize_set but allows XFCC forwarding on non-mTLS connections if X-Cf-Proxy-Signature is also set


We can show the effect via printing the headers of a request routed to an application deployed in Cloud Foundry.

When mTLS is not enabled:

When mTLS is enabled, we can see the client certificate is taken along to your application as well as more informations about the subject:

TLS Configurations in SAP BTP Custom Domain Service (Custom Domain Manager)

Create new TLS configurations that can be used for one or multiple server certificate activations:

  1. Choose the TLS Configurations tile, and choose Create TLS Configurations to use the wizard to create each required configuration:

  2. Enter a name and choose Next Step


    The Client Authentication (mTLS) mode is displayed as disabled by default. Once the new configuration has been created, Client Authentication (mTLS) can be turned on by adding one or multiple trusted CA certificates.

  3. Choose Next Step:

  4. The summary information displays the entered configuration name and the status of the mTLS mode again. Choose Finish to exit the wizard and manage the created configuration.

  5. If you want to turn the Client Authentication (mTLS) mode on, from the corresponding drop-down list, select optional or required, as the case may be:

    In the Configuration pane, under the General Information section, you can use the Edit button to change the name, if desired. You can also use the Duplicate button to copy the existing configuration, with a new name. Alternatively, you can delete it by using the Delete button and then create a new one again, if desired.

    Note: Configurations that are already in use cannot be edited or deleted; they can only be duplicated.

  6. Switch to the Trust List tab and choose Add Trust List to upload your list of trusted certificates and assign it to your custom domains.

    On adding the trust list, client authentication is enabled. However, when the last CA certificate is removed from the trust list, client authentication is automatically turned off.

  7. Copy your trusted certificates list into the Add to Trust List text box and choose Add:

  1. Upload your server certificate by referring to Manage Server Certificates

  2. When activating your server certificate, the activation has to be done for one or more of the certificate's SANs and the TLS configuration of your choice. The activation can be modified or removed at any time and will take a few minutes until it is effective in the landscape load balancer. Any corresponding SaaS routes are also automatically activated.

    In the detail pane, choose Activate, and select the SANs you want to activate and choose Next Step.

  3. Select the TLS Configuration you created before, and choose Next Step:

  4. Confirm the TLS configuration and choose Finish:

Enable mTLS to Secure the Connection between Your Application and XSUAA

Mutual Transport Layer Security (mTLS) is considered more secure than the combination of client ID and client secret. Unlike retrieving the access token with client ID and client secret, no secret is shared between calling application and the service instance of SAP Authorization and Trust Management service (XSUAA).

This configuration enables your application to retrieve or exchange access tokens from an instance of the SAP Authorization and Trust Management service with mTLS. When using TLS, the client verifies the identity of the OAuth server during their handshake. By using mTLS, the OAuth server also verifies the identity of the client. Calls to other services and applications with the access token use the standard OAuth protocols.

You, as a developer, have the option to have the service provide the X.509 certificate for the binding or service key or if you already have your own public key infrastructure (PKI), you can provide your own.

Using XSUAA provided client certificate

Get access token (JWT token) via SAP BTP Destination service

SAP BTP Destination service offers the convenience of taking care of fetching a JWT token for the target app.

A good blog: SAP BTP Security: How to use mTLS with Destinations

Get access token (JWT token) via SAP Cloud SDK

To adhere to the latest recommended security best practices by SAP, some re-use and kernel services have enabled certificate-based authentication. As a consequence, SAP Cloud SDK also supports certificate-based authentication while accessing these services. If a service binding has a property credentials: { credential-type: x509 } then this is an indication that you can use certificate-based authentication to access the service.

To fetch the token, SAP Cloud SDK has provided an easier way. You can refer here for documentation.

Get access token (JWT token) via SAP CAP (Cloud Application Programming)

You can now configure @Sap/cds-mtxs to authenticate with X.509 (mTLS) against XSUAA when fetching a token for multitenancy and/or extensibility. In particular, cds login -m <clientid>[:<key>] can be run against an X.509-enabled application, supplying as <key> the private key of its X.509 client certificate. This configuration is usually made in the config parameters of the XSUAA resource in mta.yaml.

For more information, please read: MTX Services Reference


Enable mTLS with SAP Application Router and XSUAA to Protect Your Application

The application router supports the use of certificates for the creation of tokens and an mTLS handshake in backend connections.

To enable the mTLS authentication for backend connections, the following prerequisites must be met:

  • The authentication service instance that is bound to the application router, Authorization and Trust Management service (XSUAA) or Identity Authentication (IAS), must provide a certificate chain and a private key in its credentials.

    If the private key isn't provided in the credentials, you can also configure the environment variables XSUAA_PRIVATE_KEY (Authorization and Trust Management) and IAS_PRIVATE_KEY (Identity Authentication) in the application router to provide the private key.

  • In Cloud Foundry, the client certificate is propagated using the x-forwarded-client-cert header. To enable this, the backend URL must contain a .cert segment in its domain, or you can set TLS configurations with the SAP BTP Custom Domain service.

The application router gets the XSUAA or IAS tokens that provide the certificates chain and private key. The application router uses the certificates chain and private key from the credentials of the authentication service instance for the following:

  • The application router creates the HTTP connection to backend using the private key and a chain of intermediate and client certificates to enable the mTLS handshake. If the FULL_CERTIFICATE_CHAIN environment variable is enabled, the application router sends the entire chain of certificates provided in the binding of the authentication service (XSUAA or IAS) to the backend applications. If this environment variable is not enabled, the application router sends only the root and intermediate certificates from the chain.

  • When forwarding a request to business services, the application router uses these certificates also to create a client_credentials token or to exchange the login token.

For more details, please read:

1 Comment