Configuring mutual TLS

Mutual TLS (mTLS) provides certificate-based client authentication for enhanced security. mTLS is not enabled by default and requires prior authorization on a per-domain basis. To configure mTLS, follow these steps:

1. Request authorization. Create a support case to request mTLS enablement for your IBM Cloud account.

   After mTLS is enabled, it can't be disabled.

2. Enable mTLS:

   1. In the CIS console, click Security, then select the Mutual TLS tab.
   2. Click Enable.

3. Upload Root certificates:

   1. In the Root certificates table on the Mutual TLS page, click Add to define a new root certificate.

   2. Paste the certificate content into the Certificate content field. Provide a name for the Root CA certificate, and add one or more fully qualified domain names (FQDNs) of the endpoints that will use this certificate.

      These FQDNs are the hostnames that are used by the resources protected by the mTLS application policy. You must associate the Root CA with the FQDN used by the protected application.

   3. Click Save.

      If using an intermediate certificate, upload the entire certificate chain.

4. Create an mTLS access policy:

   1. In the MTLS access policies table on the Mutual TLS page, click Create to create an access application.

   2. Select or enter a hostname that matches one of the FQDNs associated with the uploaded root certificate and click Create.

      The application policy is pre-set to use a decision of non_identity, and include a rule that matches any valid client certificate.

5. Enable client certificate forwarding with the API:

   To forward validated client certificates to your origin server (useful for logging, auditing, or back-end authentication), you must enable forwarding.

   The client certificate is forwarded only with the first request in each mTLS connection.

   For an API curl example to enable client certificate forwarding, see the Update access certificates settings API.

   Client certificate headers sent to your origin server:

   • Cf-Client-Cert-Der-Base64: Base64-encoded DER version of the client certificate
   • Cf-Client-Cert-Sha256: SHA-256 fingerprint of the client certificate

   To verify forwarding status with the API:

   curl -X GET https://api.cis.cloud.ibm.com/v1/crn:v1:bluemix:public:internet-svcs:global:a/<account-id>:<instance-id>::/zones/<zone-id>/access/certificates/settings \
    -H 'X-Auth-User-Token: Bearer <IAM-TOKEN>'
   

6. Create a WAF custom rule to block unauthenticated requests:

   To improve security, especially for sensitive endpoints such as login paths or APIs, create a WAF rule to block requests that do not present a valid client certificate.

   1. In the CIS console, navigate back to the Security section, then select the Custom rules tab.

   2. Click Create.

   3. In the Create WAF custom rule side panel, click Use Expression Editor.

   4. Enter the following condition (update hostname and path as needed) in the Use Expression Builder field.

      (http.host eq "example.com" and http.request.uri.path eq "/authenticate" and not cf.tls_client_auth.cert_verified)
      

   5. Set the Action to Block.

   6. Click Create.

   This rule allows access to authenticate only if the client certificate is successfully verified. Requests without mTLS or with invalid certificates are blocked.
   

Testing mTLS access

The following example uses curl to test mTLS authentication by making requests with and without a client certificate.

1. Attempt to access the site without a client certificate.

   This example demonstrates using curl to test access to a site that enforces mTLS. The target URL in this example is https://auth.example.com.

   curl -sv https://auth.example.com
   

   Because no client certificate is provided, the request is expected to fail with a 403 Forbidden response.

2. Add your client certificate and private key to the request:

   curl -sv https://auth.example.com --cert example.pem --key key.pem
   

   If the client is properly authenticated, the response includes a CF_Authorization Set-Cookie header, indicating successful mTLS authentication.

Validating mutual TLS

When you enable this access policy, use the following workflow to validate client certificates:

All requests to the origin are evaluated for a valid client certificate.

1. The client initiates a connection by sending a Hello message.
2. The access application responds with a Hello and requests the client certificate.
3. The client sends its certificate for validation.
4. The client certificate is authenticated against the configured root certificate authority.
5. If a certificate chain is used, the system also checks for expired certificates and validates the entire chain.
6. If the client certificate is trusted, a signed JSON Web Token (JWT) is generated for the client that allows the request and subsequent requests to proceed.
7. If the client doesn't present a valid certificate, the server returns a 403 Forbidden response.

To retrieve access certificates with the API, see List access certificates.