TLS and mutual TLS
iya-sts serves its main port over TLS
(RFC 8446, TLS 1.2 and 1.3) with a
certificate issued by its own certificate authority, and asks every connection
for a client certificate while requiring none. Presenting one is the client’s
decision: GET /tls/sign-in signs the holder of a verified certificate in, and
RFC 8705 binds tokens to it. The same
certificate is presented by LDAPS on 636 and by the embedded debugger’s
listener, so one trust anchor covers every socket. The socket and its truststore
are shared by every trust realm; the session a certificate starts goes in
the realm of the authority that signed it.
Features
HTTPS on the main port
global.https makes the main port (global.port, 8081) HTTPS. Its built-in
default follows oauth2.rfc9700 / oauth2.oauth21, and every appconfig file
this repository ships turns it on — so the port is HTTPS unless
STS_HTTPS=false. It is one listener in one scheme, never both.
The main port presents the same certificate as LDAPS 636 and the embedded debugger’s listener, so trusting this service is one decision for every socket rather than three, and a caller who has trusted it for the other sockets does not meet an unencrypted one on the port every protocol family answers on.
It costs one unverified call, necessarily. With HTTPS on there is no plain
listener left except /pki/ on pki.httpPort, and in development the key does
not exist until the process starts, so nothing can hold an anchor for it in
advance. The first fetch of the certificate is made with verification off, and
everything after it is verified:
curl -k https://localhost:8081/tls/server-certificate > /tmp/sts.pem
curl --cacert /tmp/sts.pem https://localhost:8081/healthcheck # verified from here on
export NODE_EXTRA_CA_CERTS=/tmp/sts.pem # for a node client
GET /tls/server-certificate exists so that a caller can put the certificate in
its own truststore rather than switching verification off, which is the habit
this workflow exists to break. It is on the main port because that is the port
reachable before anything is trusted.
STS_HTTPS=false restores the plain port, and it is a supported configuration
rather than an escape hatch: a client that cannot be taught to trust a
per-start certificate is exactly the thing this service exists to exercise.
tls.minVersion (TLS 1.2 by default), tls.ciphers, tls.groups and
tls.signatureAlgorithms apply to the main
port, LDAPS and the debugger’s listener alike, and each binds global.host. A
cipher list that matches nothing stops the service at startup, naming the
setting.
The listeners: TLS 1.2, the TLS 1.3 suites, post-quantum only, client certificates
Server configuration → Listeners (/admin/listeners,
GET /admin-api/listeners, #423) lists every socket this service answers on and
what each one is held to. Its settings are runtime: a change reaches every
listener at its next handshake, with no restart and no rebind.
| Setting | Default | What it does |
|---|---|---|
tls.disableTls12 |
on (since #429) | Every TLS listener negotiates TLS 1.3 only, whatever tls.minVersion says. Off lets a client negotiate TLS 1.2 (see the warning below). |
tls.tls13CipherSuites |
TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256 |
The TLS 1.3 suites, ticked and numbered on the page; the server’s order wins. Any of RFC 8446’s five, CCM included. At least one is required. |
tls.pqcOnly |
off | TLS 1.3 only, the 256-bit suites only, and the ML-KEM groups only (see below). |
tls.mainPortDisableOptionalClientCertificate / tls.mainPortRequireClientCertificate |
off / off | The main port: send no CertificateRequest / require a certificate that chains to the client truststore. |
ldap.ldapsDisableOptionalClientCertificate / ldap.ldapsRequireClientCertificate |
on / off | LDAPS: the same pair. LDAPS asks for nothing by default, as it always did. |
debugger.disableOptionalClientCertificate / debugger.requireClientCertificate |
off / off | The protocol debugger’s listener. |
“Require” wins over “do not ask”. A required certificate is verified against the client truststore (Protocols → Client-certificate truststore, and the certificates this service issues), so a handshake without one is refused.
Warning. Requiring a client certificate on the main port refuses every browser without one, discovery, the JWKS and every public document, and a load balancer’s or container’s HTTPS health check. Turning off “ask” on the main port stops RFC 8705 certificate-bound tokens and client authentication,
GET /tls/sign-in, EST with a certificate and the remote XACML PEP there.
What “post-quantum safe” means for a TLS 1.3 suite. A suite names only the
record protection, the AEAD and its hash. Grover’s algorithm halves a symmetric
key, so TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 (256-bit
keys) keep 128 bits against a quantum adversary and are marked post-quantum safe;
the AES-128 suites keep 64 and are not. CNSA 2.0 allows AES-256 alone. What stops
a session recorded today being decrypted later is the key EXCHANGE, so
tls.pqcOnly also keeps only the ML-KEM groups of tls.groups (X25519MLKEM768,
SecP256r1MLKEM768, SecP384r1MLKEM1024, MLKEM512/768/1024) and turns TLS 1.2 off,
which has no ML-KEM group. It does not restrict the signature algorithms: a
handshake cannot be forged after the fact. A choice that leaves nothing
post-quantum is refused (STS-TLS-0043), and one reaching the service from the
environment stops it (STS-TLS-0042).
Warning.
TLS_AES_128_CCM_8_SHA256has an 8-byte tag and RFC 8446 says it is not for general use; choose it only for a client that offers nothing else.
The SPIFFE gRPC listeners and the channel between cells take the TLS 1.2, suite and post-quantum settings too, and have no client-certificate toggles: their protocols decide. The SPIRE Server API must reach an agent with no SVID yet, and the Broker API and the cell channel always require a certificate. The cell channel is TLS 1.3 always.
EVERY SETTING IS PER LISTENER (#429). Each TLS listener has its own row for
every setting above and its TLS settings below, named listener<Id>.<setting>.
For example, listenerLdaps.disableTls12 or listenerMain.tls13CipherSuites.
- Listeners:
Main,Ldaps,Debugger,SpiffeServer,SpiffeBroker,Cell. - Inheritance: each row inherits the service-wide value until it is set.
inheritin a list of choices, or an empty box, means inherit. - Truststore: a listener’s own
trustAnchorsFilereplaces the service’s file anchors for that listener alone. The runtime anchors from/admin/tls/trustare shared by every listener. - Where they are edited: Server configuration → Listeners has a tab per listener. Each tab shows what is in force there first, then its own rows. The Service-wide defaults tab holds what every listener inherits.
- What some listeners lack: the cell channel is TLS 1.3 always, so it has no TLS 1.2 rows. The SPIFFE listeners and the cell channel verify clients against their protocol’s trust bundle, so they have no truststore rows.
Warning. Turning TLS 1.2 on, service-wide or for one listener, lets a client negotiate it. FAPI 2.0 and BCP 195 still allow TLS 1.2 with the AES-GCM suites, but TLS 1.2 has no post-quantum key exchange.
A custom listener (#472 — the service’s, or a realm’s own) carries the
same settings in its definition’s tls block, by their short names
(disableTls12, pqcOnly, tls13CipherSuites, …), and its client
authentication as clientAuth (none, optional, required): see
Listeners and hosted applications. Each has a tab of its own on
the Listeners page with the policy in force.
The TLS 1.2 cipher list is BCP 195 by default (tls.ciphers, the TLS 1.2
list alone since #423). TLS 1.3’s suites come
first, and TLS 1.2 is limited to the four ECDHE AES-GCM suites RFC 9325
section 4.2 recommends. The server’s order wins, so a client that speaks TLS
1.3 gets it. This is what the FAPI 2.0 Security Profile requires of a server
(section 5.2.2), and it is the default for every listener, not only in a
FAPI realm: a cipher suite belongs to the socket, not to a realm.
tls.minVersion=TLSv1.3 requires TLS 1.3 alone.
The key exchange is post-quantum first (tls.groups, #212). The three
hybrid groups OpenSSL 3.5 implements — X25519MLKEM768, SecP256r1MLKEM768 and
SecP384r1MLKEM1024 — form the first tuple, X25519 and P-256 the second, X448,
P-384 and P-521 the third. A client that supports a hybrid but sent only an
X25519 key share is asked, with a HelloRetryRequest, for the hybrid one. The
finite-field groups are not offered. TLS 1.2 never negotiates a hybrid (they
are TLS 1.3 groups), and uses the curves in the same order.
The signature algorithms leave out DSA and SHA-224 (tls.signatureAlgorithms,
#212). OpenSSL’s default list advertised both in every TLS 1.2
CertificateRequest, and with them a dss_sign certificate type — an
invitation to answer the main port’s certificate request with a DSA
certificate, an algorithm FIPS 186-5 no longer approves for signing.
A client certificate on a curve outside the NIST set is refused (#212).
Certificates whose EC key is on a curve other than P-256/P-384/P-521 (and the
other NIST-named curves) are refused before any certificate object is built (a
third-party runtime defect found by #212; details are held privately by the
maintainer). The rule covers the whole certificate CHAIN, not only the leaf:
every listener that asks for a certificate — the main port and the debugger’s
— closes such a connection (STS-TLS-0035), whatever
tls.signatureAlgorithms says. Separately, brainpool is omitted from the
offered signature schemes by policy.
Warning. Emptying
tls.groupsortls.signatureAlgorithmsrestores node’s and OpenSSL’s defaults, with the finite-field groups, one hybrid group of three, and DSA and SHA-224 back in the lists above.
Warning. An empty
tls.ciphersmeans node’s own list, and any other value replaces BCP 195’s. Either can allow CBC-mode and non-forward-secret suites that BCP 195 recommends against, and a FAPI 2.0 deployment then no longer meets section 5.2.2. Widen it only to test an old client.
The server certificate
- Issued under this service’s Root CA, through a process Intermediate and a TLS Issuing CA rather than any one realm’s, because the sockets that present it are shared by every realm. The chain (leaf, Issuing CA, Intermediate) goes on the wire, so a client that holds only the Root can build a path.
- One anchor covers the main port, LDAPS 636, the debugger listener and every token this service signs. In development mode the hierarchy is rebuilt at every start; where the keystore persists, it survives a restart. It is not a file in the image or the repository, because a certificate committed to a repository is a private key committed to a repository.
GET /tls/server-certificatepublishes the leaf (first), the chain and the Root — everything a client needs to build a truststore, and never a private key. It is servedCache-Control: no-store, since a cached copy outlives the key it describes. A truststore holding only the leaf builds no path, and fails withunable to get local issuer certificateabout a Root it was never given. If the Root is rebuilt (build-rooton/admin/pki), every socket is re-keyed onto the new hierarchy for the next handshake.- LDAPS presents the same certificate and key, not a second pair, so one
fetch is one anchor for
https://andldaps://; two key pairs would make anldapsearchfail against a truststore built for the HTTPS port with the sameunable to get local issuer certificate, which names nothing. The private key is held in memory by the process and nothing writes it to a response. - Names and addresses:
tls.hostnames(localhost,sts,sts-mock,sts.example.com) andtls.ips(127.0.0.1) go into the subjectAltName; the CN is the first host name. - A certificate somebody else issued: set
tls.certificateFileandtls.keyFiletogether (one alone is refused at startup). The file may be a chain, leaf first, and all of it is sent. A supplied certificate is never re-issued under this service’s Root. - A random 128-bit serial, so a browser that trusted a previous start’s
certificate does not meet
SEC_ERROR_REUSED_ISSUER_AND_SERIAL. - The key is kept across restarts, per node, where minted state is. In
product mode on postgres, and in a cluster, each node makes its listener key
once and keeps it in the database, encrypted under the key-encryption key
like every other stored secret, under its node name (
cluster.nodeName, or the host name;STS_CLUSTER_NODE_NAME). A node never holds another node’s key. A restart presents the same key and, while it is still current, the same certificate. The certificate is re-issued over the same key when the Root or the TLS Issuing CA is rebuilt, whentls.hostnamesortls.ipschange, and when less than a third of its validity is left. A new key is made when the database volume is wiped, when the node is renamed, whentls.selfSignedKeyBitsortls.certificateAlgorithmschanges the key, and at every start in development,memoryorldifmode. Give every node a name of its own: two nodes with one name would share a listener key. - A changed certificate is announced over Shared Signals. A receiver
subscribed to
tls-certificate-changedis told once the port is bound (reason: restarted) when a start presents a certificate other than the one last announced, and whenever the certificate is re-issued while the service runs. The last certificate announced is kept in the store, so this works only where minted state survives a restart (product mode on postgres, a cluster). In a cluster a node’s start is announced whenever another node announced after it, because each node has its own listener key. Pin the Root, not the leaf. Shared Signals has the event.
When a browser refuses the certificate
A browser trusts this service’s certificate only once the service’s Root CA is in its trust store. Until then it refuses the certificate during the handshake, and the service logs one line per refused connection:
[STS-TLS-0034] tls: the client at 172.29.0.1 REFUSED this service's certificate on the main port (8081) (it sent the TLS alert certificate_unknown, 46). …
(unknown_ca, 48, from OpenSSL and curl; certificate_unknown, 46, from
Chrome.) Because browsers open several connections at once, expect a few of
these per page load. To trust the Root:
curl -k https://localhost:8081/tls/server-certificate > sts-chain.pem # leaf, chain, Root — the Root is LAST
# Chrome and Chromium on Linux read the NSS database:
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "iya-sts Root" -i sts-root.pem
Save the last certificate in sts-chain.pem as sts-root.pem first. Or
import it under chrome://settings/certificates → Authorities. Reach the
service by a name the certificate carries (tls.hostnames, tls.ips); a
laptop’s host name or LAN address fails as a name mismatch instead. In
development mode the Root is rebuilt at every start, so re-import after a
restart; in product mode it survives restarts, but not down -v or a
build-root.
STS-TLS-0021 is every OTHER failed handshake: a version or cipher
mismatch, or a client not speaking TLS.
Post-quantum server certificates
tls.certificateAlgorithms is rsa by default and accepts ml-dsa-44,
ml-dsa-65 and ml-dsa-87 beside it. More than one is the useful setting:
with rsa,ml-dsa-65, OpenSSL serves whichever certificate matches the signature
algorithms the client offered, so an ordinary client gets RSA and a
post-quantum one gets ML-DSA (RFC 9881)
over the same port — how a migration actually runs. Each ML-DSA certificate is
also a leaf of the TLS Issuing CA.
- ML-DSA needs node 24 (OpenSSL 3.5), which the image uses; on an older runtime the algorithm is skipped with a warning and RSA is served.
GET /tls/server-certificatereturns every certificate; a truststore built from the first alone may not verify the connection a client actually gets.- LDAPS on 636 serves the first certificate only.
- Nothing reports the post-quantum posture of a connection’s key exchange any
more;
GET /tls/server-certificateand/admin/crypto-metadatalist the certificates.
Client certificates on the main port
The port is bound asking for a certificate and accepting a connection without
one (requestCert: true, rejectUnauthorized: false), so presenting one is the
client’s decision and mutual TLS happens where every other protocol already
arrives. What a certificate is worth is decided where it is used:
| Where | What it takes |
|---|---|
GET /tls/sign-in and the sign-in screen |
a certificate that verified starts a sign-on session (below) |
| the token endpoint | RFC 8705: tls_client_auth and self_signed_tls_client_auth authenticate a client, and a token is bound to whatever certificate the connection carried |
/xacml/* and POST /xacml/pip |
a verified certificate whose entry holds REMOTE_PEPS or XACML_USER |
/scim/v2 |
RFC 7644 section 2’s client-certificate scheme |
| Shared Signals, WS-Trust, LDAPS (SASL EXTERNAL) | a verified certificate as the receiver’s application, the requester, or the bound person |
Every door except the token endpoint (and GNAP’s key proof, which reads a
certificate as a key) maps a certificate to one directory entry the same
way: a certificate this service issued names its person or application in a
urn:sts:person: / urn:sts:application: subjectAltName (urn:sts:sa: for a
service account, which is a person), and a certificate
from an outside certificate authority is the entry it is stored on — see
A certificate from an outside certificate authority.
The token endpoint keeps the client’s registered RFC 8705 metadata
(tls_client_auth_subject_dn and the SAN members).
Presenting a certificate anywhere else signs nobody in, and does nothing at all at a route that reads no certificate.
Monitoring → TLS connection (/admin/tls-connection, Admin Read, in both
modes) shows what this service saw of a request: the TLS version and cipher,
the client certificate the connection presented — whether it verified against
the truststore and OpenSSL’s reason if not, what the identity gate makes of
it, its revocation verdict — and every forwarding header with what was
believed of it. Its data is GET /admin-api/tls-connection, which describes
the request that called it. The request the console page describes is its
own call to that operation, made after the page loaded, not the page load
itself: the console is a static application, so the view is a second request
on whatever connection the browser chose (usually the same one, and for these
facts the same answer — a client certificate belongs to the connection, and a
proxy writes the same headers on every request it relays). It starts no
session and changes nothing. It replaced the development pages GET /tls and
GET /tls/forwarded (#597).
What happens to a certificate that is presented:
- The handshake always completes. A certificate that verifies against the truststore is known; one that chains to nothing still completes the handshake and can still bind a token under RFC 8705 section 3.
- It is refused where it is used: RFC 8705 client authentication at the
token endpoint,
/xacml,/scim/v2,/tls/sign-inand a GNAP key proved by mutual TLS undergnap.mtlsTrust=pki(GNAP) each decide for themselves, carrying OpenSSL’s own reason (authorizationError) out whole. - A verified certificate this service issued is recorded as an
authentication when the connection is established — once per connection,
not per request — under protocol
TLSon/admin/users(see Recording a verified certificate below). One from an outside authority is not: a handshake has no realm to look its entry up in, so it is recorded by the door that signs its holder in. - A certificate is never read from a forwarded header (
X-Client-Certand its relatives) in any mode. Behind a balancer, TLS has to be passed through. - A handshake that fails is logged, with OpenSSL’s own reason
(
tlsClientError), and recorded as a refusal on the audit log. Such a handshake never reaches a handler, so without that it is invisible from both ends: the caller sees a closed socket and the server says nothing. On this port a client certificate is never required, so what lands there is a broken handshake rather than a refused credential.
Recording a verified certificate
/admin/users answers “who has this service seen, in an interaction that
succeeded”, and a mutual-TLS client whose certificate verified is exactly that.
So when a handshake completes with a certificate this service issued that
verified, its subject is filed through the same authentication record every
other family uses, under protocol TLS, on the entry of the person it names.
It is a record of what happened, not a credential: nothing consults the
record to decide anything (/tls/sign-in is what signs somebody in). No
entry is created from a certificate — not for one this service issued,
whose person already has one, and never for one from an outside authority.
- It is recorded at the handshake, not per request. The handshake is where the credential was accepted, so a connection carrying six requests is one authentication, and a client that opens six connections presented its certificate six times.
- It is recorded only when the certificate verified; nothing is written for a certificate that failed or was never sent.
- The identity is the subject in RFC 4514 form — leaf first, no spaces after
the commas, values escaped. That is a different string from the display DN
shown beside it and from the one
openssl x509 -subjectprints.
No entry is seeded from a certificate any more (#1061). Until then a
certificate from an outside authority made an entry named by its CN
(cn=alice,ou=users,…) and was filed under it; that name was chosen by
whoever ran the authority, so it is no longer read at all. Entries made that
way are left as they are, and sign nobody in unless the certificate is stored
on them.
A certificate from an outside certificate authority
A certificate that chains to an anchor in the truststore below — not to this
service’s own Root — is an identity only while it is stored, byte for byte,
in userCertificate (RFC 4523) on exactly one entry of the realm the request
is in. Every door that reads a certificate as a person or an application asks
the same question: GET /tls/sign-in, the sign-in screen’s Continue with
your certificate, SCIM’s client-certificate scheme, the XACML gates and the
remote PEP endpoints, Shared Signals, WS-Trust and LDAP SASL EXTERNAL.
- It is never matched by its common name or subject, and no entry is created for it.
- Stored on no entry, or on more than one, it signs nobody in. Each
door refuses it with a code of its own:
STS-TLS-0054/0055at/tls/sign-in,STS-AUTHN-0468/0469on the sign-in screen,STS-SCIM-0084/0085,STS-XACML-0177–0180,STS-SSF-0151/0152,STS-WSTRUST-0038/0039andSTS-LDAP-0192/0193(Error codes). - It must still verify against the truststore and pass the revocation check below; storing it does not replace either.
- A renewed certificate is a different certificate: store the new one (the old one can stay on the entry until it expires, then be removed).
- The match is by the SHA-256 of the certificate’s DER, looked up in an index, so it costs the same with a million people as with ten.
Storing one. Store the leaf (only the leaf — its issuing authority goes in the truststore) on the person’s or the application’s entry:
- the console: Users → the person → Stored certificates, paste the PEM, Store; Remove beside a stored one takes it off;
- the management API:
POST /admin-api/users/add-certificate{"user":"alice","certificate":"-----BEGIN CERTIFICATE-----…"},POST /admin-api/users/remove-certificate{"user":"alice","sha256":"…"}, andGET /admin-api/users/certificates?user=aliceto list them; - for an application: the console’s Applications → the application →
Credentials → Stored certificates, and
POST /admin-api/applications/add-certificate{"application":"my-ssf-receiver","certificate":"-----BEGIN CERTIFICATE-----…"},POST /admin-api/applications/remove-certificate{"application":"my-ssf-receiver","sha256":"…"}, with the list undercredentials.storedofGET /admin-api/applications?application=…; - LDAP: a modify adding
userCertificate;binaryto the entry, under product mode’s write authorization (LDAP).
The console and the API refuse a certificate that is not one X.509 certificate
(STS-ADMIN-0897), a person with no entry (STS-ADMIN-0898), an application
the registry does not hold (STS-ADMIN-0906), a certificate already stored on
another entry (STS-ADMIN-0899), and removing one the entry does not store
(STS-ADMIN-0900). A certificate stored on an application’s entry is how a
Shared Signals receiver or a SCIM client is authenticated by an outside
certificate. SCIM does not write it: its
x509Certificates member is not published (SCIM).
Upgrading a deployment. Before upgrading a deployment that signs people in with certificates from an outside authority — the remote XACML PEP is one — store each of those certificates on its entry. Until it is stored, the certificate is refused at every door; nothing migrates them, because which entry a certificate belongs to is the decision the old common-name match made on the operator’s behalf.
The client truststore
The anchors client certificates are verified against. It starts empty and is filled from three places:
| Source | When | Survives a restart? |
|---|---|---|
tls.trustAnchorsFile |
read at startup; the product-mode way to fill it | yes — the file brings it back |
/admin/tls/trust, POST /admin-api/tls/trust/{add,remove} |
at runtime, in both modes, gated by the console / an admin token | yes — written to the directory (ou=trustAnchors in the default realm) and restored before any listener binds |
| this service’s own Root CA | always, while tls.trustIssuedClientCertificates is on |
— |
The gated doors are strict: a bundle with one block that cannot be read is
refused whole. There is no bulk clear on them — removing is one row at a
time — and removing an anchor from the file lasts only until the next start.
The console page needs Admin Write to change anything, and the API needs an
admin:write token (admin:read to list). An anchor added in one process
reaches the others through the directory; with request workers, both doors are
answered by the front process, which is the one that holds the listener.
Under paranoid PKI mode, on by default in product
mode, the gated doors and the file also hold each block to the admission rule of
the signer truststore: a self-signed
CA is an anchor, another CA must chain to something held, and a leaf is refused.
An anchor already stored that the rule now refuses is kept, flagged on the page and
logged once (STS-TLS-0056). A block of the file it refuses is left out
(STS-TLS-0057). This truststore is for TLS handshakes; for everything else see
the signer truststore.
Under paranoid PKI mode a server this service dials may not present a self-signed certificate until it is accepted by name, or configured as that dialer’s own CA. A private CA is reached by naming it in the dialer’s CA file as before: if its certificates name no revocation source, there is no check to perform.
Under paranoid PKI mode a client certificate is also held to more than OpenSSL’s
answer on the main port, custom listeners, LDAPS and the debugger: the leaf is not a CA, its keyUsage and extendedKeyUsage
fit client authentication, revocation is consulted before the connection is read, a
failure inside the check refuses, and a resumed session keeps what its full handshake
concluded. A certificate that fails is treated as unverified rather than breaking the
handshake. See the tls-client row of the use cases. A registered
self_signed_tls_client_auth certificate is held to its validity and keyUsage too,
while equality stays the method (tls-client-self-signed). The channel between cells
asks the same of the leaf under a row of its own, cell-peer, and consults this
service’s own register for revocation.
A TLS handshake has no realm in it, so a realm’s own rows mostly do not decide it. The path that names a realm arrives after the handshake is over, so which realm’s setting applies depends on the listener:
| Where a client certificate arrives | Whose settings decide |
|---|---|
| The main port, a custom listener, LDAPS, the debugger listener | The default realm’s pki.paranoid and pki.paranoidTlsClient, whichever realm the request later names |
| The channel between cells | pki.paranoid and pki.paranoidCellPeer, read outside any realm |
A use case decided on a request, such as tls-client-self-signed |
The realm of that request |
So setting pki.paranoid or pki.paranoidTlsClient in another realm changes nothing
at these handshakes, in either direction: it neither turns the hold on for that realm
nor weakens it. To change them, change the default realm’s rows.
SPIFFE’s gRPC sockets belong to one realm each, told apart by address. There, the
realm’s own pki.paranoid and pki.paranoidTlsClient decide one thing: whether the
SPIRE Server API may bind in plain text when it could not be given a TLS identity.
They add no check to each connection there: those sockets verify a caller’s SVID
themselves, as SPIFFE describes.
Why it starts empty. The certificate authority whose clients it verifies is
often generated in somebody’s browser minutes before the connection, and
exists nowhere else, so no configuration file could hold it and no image could
bake it in. POST /admin-api/tls/trust/add takes one or more PEM certificates
and applies them to the listener; existing connections keep the truststore
they were made under, and the next handshake is judged against the new one.
The open POST /tls/trust and POST /tls/trust/clear that did this without a
credential in development were deleted (#597).
“Empty” is meant literally: node’s bundled public root store is not used,
since a public root has no business verifying a client certificate from a
private CA, so the starting state is “nothing verifies”. With HTTPS on, the
first call to /admin-api is made with verification off, as the first fetch of
the server certificate is.
The service Root in the truststore lets a person present the TLS client
certificate they issued themselves on /portal/signing-key. Every key pair this
service issues chains to the same Root, so the chain alone is not an identity:
only a leaf from a TLS client Issuing CA with clientAuth signs anybody in.
Signing in with a certificate: GET /tls/sign-in
In product mode a browser must reach this address as a page: typed by the
person, or by a link on this same origin. A link from another site, a frame or
an image gets 403. A program such as curl sends no Sec-Fetch-* headers and is
not affected.
A request with a verified certificate starts a sign-on session — the same session the password screen, the KDC and the SAML profiles start, so the holder is signed in to every surface on the port. In order:
- revocation is consulted (below); a refused certificate starts no session and is not recorded as an authentication;
- the identity gate: a certificate this service issued must come from a TLS
client Issuing CA; anything else issued here is reported as
refusedAsIdentity; - an application’s certificate signs nobody in — it is an RFC 8705 client
credential, reported as
session.application; - the session starts in the certificate’s realm: for a certificate this
service issued, the realm whose Issuing CA signed it and the person it names;
for one from an anchor somebody installed, the realm of the request
(
/realm/<id>/tls/sign-in, else the default realm) and the person whose entry stores it — refused, withsession.refusedAsStored, when no entry or several do (above); - in product mode, a person who owes a second factor is not signed in here
(
STS-TLS-0060), because this address cannot ask for one. The answer says to sign in on the sign-in screen and choose the certificate there, which asks for the second factor. A program presenting a certificate elsewhere (WS-Trust, token exchange, RFC 8705, LDAP SASL EXTERNAL, PKINIT) is not affected.
The answer is JSON: signedIn, the session, whether a certificate was
presented and verified, the x5t#S256 thumbprint the token endpoint would bind
a token to, and the revocation verdict. A caller that presents no certificate is
simply not signed in, and the answer says so. The session carries
amr ["swk"] (a software key) and acr "1". A browser that already holds a
session keeps it and starts no second one.
Why a client needs this answer. A client knows what it sent. What it cannot
see is which chain the server built out of it, which anchor it verified against,
or whether the certificate was accepted at all. Under TLS 1.3 it has not
even been told: the client sends its Certificate and Finished last, so its
handshake is complete before the server has said anything, and the verdict
arrives afterwards — as a post-handshake alert, or as a bare hang-up, which is
what node’s own TLS server does. GET /tls/sign-in answers the one question of
that family this service answers: did my certificate arrive, and as what.
Revocation is consulted
A presented certificate is checked for revocation under pki.revocationCheck
before it is used — at /tls/sign-in, when the connection is recorded, and by
every door that turns a certificate into an identity. A certificate this service
issued is looked up in its own register; one from another authority is checked
with the OCSP responder and the CRLs it names, so a first request can wait on
those fetches (each bounded by pki.revocationFetchTimeoutMs, then cached).
It is not done at the handshake: OpenSSL’s CRL check would demand a list for every issuer and fetches nothing. So the handshake completes, and the session, the recorded identity and the request are what get refused. See PKI.
Reverse proxies and load balancers
- L7 (TLS-terminating) proxy:
global.trustProxybelievesX-Forwarded-ProtoandX-Forwarded-Host, andglobal.trustedProxiesnarrows that to the proxy’s own addresses. In product mode, withglobal.trustedProxiesempty, no caller’sX-Forwarded-*headers are believed: the client’s address is the connection’s, and the scheme and host are the request’s own. Set it to your proxy’s addresses. Monitoring → TLS connection shows what a request carried and what was believed. A client certificate cannot cross such a proxy. - L4 load balancer with TLS passthrough — the supported front for client
certificates:
global.proxyProtocol=v2reads a HAProxy PROXY protocol v2 header before TLS on every TCP listener (the main port, LDAP 389 and LDAPS 636, the KDC’s TCP 88, the debugger and the revocation listener), so the client’s address is known and mutual TLS still terminates on the node. A connection from outsideglobal.trustedProxiesis closed, except one from this host. Behind an L4 load balancer has the AWS NLB recipe.
Not implemented
- Refusing an unverified client certificate at the handshake. Refusing
there is a property of a socket, and the main port carries every protocol:
rejectUnauthorized: truewould refuse every caller that presents no certificate, which is almost all of them. A certificate that does not verify is refused at the doors that use it — the same answer, one layer up. What is lost is the proof that a certificate was acceptable before any handler ran, and with it the chance to exercise a client’s own mutual-authentication verdicts against a server that insists:required, andrequired-and-rejected(the case an operator hits most). Onlynot-required, the main port’s posture, is reachable here. - A connection report for anybody. What the server made of a request’s
connection (what TLS negotiated, the client certificate as presented) is
reported only to an administrator, by Monitoring → TLS connection and
GET /admin-api/tls-connection(above). - Separate TLS ports. There is no
tls.portortls.mutualPort; a deployment that setsSTS_TLS_PORTorSTS_MTLS_PORTgets an “unknown setting” warning at startup rather than a silent no-op. - Client certificates on LDAPS by default. Port 636 asks for none until
ldap.ldapsDisableOptionalClientCertificateis turned off (see The listeners above). Once it asks, a person’s certificate binds an LDAP connection with SASL EXTERNAL — one this service issued, or one from an outside certificate authority stored on that person’s entry (LDAP, Binding with a client certificate).
Development and product mode
| Development | Product | |
|---|---|---|
Revocation (pki.revocationCheck=auto) |
soft-fail: revoked is refused, an undeterminable status is accepted and reported | hard-fail: an undeterminable status is refused too |
| Which realm’s mode decides the truststore | the default realm’s, because the anchors are one list for the whole process | the same |
Everything else — the certificate, the sign-in order, the identity gate, the refusal of an application’s certificate — is the same in both modes. See What is not checked.
Configuration
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
global.https |
STS_HTTPS |
on when oauth2.rfc9700 or oauth2.oauth21 is (every shipped appconfig sets it on) |
no | Serve the main port over HTTPS with the shared certificate, asking for a client certificate and requiring none. |
tls.hostnames |
STS_TLS_HOSTNAMES |
localhost,sts,sts-mock,sts.example.com |
no | The subjectAltName DNS entries of the shared certificate. |
tls.ips |
STS_TLS_IPS |
127.0.0.1 |
no | The subjectAltName IP entries. |
tls.certificateAlgorithms |
STS_TLS_CERT_ALGS |
rsa |
no | Which server certificates to present: rsa and any of ml-dsa-44, ml-dsa-65, ml-dsa-87. |
tls.certificateFile |
STS_TLS_CERT_FILE |
(empty) | no | Serve a certificate (or chain) somebody else issued; set with tls.keyFile. |
tls.keyFile |
STS_TLS_KEY_FILE |
(empty) | no | The unencrypted PKCS#8 or PKCS#1 key for tls.certificateFile. |
tls.minVersion |
STS_TLS_MIN_VERSION |
TLSv1.2 |
no | The lowest TLS version the main port and LDAPS negotiate. |
tls.ciphers |
STS_TLS_CIPHERS |
BCP 195: ECDHE-{ECDSA,RSA}-AES{128,256}-GCM-SHA{256,384} |
no | The TLS 1.2 cipher list for those sockets, in the server’s order; empty means node’s own TLS 1.2 list (see the warning above). A TLS 1.3 name is refused (tls.tls13CipherSuites). One matching nothing stops startup. |
tls.disableTls12, tls.tls13CipherSuites, tls.pqcOnly and the client-certificate pairs |
see The listeners above | yes | Server configuration → Listeners. | |
tls.groups |
STS_TLS_GROUPS |
X25519MLKEM768:SecP256r1MLKEM768:SecP384r1MLKEM1024 / X25519:P-256 / X448:P-384:P-521 |
no | The key-exchange groups, post-quantum hybrids first (see below); empty means node’s auto. |
tls.signatureAlgorithms |
STS_TLS_SIGALGS |
OpenSSL’s list without DSA and SHA-224, brainpool omitted by policy | no | The signature schemes signed with, accepted, and asked for in a CertificateRequest; empty means OpenSSL’s. |
tls.trustAnchorsFile |
STS_TLS_TRUST_ANCHORS_FILE |
(empty) | no | A PEM file of CA certificates client certificates are verified against, loaded at startup; unreadable or empty is fatal. |
tls.trustIssuedClientCertificates |
STS_TLS_TRUST_ISSUED_CLIENT_CERTIFICATES |
true |
no | Add this service’s Root to the client truststore, so a certificate a person issued on the portal signs them in. |
tls.selfSignedKeyBits |
STS_TLS_SELF_SIGNED_KEY_BITS |
2048 (3072 in product) |
no | The RSA key size of the listener certificate made at startup. |
tls.selfSignedValidityYears |
STS_TLS_SELF_SIGNED_YEARS |
2 |
no | How long that certificate is valid. |
tls.selfSignedOrganization |
STS_TLS_SELF_SIGNED_ORGANIZATION |
iya-sts |
no | The O= of its subject. |
tls.sessionTicketRotationS |
STS_TLS_SESSION_TICKET_ROTATION_S |
3600 |
yes | In an active-active cluster, how often the session-ticket key every node’s LDAPS listener and main port share is replaced (the old key is deleted); 0 shares nothing. Outside active-active nothing is shared. |
tls.mainPortSharedTickets |
STS_TLS_MAIN_PORT_SHARED_TICKETS |
true |
no | The main port seals its session tickets under the cluster’s shared key, so a session resumes on any node. false keeps a key per node. |
tls.sessionTimeoutS |
STS_TLS_SESSION_TIMEOUT_S |
300 |
yes | How long a TLS session may be resumed, on every TLS listener that does not set its own (listener<Id>.sessionTimeoutS; -1 inherits). It was tls.mainSessionTimeoutS, the main port’s alone, until #429. |
tls.sessionCacheSize |
STS_TLS_SESSION_CACHE_SIZE |
2048 |
yes | How many TLS 1.2 session IDs a listener keeps for resumption; 0 keeps none and resumes by ticket only. Per listener as listener<Id>.sessionCacheSize. Not on the SPIFFE listeners: grpc-js offers no session-ID cache. A TLS 1.2 session, by ID or by ticket, is resumed only under the server name it was made under (RFC 6066 section 3): a session ID offered under another name gets a full handshake, and a ticket offered under another name is accepted by OpenSSL and the connection then closed, so the client’s next connection is a full handshake. A TLS 1.3 ticket is the client’s to use under one name (RFC 8446 section 4.6.1). |
tls.resumedChainWaitMs |
STS_TLS_RESUMED_CHAIN_WAIT_MS |
2000 |
yes | How long a request on a session resumed from another node waits for that session’s client-certificate chain to replicate; 0 never waits. |
http.keepAliveTimeoutS |
STS_HTTP_KEEP_ALIVE_TIMEOUT_S |
60 |
yes | How long an HTTP listener keeps an idle connection for the next request — an HTTP/1.1 one between requests, an HTTP/2 one with no frame passing, which is closed with a GOAWAY; pipelined requests are answered in order. It was global.httpKeepAliveTimeoutS, the main port’s alone, until #429. |
http.headersTimeoutS |
STS_HTTP_HEADERS_TIMEOUT_S |
0 |
yes | How long a request’s headers may take to arrive; 0 is the keep-alive timeout plus one second, and a value at or below the keep-alive is raised to that. |
http.maxRequestsPerSocket |
STS_HTTP_MAX_REQUESTS_PER_SOCKET |
0 |
yes | How many requests one connection may carry before it is closed; 0 is no limit. An HTTP/2 connection is sent a GOAWAY after its last. |
http.maxConnections |
STS_HTTP_MAX_CONNECTIONS |
0 |
yes | How many connections an HTTP listener holds at once; 0 is no limit. |
http.http2MaxConcurrentStreams |
STS_HTTP_HTTP2_MAX_CONCURRENT_STREAMS |
100 |
yes | How many streams (requests) one HTTP/2 connection may have open at once; a stream past it is refused (REFUSED_STREAM). Node’s own is unbounded. Per listener as listener<Id>.http2MaxConcurrentStreams and a custom listener’s tls.http2MaxConcurrentStreams. |
global.trustProxy |
STS_TRUST_PROXY |
false |
yes | Believe X-Forwarded-Proto and X-Forwarded-Host from a TLS-terminating proxy. |
global.trustedProxies |
STS_TRUSTED_PROXIES |
(empty) | yes | The addresses or CIDRs forwarded headers — and PROXY protocol headers — are believed from. Empty believes forwarded headers from any caller in development and from none in product. |
security.hstsIncludeSubDomains |
STS_SECURITY_HSTS_INCLUDE_SUBDOMAINS |
false (true in product) |
yes | Adds includeSubDomains to Strict-Transport-Security, which only product mode sends. |
global.proxyProtocol |
STS_PROXY_PROTOCOL |
off |
no | v2 expects a PROXY protocol v2 header on every TCP listener, read before TLS. |
global.proxyProtocolTimeoutMs |
STS_PROXY_PROTOCOL_TIMEOUT_MS |
30000 |
yes | How long a trusted proxy may take to send a complete header. |
pki.revocationCheck |
STS_PKI_REVOCATION_CHECK |
auto |
yes | Whether a presented certificate is checked for revocation: off, soft-fail, hard-fail, or auto (hard in product, soft in development). |
pki.revocationRequireDistributionPoint |
STS_PKI_REVOCATION_REQUIRE_DISTRIBUTION_POINT |
auto |
yes | Under hard-fail, whether a CA-issued foreign certificate that names no CRL and no OCSP responder is refused: auto in product mode, on in both; off accepts certificates nobody can ever revoke. |
pki.revocationFetchTimeoutMs |
STS_PKI_REVOCATION_FETCH_TIMEOUT_MS |
3000 |
yes | How long a fetch of a foreign CRL may take; a request waits on it the first time. |
The remaining pki.revocation* settings tune OCSP, CRL caching and LDAP
distribution points; they are on /admin/pki and in
Every setting. This table is a copy of rows in common/config.js; the live source is
/admin/listeners and GET /admin-api/config.
See Configuration for how a value is resolved and where it
is changed: on Server configuration → Listeners (/admin/listeners, or
/admin/config for global.*), through
POST /admin-api/config/set, or in an appconfig file.
Product mode and the main port
Product mode serves its main port over TLS only: with global.https off the
process does not start. The plain-HTTP revocation and SCEP listener stays,
because RFC 5280, RFC 5019 and RFC 8894 expect it there.
Set tls.certificateFile to a publicly trusted chain before people use a
product deployment. A certificate this service minted does not stop it starting,
so a new install still works, but it does not meet ASVS 5.0.0 requirement 12.2.2
and /admin/mode says so.
Strict-Transport-Security
In product mode, every response that arrives over TLS carries
Strict-Transport-Security: max-age=31536000; includeSubDomains. It applies to
the whole host name, every port included, and to every subdomain of it. Turn off
security.hstsIncludeSubDomains if a subdomain must still answer over plain
HTTP; the header then carries max-age alone. A browser that has seen the
header refuses an untrusted certificate with no way to click through, so give
the service a certificate browsers trust before people use it in product mode. The plain-HTTP revocation
and SCEP listener never sends the header. Development mode does not send it.
Design decisions
- Ask for a certificate, require none. RFC 8705 needs a certificate asked for on the port where tokens are issued, and every other protocol answers on that same port; requiring one would refuse almost every caller.
- A certificate is refused where it is used, not at the handshake. A handshake refusal is a property of the whole socket; each door that turns a certificate into an identity refuses it instead, with the reason.
- A verified certificate is a sign-in, but only when asked. It was once a side effect of reaching a listener; a sign-in that happens because somebody loaded a page is one nobody asked for, so it is a route of its own.
- One certificate, one anchor, every socket. The main port, LDAPS and the debugger share one certificate under one Root, so a caller trusts this service once rather than three times.
- The certificate is under a process Intermediate, not a realm’s. One realm’s authority signing the front door every realm uses would be that realm vouching for all the others.
- Revocation is checked before a session starts, not at the handshake. OpenSSL’s handshake CRL check demands a list for every issuer and fetches nothing; checking after the handshake lets foreign certificates be checked by OCSP and fetched CRLs.
- The chain alone is not an identity. Every key pair this service issues chains to its Root; only a TLS client certificate, and never an application’s, signs a person in.
- The test-control truststore is closed in product mode. An anchor anybody can add is a client certificate anybody can make verify, and anchors decide who a remote PEP or a SCIM caller is; product fills it from a file or through the gated doors.
- No bulk clear on the gated doors. A clear reaches every client certificate every other caller relies on.
- No certificate is ever read from a header. A forwarded certificate is one anybody can forge, so client certificates require TLS passthrough.
- One LDAPS session-ticket key for the whole cluster, and none outside
one. Behind a balancer that picks a node per connection, a ticket sealed
under one node’s own key cannot be opened on the other, so resumption
worked about half the time. In active-active mode the nodes’ LDAPS
listeners share one key, kept
sealed in the store and replaced every
tls.sessionTicketRotationSby thetls.ticket-key-rotatejob; the old key is deleted, which bounds how long a resumed session’s secrets can be recovered from a captured ticket. Anywhere else each listener keeps OpenSSL’s own keys, which never leave the process. Each node still presents its own listener key, so a client that checks a second node’s handshake against the first node’s key fails; resumption does not care. The main port shares the key too since #406 (2026-10-02) (tls.mainPortSharedTickets). It asks for a client certificate, and a resumed session carries only the leaf, so the chain the full handshake verified is replicated to every node (tls.presentedChains) and a request on a session resumed elsewhere waits up totls.resumedChainWaitMsfor it before its revocation check. The debugger’s listener still keeps a key per node. - The main port keeps connections and sessions for 60 seconds (#406).
A browser holding a client certificate under one of the CAs the main port
names is asked by Firefox whether to send it on every FULL handshake; a
resumed session carries no CertificateRequest. With node’s five-second
keep-alive and a ticket key per node, a person clicking through the
console or the portal behind a balancer was asked on nearly every click.
http.keepAliveTimeoutSkeeps an idle HTTP/1.1 connection 60 seconds (pipelined requests are answered in order),tls.sessionTimeoutSlets a session resume for 300 seconds, and the shared key lets it resume on any node. Keep a load balancer’s idle timeout above the keep-alive (an AWS NLB’s is 350 seconds). - Every HTTPS listener speaks HTTP/2 as well as HTTP/1.1 (#407) — the
main port, the protocol debugger’s and each custom listener. ALPN chooses
per connection: a client that offers
h2gets HTTP/2, and one TLS connection carries every request a browser makes in parallel; a client that offers onlyhttp/1.1is answered exactly as before. A client certificate is asked for and bound the same way over either. It is on by default and can be turned off:http.http2for every listener (Server configuration → HTTP connections),listenerMain.http2orlistenerDebugger.http2for one, andtls.http2in a custom listener’s definition. A change reaches the next connection at once; an open one keeps the protocol it chose. An HTTP/2 connection is held to the same bounds as an HTTP/1.1 one: it closes when idle for the keep-alive timeout, is sent a GOAWAY afterhttp.maxRequestsPerSocketrequests, and may have at mosthttp.http2MaxConcurrentStreams(100) open at once. A request whose:authorityandHostname different hosts is refused 400 (RFC 9113 section 8.3.1). Off, a client that offers onlyh2is refused in the handshake (no_application_protocol). A load balancer that terminates TLS speaks to a listener in whatever protocol it is configured to; one that passes TCP through (an NLB) leaves the choice to the client. - The serial is random. A constant serial made Firefox refuse the port after a restart with an error no “accept the risk” could get past.
In the running service
- Protocols → TLS / mutual TLS (
/admin/tls): the certificate the main port and LDAPS present and what the service does with a client certificate. Thetls.*settings are on Server configuration → Listeners (/admin/listeners). Whether the port is HTTPS at all isglobal.httpson/admin/config. - Protocols → Client-certificate truststore (
/admin/tls/trust): every anchor with subject, issuer, serial, validity, SHA-256 fingerprint and source (fileorruntime), an add form, and a Remove per row, in either mode. The service Root added bytls.trustIssuedClientCertificatesis not listed there. - Monitoring → TLS connection (
/admin/tls-connection): what this service saw of the console’s own request — its connection, its client certificate and its forwarding headers. - Live descriptions:
GET /tls/server-certificate,GET /tls/sign-in. - Related pages:
/admin/crypto-metadatalists every certificate configured;/admin/pkiissues and revokes;/admin/usersshows TLS authentications. - Management API:
GET /admin-api/tls,GET /admin-api/tls/trust,POST /admin-api/tls/trust/{add,remove}andGET /admin-api/tls-connection— see/admin-api/openapi.json. - Failures are recorded under
STS-TLS-NNNN,STS-PKI-NNNNandSTS-PROXY-NNNNcodes — see Error codes.
Related
- OAuth security profiles — RFC 8705 client authentication and certificate-bound tokens
- PKI — the certificate authority and revocation
- Sessions — the session a certificate starts
- Authentication — the other ways to sign in
- SCIM, XACML and Remote PEP — doors that authenticate by client certificate
- LDAP — LDAPS on 636 presents the same certificate
- Trust realms — what a shared socket means for realms
- AWS cluster — the load-balanced deployment
- Configuration —
global.https