Interface MtlsOptions

Options that control mutual-TLS certificate-bound access token validation (RFC 8705 §3).

Remarks

When a client authenticates to the authorization server with a TLS client certificate, the issued access token carries a cnf.x5t#S256 claim: the base64url-encoded SHA-256 thumbprint of that certificate. This SDK validates, on each request, that the certificate presented on the TLS connection matches the thumbprint in the token.

Because APIs commonly run behind a TLS-terminating proxy (nginx, ALB, Cloudflare, etc.), the SDK cannot read the TLS socket directly. The client certificate must be supplied by the caller — see getCertificate on the Express auth() middleware — and is then passed to this verifier as raw PEM or DER.

mTLS is opt-in: unlike DPoP, it depends on a certificate resolver the caller must supply (see getCertificate on the Express auth() middleware), so it cannot safely default to on. The Express middleware enables it automatically when getCertificate is supplied, unless enabled is set explicitly.

Behavior matrix:

• Default ({ enabled: false }): The cnf.x5t#S256 claim is ignored and no certificate binding is checked.

• Enabled ({ enabled: true, required: false }): Validates the certificate binding when the token carries cnf.x5t#S256; plain bearer tokens are accepted as-is.

• Required ({ enabled: true, required: true }): Every access token must be certificate-bound; a token without a valid cnf.x5t#S256 binding is rejected.

• Misconfiguration ({ required: true } without enabled: true): Invalid — a binding cannot be required unless mTLS is explicitly enabled.

Interaction with DPoP: A token carries at most one confirmation method, so mTLS and DPoP are mutually exclusive per token. When both are enabled, DPoP is evaluated first and takes precedence: the mTLS verifier runs only for requests the DPoP path does not handle. As a result required: true is scoped to the mTLS path (it does not force a certificate binding on a request satisfied by a DPoP-bound token), and enabling dpop.required makes these options inert because every request is then routed to the DPoP path.

See

https://www.rfc-editor.org/rfc/rfc8705