Mutual TLS (mTLS) Client Authentication

OAuth 2.0 Mutual TLS (mTLS) Client Authentication and Certificate-Bound Access Tokens is an extension to OAuth 2.0 that provides enhanced security through the use of X.509 certificates.

This feature implements RFC 8705 and provides two key security capabilities:

1. mTLS Client Authentication - authenticate OAuth clients using X.509 certificates instead of client secrets
2. Certificate-Bound Access Tokens - cryptographically bind access tokens to client certificates to prevent token theft and replay attacks

What is Mutual TLS?

Mutual TLS (mTLS) is a security protocol where both the client and server authenticate each other using X.509 certificates during the TLS handshake. Unlike standard TLS where only the server presents a certificate, mTLS requires the client to also present a valid certificate.

Benefits include:

• Strong authentication - certificate-based authentication is more secure than shared secrets
• Non-repudiation - certificate usage provides proof of client identity
• Token binding - access tokens can be bound to the client certificate, preventing token theft

Domain configuration

• Main domain - used for authorization, discovery, and non-mTLS endpoints (for example oauth.example.com)
• mTLS subdomain - dedicated domain for mTLS-enabled endpoints, like the token endpoint (for example mtls.oauth.example.com)

mTLS client authentication methods (web clients)

For web clients, the admin console supports the following client authentication methods:

• mTLS with PKI certificate (TLS_CLIENT_AUTH)

PKI-based mutual TLS authentication (RFC 8705 Section 2.1). Validates the client certificate against a trusted CA and matches the certificate subject DN.

• mTLS with self-signed certificate (SELF_SIGNED_TLS_CLIENT_AUTH)

Self-signed certificate mutual TLS authentication (RFC 8705 Section 2.2). Validates the client certificate against a pre-registered certificate.

Support onboarding and certificate rotation

The operational model differs depending on which authentication method you choose:

mTLS with PKI certificate

• You only need to reach out to support once to register the root CA or intermediate CA that will be trusted for your mTLS subdomain.
• As long as your client certificates are signed by this root/intermediate, they will work without further changes on our side.
• You can rotate client certificates without contacting support as long as the subject DN stays the same (because the platform matches the subject DN configured on the web client).

mTLS with self-signed certificate

• The exact self-signed certificate must be registered by support on the mTLS domain.
• When you rotate/renew the certificate, you must request support to register the new certificate in time.

How mTLS client authentication works

When using mTLS client authentication, the client must present a valid X.509 certificate during the TLS handshake with the token endpoint:

sequenceDiagram
    participant Client as Web client
    participant mTLS Endpoint as OneWelcome mTLS token endpoint
    participant OAuth Server as OneWelcome authorize endpoint

    Note over Client,OAuth Server: Step 1: Authorization (Standard OAuth)
    Client->>OAuth Server: Authorization Request
    OAuth Server->>Client: Authorization Code

    Note over Client,OAuth Server: Step 2: Token Request with mTLS
    Client->>mTLS Endpoint: TLS Handshake
    mTLS Endpoint->>Client: Request Client Certificate
    Client->>mTLS Endpoint: Present X.509 Certificate
    mTLS Endpoint->>mTLS Endpoint: Validate Certificate (PKI or pre-registered)
    mTLS Endpoint->>mTLS Endpoint: Extract Certificate Subject DN

    alt Certificate Valid
        Client->>mTLS Endpoint: POST /token<br/>(grant_type=authorization_code)
        mTLS Endpoint->>mTLS Endpoint: Verify certificate matches configured client

        alt Certificate matches the client_id
            mTLS Endpoint->>mTLS Endpoint: Issue Access Token
            mTLS Endpoint->>Client: 200 OK + Access Token
        else No match
            mTLS Endpoint->>mTLS Endpoint: Authentication Failed
            mTLS Endpoint->>Client: 401 Unauthorized
        end
    else Certificate Invalid
        mTLS Endpoint->>Client: TLS Handshake Failed
    end

Certificate validation

The platform validates the certificate used for client authentication as follows:

• mTLS with PKI certificate
• Validate the certificate chain against the registered trusted root/intermediate CA
• Check certificate validity period (not before / not after)

• Match the certificate subject DN to the subject DN configured on the web client

• mTLS with self-signed certificate

• Check the presented certificate matches the pre-registered certificate
• Check certificate validity period (not before / not after)
• Match the certificate subject DN to the subject DN configured on the web client

Certificate-Bound Access Tokens (RFC 8705)

Certificate-bound tokens provide an additional security layer by binding the access token to the mTLS certificate used during token issuance.

When Certificate-Bound Access Tokens (RFC 8705) (mtlsCertificateBoundAccessTokens) is enabled for a web client:

• Access tokens issued to this client using mTLS authentication will be bound to the client's certificate.
• The platform will add the cnf claim to:
• the JWT access token payload (if JWT access tokens are used)
• the token introspection response (for opaque tokens and for introspection of JWTs)

The cnf claim

When certificate-bound tokens are enabled, a JWT access token includes a confirmation (cnf) claim containing the certificate thumbprint. For opaque tokens, this claim is available via the introspect endpoint.

JWT access token example:

{
  "ver": 1,
  "jti": "AT.abc123",
  "iss": "https://oauth.example.com/oauth",
  "aud": "api.example.com",
  "iat": 1637000000,
  "exp": 1637003600,
  "client_id": "my-mtls-client",
  "scope": "profile read",
  "sub": "user-123",
  "cnf": {
    "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
  }
}

The x5t#S256 field contains the base64url-encoded SHA-256 thumbprint of the client certificate's DER encoding.

Configuration guide

Prerequisites

Before configuring mTLS, ensure:

1. mTLS subdomain is configured - contact support to configure the mTLS domain for your tenant
2. Client certificate is available - either PKI-issued or self-signed certificate
3. Certificate subject DN is known - the subject DN of the client certificate

Configuring a web client for mTLS

To enable mTLS client authentication for a web client:

1. Navigate to Configuration > Web Clients in the admin console
2. Create a new web client or edit an existing one
3. Configure the following mTLS-specific fields:

Discovery and metadata

The OAuth server's discovery endpoint advertises mTLS support through the mtls_endpoint_aliases field:

Request:

GET /oauth/.well-known/openid-configuration HTTP/1.1
Host: oauth.example.com

Response (excerpt):

{
  "issuer": "https://oauth.example.com/oauth",
  "authorization_endpoint": "https://oauth.example.com/oauth/v1/authorize",
  "token_endpoint": "https://oauth.example.com/oauth/v1/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt",
    "tls_client_auth"
  ],
  "mtls_endpoint_aliases": {
    "token_endpoint": "https://mtls.oauth.example.com/oauth/v1/token",
  }
}

References

• RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 7519: JSON Web Token (JWT)
• OpenID Connect Discovery
• OAuth Client Authentication Methods
• Web Clients
• Access Tokens