mTLS Integration (Optional)

What is mTLS?

mTLS (Mutual TLS) is a security protocol where both the client and server authenticate each other using certificates, unlike regular TLS where only the server is authenticated.

How it works

Socure provides a dedicated mTLS endpoint:

At this endpoint:

📘

Account-level constraints:

Flow diagram

RiskOS™(HTTP)NEG(K8s endpoints)Backend ServiceURL MapTarget HTTPS Proxy+ ServerTlsPolicy+ TrustConfigForwarding Rule(Public IP:443)ClientRiskOS™(HTTP)NEG(K8s endpoints)Backend ServiceURL MapTarget HTTPS Proxy+ ServerTlsPolicy+ TrustConfigForwarding Rule(Public IP:443)ClientClient sendsclient certificate (mTLS)alt[Missing/Invalid client cert]alt[Valid client cert]Connect to https://mtls.riskos.socure.comForward TLS handshakeTLS + mTLS handshakeValidate client cert via TrustConfigclientValidationMode = REJECT_INVALIDTLS Handshake FailureConnection TerminatedMark request as mTLS-authenticatedSelect route based on host/pathRoute to Backend ServiceSelect endpointHTTP request (no TLS in-cluster)HTTP responseResponseResponseResponseEncrypted HTTPS responseResponse to clientmTLS (strict) – Client → External LB → K8s

Prerequisites

Make sure the following are in place:

  1. Ability to perform HTTPS requests with client certificate authentication.
  2. Required certificate assets unique to your RiskOS™ account:
  1. Please share the Customer CA bundle (Root or Intermediates) with Socure for configuring in our Trust Store. The format should be as follows:
-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

Certificate requirements

1. Client certificate type

📘

Note:

The customer must provide a certificate authority (CA) certificate with Basic Constraints set to CA:true.

2. Subject / DN

We recommend:

Socure maps certificate identity (CN / DN / serial / issuer) to your account on our side for future reference.

3. Key type and size

RSA 2048+ or ECDSA (P-256)

How Socure configures trust on our side

You don't need to do this, but it helps you understand the behavior:

Implication for you: If your client does not present a valid certificate signed by this CA, the TLS handshake fails before any HTTP request is received.

Client-side configuration – general

From the client side, mTLS is simply:

You typically configure:

Example integrations

1. cURL

cURL

curl -v \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --cacert /path/to/ca_root.crt \
  https://mtls.riskos.socure.com/api/evaluation
  --header 'accept: application/json' \
  --header 'content-type: application/json'
  --data '
  {
    "data": {
      "individual": {
        .....
      },
      ....
    },
    ....
  }

Notes:

If the certificate is missing or invalid, you see a TLS handshake error such as:

2. Python as a client

Python

import requests

BASE_URL = "https://mtls.riskos.socure.com"

# Paths to your certificate files
CLIENT_CERT = "/path/to/client.crt"      # client certificate (PEM)
CLIENT_KEY = "/path/to/client.key"       # client private key (PEM)
CA_CERT = "/path/to/ca_root.crt"         # CA to trust our server cert (optional if system trust is enough)

def main():
    try:
        # JSON payload matching your curl example
        payload = {
            "data": {
                "individual": {
                   ....
                },
                ....
            },
           ....
        }

headers = {
            "accept": "application/json",
            "content-type": "application/json",
        }

response = requests.post(
            f"{BASE_URL}/api/evaluation",
            headers=headers,
            json=payload,               # sends JSON body like curl --data '<json>'
            cert=(CLIENT_CERT, CLIENT_KEY),
            verify=CA_CERT,             # same as --cacert; use True if using system trust store
            timeout=10,
        )
        print("Status:", response.status_code)
        print("Body:", response.text)
    except requests.exceptions.SSLError as e:
        print("TLS/mTLS error:", e)
    except requests.exceptions.RequestException as e:
        print("Request error:", e)

if __name__ == "__main__":
    main()

API behavior and authentication

Please note the following important points:

Error scenarios you should expect

  1. TLS handshake failure (no HTTP status code)
    • Likely causes:
      • Missing client certificate
      • Invalid chain (not signed by configured CA)
      • Expired or not yet valid certificate
    • Resolution:
      • Check your client certificate/key configuration
      • Check certificate validity dates
      • Confirm you're using the correct certificate for production vs sandbox
      • Confirm CA chain matches what you shared with us
  2. HTTP 401 / 403 / 429 from API
    • mTLS succeeded, but:
      • Bearer token / API key is invalid or missing
      • Your IP is not whitelisted in our system
      • Your request hit the rate limit
  3. HTTP 404 / 405 / 500 responses
    • mTLS layer is OK; these are regular API-level errors (wrong path, method, or internal error)

Certificate rotation guidance

Customer responsibilities:

Socure will:

How to inform us: Contact our Support team at support@socure.com.

Lead time required: Please allow 3–5 business days for CA changes

Common error messages and causes

Errors are often reported by the client's application, browser, or server logs during the TLS handshake.

These indicate a fundamental failure in the TLS negotiation process, often due to configuration issues on either the client or server side.

These errors are often seen in clients like Python requests or cURL and indicate a problem with the certificate itself or the validation process.

This happens when the server (or client) cannot build a complete, trusted chain from the presented certificate back to a known and trusted root Certificate Authority (CA).

The validating party has identified that the certificate's validity date is in the past, or it is present on a Certificate Revocation List (CRL).

The client certificate does not have the required Extended Key Usage (EKU) attribute (specifically "Client Authentication") to be used for mTLS.

The client did not send a certificate when the server requested one during the handshake.

The certificate uses an algorithm or key size that is not supported by the validating system.

The hostname in the server's certificate does not match the domain name the client is trying to connect to.