Cloudflare Docs
Cloudflare Zero Trust
Edit this page
Report an issue with this page
Log into the Cloudflare dashboard
Set theme to dark (⇧+D)

Client certificate

The Client Certificate device posture attribute checks if the device has a valid certificate signed by a trusted certificate authority (CA). The posture check can be used in Gateway and Access policies to ensure that the user is connecting from a managed device.

Feature availability
WARP modesZero Trust plans
All modesAll plans
SystemAvailabilityMinimum WARP version1
Windows2024.6.415.0
macOS2024.6.416.0
LinuxComing soon
iOS
Android
ChromeOS

1 Client certificate checks that ran on an earlier WARP version will continue to work. To configure a new certificate check, update WARP to the versions listed above.

​​ Prerequisites

  • A CA that issues client certificates for your devices. WARP does not evaluate the certificate trust chain; this needs to be the issuing certificate.
  • Cloudflare WARP client is deployed on the device.
  • A client certificate is installed and trusted on the device.

​​ Configure the client certificate check

  1. Use the Upload mTLS certificate endpoint to upload the certificate and private key to Cloudflare. The certificate must be a root CA, formatted as a single string with \n replacing the line breaks. The private key is only required if you are using this custom certificate for Gateway HTTPS inspection.

    curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/mtls_certificates" \
    --header "X-Auth-Email: <EMAIL>" \
    --header "X-Auth-Key: <API_KEY>" \
    --header "Content-Type: application/json" \
    --data '{
    "name": "example_ca_cert",
    "certificates": "-----BEGIN CERTIFICATE-----\nXXXXX\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN PRIVATE KEY-----\nXXXXX\n-----END PRIVATE KEY-----",
    "ca": true
    }'

    The response will return a UUID for the certificate:

    {
    "success": true,
    "errors": [],
    "messages": [],
    "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "name": "example_ca_cert",
    "issuer": "O=Example Inc.,L=California,ST=San Francisco,C=US",
    "signature": "SHA256WithRSA"
    ...
    }
  2. In Zero Trust, go to Settings > WARP Client.

  3. Scroll down to WARP client checks and select Add new.

  4. Select Client certificate.

  5. You will be prompted for the following information:

    1. Name: Enter a unique name for this device posture check.
    2. Operating system: Select your operating system.
    3. OS locations: Specify the location(s) where the client certificate is installed.
      SystemCertificate stores
      Windows- Local machine trust store
      - User trust store
      macOS- System keychain
      Linux- NSSDB
      - To search a custom location, enter the absolute file path(s) to the certificate and private key (for example /usr/local/mycompany/certs/client.pem and /usr/local/mycompany/certs/client_key.pem). The certificate and private key must be in PEM format. They can either be in two different files or the same file.
    4. Certificate ID: Enter the UUID of the root CA.
    5. Common name: (Optional) To check for a specific common name on the client certificate, enter a string with optional ${serial_number} and ${hostname} variables (for example, ${serial_number}_mycompany). WARP will search for an exact, case-insensitive match. If you do not specify a common name, WARP will ignore the common name field on the certificate.
    6. Check for Extended Key Usage: (Optional) Check whether the client certificate has one or more attributes set. Supported values are Client authentication (1.3.6.1.5.5.7.3.2) and/or Email (1.3.6.1.5.5.7.3.4).
    7. Check for private key: (Recommended) When enabled, WARP checks that the device has a private key associated with the client certificate.
  6. Select Save.

Next, go to Logs > Posture and verify that the client certificate check is returning the expected results.

​​ How WARP checks for a client certificate

Learn how the WARP client determines if a client certificate is installed and trusted on the device.

  1. Open a PowerShell window.
  2. To search the local machine trust store for a certificate with a specific common name, run the following command:
PS C:\Users\JohnDoe> Get-ChildItem Cert:\LocalMachine\My\ | where{$_.Subject -like "*<COMMON_NAME>*"}
  1. To search the user trust store for a certificate with a specific common name, run the following command:
PS C:\Users\JohnDoe> Get-ChildItem Cert:\CurrentUser\My\ | where{$_.Subject -like "*<COMMON_NAME>*"}
  1. Open Terminal.
  2. To search System Keychain for a certificate with a specific common name, run the following command:
$ /usr/bin/security find-certificate -c "<COMMON_NAME>" -p /Library/Keychains/System.keychain
  1. Open Terminal.
  2. To search NSSDB for a certificate with a specific common name, run the following command:
$ certutil -L -d sql:/etc/pki/nssdb -r -n <COMMON_NAME>

For the posture check to pass, a certificate must appear in the output that validates against the uploaded root CA.