Certificates and mutual TLS in your tenant

Certificate authorities

A client certificate counts only when an authority listed under Certificates vouches for it. There are two kinds:

• Teaching authority. Your tenant creates the key pair (EC P-256 or RSA 3072) and a self-signed authority certificate valid for 30 days to 10 years. The private key is sealed in the tenant and is never shown or exported. Its certificate is public at /pki/authorities/<id>/certificate on your tenant's address.
• Imported authority. Paste the PEM certificate of an authority you trust, such as a partner's. It must be an authority (CA true, and keyCertSign if it lists key usage), current, with an RSA key of at least 2048 bits or an EC key. Only its certificate is stored.

A client certificate must be issued directly by one of them; to trust what an intermediate authority issues, import the intermediate itself. Stop trusting or Remove stops every certificate an authority issued at once. Retire stops a teaching authority issuing; what it issued keeps working until it expires or is revoked.

Issuing, renewing and revoking

The client makes its own key and a certificate request, so the private key never leaves it:

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -noenc -keyout client.key -out client.csr   -subj "/O=Lab Printer/CN=lab-print-orders" -addext "subjectAltName=DNS:orders.printer.example"

Paste the request under Issue certificate and choose a lifetime of 1 to 397 days (never past the authority's own expiry). The request's signature must verify with the key it carries: that proves the client holds it. The subject (CN, O, OU, C, L, ST, serialNumber, UID, DC, emailAddress) and up to 10 DNS, URI, email or IP alternative names are copied. Every certificate is for TLS client authentication only (extended key usage clientAuth, CA false) and names its authority's revocation list. The page shows the certificate and the chain to save next to the key.

Renew issues a new certificate with the same names and, unless you paste a new request, the same key; it has a new serial and thumbprint. Revoke takes a reason (keyCompromise, superseded and so on): the certificate stops authenticating at once, and the next revocation list, at /pki/authorities/<id>/crl (DER, valid for seven days, signed again after each revocation), lists it until it expires. Your tenant checks its own records, so it does not need the CRL itself.

The mutual TLS addresses

The sign-in pages never ask for a certificate: only API clients use the separate mutual TLS address. In Flow Policy, turn Mutual TLS addresses On. The token, introspection, revocation, UserInfo, pushed request and device endpoints, and the sample photo API, then also answer on one host per environment that asks for a client certificate, below your tenant's own path:

"mtls_endpoint_aliases": {"token_endpoint": "https://mtls.beyondthelogin.com/tenant-<id>/oauth/token", ...},
"tls_client_certificate_bound_access_tokens": true

Discovery lists them, and token_endpoint_auth_methods_supported adds tls_client_auth and self_signed_tls_client_auth. The certificate is read only from the TLS connection: a Client-Cert header sent by a client, or by anything in front of it, is ignored everywhere. Sign-in pages, management, SCIM and the decision API are not offered there. Mutual TLS stays on while any client uses a certificate method or certificate-bound tokens.

Client authentication

In Clients, set a confidential client's Client authentication to one of the two certificate methods. Its token request then sends only client_id, over the mutual TLS address:

curl --cert client.crt --key client.key "$MTLS_TOKEN" -d grant_type=client_credentials -d client_id=$CLIENT_ID

• tls_client_auth needs a certificate from a trusted, current authority, current itself, for client authentication, not revoked, and carrying the one value registered for the client: a subject DN (tls_client_auth_subject_dn, compared attribute by attribute without regard to case) or a DNS name, URI, IP address or email address among its alternative names. A renewed certificate with the same names needs no change.
• self_signed_tls_client_auth needs a certificate listed in the client's own public keys: add it as x5c on the matching JWK in Access Token Management (the certificate must hold that same key). No authority vouches for it; the registration is the trust, so register a new certificate before switching to it.

A client registered for either method that presents no certificate, or another one, gets invalid_client. FAPI 2.0 clients may use either method instead of private_key_jwt.

Certificate-bound tokens

A client with Certificate-bound access tokens (tls_client_certificate_bound_access_tokens) requests tokens over mutual TLS, and each access token is bound to its certificate: a JWT carries cnf: {"x5t#S256": ...}, the certificate's SHA-256 thumbprint, and introspection reports the same cnf. token_type stays Bearer. Any client can ask for this, public ones included: a public client's refresh tokens are then bound to the certificate as well. A client uses DPoP or certificates, not both.

UserInfo and the sample photo API accept a bound token only over a mutual TLS connection presenting the same certificate, and refuse it with HTTP 401 invalid_token otherwise. SCIM and the decision API, which are not on the mutual TLS address, refuse bound tokens. A bound token is exchanged (token exchange) only over a connection with its certificate. In Resources, Accept only certificate-bound tokens makes the sample photo API refuse other tokens. Every resource's metadata publishes tls_client_certificate_bound_access_tokens: true while mutual TLS is on, since the field says an API accepts certificate-bound tokens, not that it requires them. Your own APIs compare the connection's certificate thumbprint with cnf.

Settings and limits

A tenant has up to 10 certificate authorities and 500 unexpired issued certificates, shown on its Usage view; expired certificates are removed 30 days after they expire. Permissions: viewing (tenant.oauth.certificates.read), managing authorities (tenant.oauth.certificate_authorities.manage), issuing and renewing (tenant.oauth.certificates.issue) and revoking (tenant.oauth.certificates.revoke) are separate, and Tenant Admin holds all four. A point-in-time restore keeps authorities removed, distrusted or retired since, revocations, client certificate settings and mutual TLS turned off since; a certificate issued after the restore point stops working, because its record is gone.

Refusals and history

Audit records each change to authorities and certificates, and each token request names the method and matched value, such as Client certificate matched SAN DNS orders.printer.example, and the binding, never the certificate. Refusals carry the reasons client_certificate_missing, client_certificate_invalid, client_certificate_oversized, client_certificate_untrusted, client_certificate_expired, client_certificate_purpose, client_certificate_revoked, client_certificate_unknown, client_certificate_mismatch, client_certificate_not_registered, client_certificate_required, sender_constraint_conflict, refresh_certificate_mismatch and subject_token_certificate_mismatch, and at APIs certificate_required, certificate_mismatch and certificate_bound_token_required.

What is not covered

Chains are one level deep. Imported authorities' own revocation lists and OCSP are not fetched, so revoke such a certificate by distrusting its authority or changing the client's registered value. Teaching authorities issue client certificates only, never server certificates. The mutual TLS host serves only the endpoints listed above.