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:
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
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
To fetch the token, SAP Cloud SDK has provided an easier way. You can refer here for documentation.
You can now configure
For more information, please read: MTX Services Reference
To enable the mTLS authentication for backend connections, the following prerequisites must be met:
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:
For more details, please read:
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
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 aX-SSL-Client-prefix (see below). In case of the request not containing a client certificate, theX-Forwarded-Client-Certheader won't be set. If theX-Forwarded-Client-Certheader is manually set by a client, HAProxy overwrites the header by a valid certificate received by HAProxy in the mTLS handshake, if theforwarded_client_certproperty is set tosanitize_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-verifyheader) 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
| 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 |
| 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 |
Sample
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:
Choose the TLS Configurations tile, and choose Create TLS Configurations to use the wizard to create each required configuration:
Enter a name and choose Next Step：
Note:
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.
Choose Next Step:
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.
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.
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.
Copy your trusted certificates list into the Add to Trust List text box and choose Add:
Upload your server certificate by referring to
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.
Select the TLS Configuration you created before, and choose Next Step:
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
- Enable mTLS Authentication to SAP Authorization and Trust Management Service for Your Application
- Implementing Custom Token Retrieval from SAP Authorization and Trust Management Service with mTLS
Using customized 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
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:
- Mutual TLS Authentication (mTLS) and Certificates Handling
- Enable mTLS with SAP Application Router, Custom Domain Service and XSUAA to Protect Your Application
- SAP Managed Tags:
1 Comment
