Client certificates and their renewal

A client registered with tls_client_auth proves who it is with an X.509 certificate, and its access tokens are bound to that certificate (Sender-constrained tokens). Certificates expire, so every such client needs a way to get the next one. This page explains the options, what Versola does in each, what it does not do and what to watch. It is about the certificate of an API client, for example a bank with a FAPI 2.0 integration. The certificate that edge presents to auth for native apps is a different case: Edge client certificates.

Hands-on steps are in Automatic client certificate renewal (EST).

What Versola checks

For a tls_client_auth client, auth checks that the certificate chains to a trust anchor it knows and that the field named in the registration (mtlsAuth: subjectType and subjectValue) matches. The trust anchors are the trusted-certificates file of auth’s mutual-tls block, or, when a proxy terminates mutual TLS, whatever the proxy trusts. For the proxy path the tenant names the header and its encoding: mtlsCertificateHeader and mtlsCertificateEncoding (urlEncodedPem or base64Der), under Security, Tokens & keys, Mutual TLS. Nothing about a certificate is stored in the client record apart from what you registered, so the certificate itself is free to change.

Tokens are different. A token carries cnf.x5t#S256, the SHA-256 thumbprint of the certificate it was issued for. A new certificate has a new thumbprint, so tokens issued under the old certificate no longer work for the new one. After a renewal the client requests new tokens. See Sender-constrained tokens.

Choose how the certificate is renewed

Same subject, same CA

If the new certificate has the same subject (or the same SAN) the registration names and chains to the same CA, nothing changes in Versola. The client starts presenting the new certificate and requests new tokens. Do not touch the client record. Roll the certificate in your own PKI and let the old one expire.

Automatic enrolment and renewal through EST

RFC 7030 (Enrollment over Secure Transport) lets a client request a certificate over HTTPS. auth serves it under /.well-known/est/ and central decides what is issued and has the CA sign it, so auth holds no CA credentials. A client is registered with estEnrollment, which needs authMethod: tls_client_auth, and holds no certificate until it enrols.

The client needs two base URLs: enrolment on the issuer origin, renewal on the mutual-TLS origin. Steps are in Automatic client certificate renewal (EST). The rules:

• Subject from the registration. The certificate carries the subject the client is registered by (mtlsAuth, or CN=<client>,OU=<tenant>,O=Versola), never one the request names. It does not change at renewal, so the registration stays as it is.
• New key every time. Keys are EC P-256 or RSA of at least 2048 bits, and a renewal that reuses the previous key is refused.
• One-time token. An operator creates it in central. It lives 24 hours by default (168 at most), is shown once, works once and is stored only as a hash. A new token replaces the client’s unused ones.
• Short certificates. The lifetime is client-certificates.validity (14 days by default). A certificate renews only in its last third (client-identity.renew-window); earlier is 403, naming when the window opens.
• Chain. Renewals form a chain from the enrolment. At client-identity.max-age (a year by default) renewal stops with 403 until an operator calls POST /configuration/clients/est/extend, or client-identity.auto-extend is on. The end is soft: a certificate issued just before it lives its whole validity. The date is in every answer as Versola-Chain-Ends-At.
• Generations and revocation. What is revoked is the right to renew, not the certificate. Every certificate belongs to a generation; a re-enrolment with a new token, or POST /configuration/clients/est/revoke, ends the right of every earlier one (401). A certificate that a renewal replaced and that renews again after a 3-minute grace closes the chain (403): the key is in two hands. The operator enrols the client again.
• Rate limit. simpleenroll allows 30 attempts a minute per client id and replica (429, Retry-After).

central holds the CA power (step-ca or cert-manager, Edge client certificates); auth has none. But auth is in the trust zone of the mutual-TLS terminator: it tells central which certificate a client presented and which token it sent, and central cannot check either. Whoever controls auth, or its internal token to central, can renew the certificate of any EST client that has a current one, and enrol with a token they observe. What central narrows: only a certificate issued through EST, of the current generation, renews; only in the last third of its life; the chain ends at max-age; and the subject is the registered one.

Tokens and certificates. An access token is bound to the certificate it was issued for (cnf.x5t#S256). A renewed certificate has another thumbprint, so tokens issued under the old one do not validate with the new one. The client keeps presenting the old certificate with the old tokens until they expire, or requests new tokens with the new certificate.

What is not covered

• A subject change. The certificate carries the registered subject, so EST cannot change it. Change the registration, or register a new client, and move over.
• A change of CA. Moving a client to another CA means adding the new CA to the trust anchors of auth before the client switches, then removing the old one after the last certificate it signed has expired. EST does not do this for you.
• Self-signed clients. EST needs tls_client_auth. A self_signed_tls_client_auth client is matched on the key registered in its jwks, not on a CA. Rotation is manual: register the new key in the JWK Set before the client starts using it, switch the client, remove the old key when the old certificate is out of use.
• Expired certificates and rekeying a lost key. An expired certificate is not renewed with itself, and a lost key is not recovered: an operator creates a new token and the client enrols again.

Operations

• Expiry monitoring. Versola does not notify a client that its certificate is about to expire. Alert on the client’s certificate end date in your own monitoring, with a margin of several renewal periods. For an EST client, GET /configuration/clients shows est.certificateExpiresAt and est.chainEndsAt; alert on a certificate in its last third that has not renewed, and on the est_requests_total outcomes (Observability).
• Hot reload on the client. A renewed certificate is useless until the client’s TLS stack uses it. Make the client reload the key and certificate without a restart, or restart it in a rolling way, and request new tokens straight after.
• Trust anchors. Keep the CA that signs the client certificates in trusted-certificates of auth and, if you serve the API on edge’s mutual-TLS listener, of edge too. During a CA change keep both CAs.
• Revocation is expiry. Versola does not consult a CRL or OCSP responder. A certificate stays valid until notAfter, so short lifetimes are the revocation mechanism. For an EST client the revocable thing is the right to renew (POST /configuration/clients/est/revoke). To cut a certificate off at once, change the client’s mtlsAuth subject or delete the client in central.

Related

• Automatic client certificate renewal (EST)
• Client
• Calling an API with a certificate-bound token