SPIFFE

iya-sts is a SPIFFE issuing authority in all three of its server-side shapes: the bundle endpoint over HTTPS, the SPIFFE Workload API over gRPC, and the SPIRE Server API over gRPC. It issues X509-SVIDs and JWT-SVIDs per the SPIFFE specifications (SPIFFE ID, Trust Domain and Bundle, X509-SVID, JWT-SVID, Workload API), and its server API is SPIRE’s own spire-api-sdk protocol. Every trust realm can be a trust domain of its own, with its own authority and its own sockets on an address of its own.

The three have almost nothing in common with each other. The bundle endpoint is one GET returning a JWK Set, and it is the whole of the SPIFFE federation protocol’s server half. The two gRPC surfaces are authenticated in opposite ways, because their specifications demand opposite things (see Authentication on the two gRPC surfaces).

Features

Trust domains and the authority

A realm’s trust domain is the authority part of every SPIFFE ID it mints. The default realm’s is spiffe.trustDomain (example.org). A realm created at runtime gets its own DNS domain as its trust domain, for example iyasec.io, and may name another one outright. Two realms never share a trust domain by default, because two authorities claiming one name make every SVID either one mints ambiguous.

The trust domain is fixed when the realm’s authorities are built. A later change is reported as drift on GET /spiffe and /admin/spiffe, not acted on. To change it, turn the realm’s SPIFFE off and on again, which discards the old authorities.

A realm gets sockets of its own, and it is told apart by ADDRESS. Every other family here learns its realm from a segment at the front of the path; gRPC’s path is the METHOD name, fixed by the Workload API specification, so there is nowhere in the protocol to put one. A realm is created with spiffe.enabled off. Turning it on builds that realm’s authorities and binds a Workload API and a SPIRE Server API of its own, on the address spiffe.grpcHost names for that realm and on the same ports. That is also what a real deployment looks like — one SPIRE server is one trust domain — and it is why docker-compose.yml gives the container four addresses rather than one. Join tokens are per realm for the same reason: a join token is a credential for joining a trust domain.

The X.509 authority is the realm’s SPIFFE Issuing CA in the service’s certificate hierarchy:

Root CA (the service's)          <- what the bundle publishes
└── Intermediate CA (this realm)
     └── SPIFFE Issuing CA       <- signs X509-SVIDs
          ├── X509-SVID
          └── downstream CA      (NewDownstreamX509CA)

This is the arrangement SPIRE has with an UpstreamAuthority configured. A rotation of the Issuing CA leaves the bundle unchanged, because the bundle is the Root. Where no hierarchy exists (pki.autoBuild off, or a Root that could not be built), the realm falls back to a self-signed X.509 authority. That authority’s rotations keep spiffe.retainedAuthorities authorities in the bundle. The JWT authority is always the realm’s own key.

The SPIFFE authority is not the TLS certificate. The certificate LDAPS 636, the embedded debugger’s listener and (under global.https) the main port share is a leaf with CA:FALSE and extKeyUsage serverAuth; it cannot sign anything, and a trust domain’s CA and a host’s TLS identity are two unrelated trust decisions. They share an anchor — the service Root — and not a tree: the SPIFFE Issuing CA is a sibling of the TLS one, with its own key under its own Intermediate, so trust narrowed to SPIFFE alone is still sayable by pinning the SPIFFE Issuing CA instead of the Root. It is the one Issuing CA in the hierarchy with pathLen: 1 rather than 0, because NewDownstreamX509CA asks it for a CA and not a leaf, and the realm Intermediate above it is widened to 2 to match.

The bundle publishes the Root, which is what SPIRE publishes with an UpstreamAuthority plugin, and an X509-SVID carries its Issuing CA and the realm’s Intermediate in its own chain. The authority is per realm and the anchor is not, so every realm’s X.509 bundle is the same document.

Rotation is two different acts. Under the Root, rotating re-issues the SPIFFE Issuing CA and leaves the anchor alone: the bundle does not change, nothing has to be re-fetched, and SVIDs minted under the old authority go on verifying, because their chain still reaches the same Root. On the self-signed fallback (which /admin/spiffe and GET /spiffe report, and which pki.autoBuild: false reaches deliberately) a rotation prepends and never replaces: the new authority signs everything from then on, and the old one stays published, because an SVID minted a minute ago has to go on verifying — dropping it is the difference between a rotation and an outage. Past spiffe.retainedAuthorities the oldest is dropped, which does invalidate whatever it signed, and the page says so.

Both authorities rotate automatically, in both modes. A scheduler job runs every hour. It rotates the X.509 authority once it is past half its lifetime, and the JWT authority once it is older than half spiffe.caTtl. Rotate now on /admin/spiffe rotates either or both by hand. On a cluster, a realm’s authorities are made once and adopted by every node.

X509-SVIDs use EC P-256 by default (spiffe.x509KeyType), which is what SPIRE issues. JWT-SVIDs are signed ES256 by default (spiffe.jwtKeyType). Ed25519 is offered for X.509 only.

The bundle endpoint

GET /spiffe/bundle (spiffe.bundlePath) returns the realm’s trust bundle as a JWK Set, with spiffe_sequence (which changes only when the bundle changes) and spiffe_refresh_hint (spiffe.refreshHint). Every key carries a use of x509-svid (with the certificate in x5c) or jwt-svid. It is served no-store. A real federation partner refuses a plain-HTTP bundle endpoint, so set global.https.

GET /spiffe/federated/{trustDomain} shows a foreign trust domain’s bundle exactly as this realm holds it, so that “the bundle I pushed” and “the bundle workloads are given” can be compared.

The Workload API

The gRPC service SpiffeWorkloadAPI, on:

• a Unix socket at spiffe.workloadSocket, SPIRE’s own default path /tmp/spire-agent/public/api.sock, so SPIFFE_ENDPOINT_SOCKET needs no change for a client that was pointed at a SPIRE agent;
• TCP at spiffe.workloadPort (8092), for a caller in another container. In product mode only where the network authenticates source addresses: see A caller over TCP below.

Five of the specification’s seven methods are implemented:

• FetchX509SVID: X509-SVIDs with their private keys and the bundle;
• FetchX509Bundles and FetchJWTBundles;
• FetchJWTSVID: a JWT-SVID for an audience, which is required;
• ValidateJWTSVID: a real verification, returning the claims.

The two WIT methods are not implemented. No specification defines the token format yet, and inventing one would work here and interoperate with nothing.

The streams stay open. FetchX509SVID and the bundle streams are held for the life of the connection and re-sent at half the shortest SVID lifetime, so a client’s rotation path runs without an hour’s wait. A Workload API that writes once and ends the stream looks completely correct on the first fetch and puts go-spiffe into a reconnect loop, and a client’s rotation handling is the part most worth exercising. A call without the metadata header workload.spiffe.io: true is refused, because the specification requires it (section 3, a hardening measure against server-side request forgery). spiffe.requireSecurityHeader off serves such a call in development mode only (#181); product ignores it and refuses turning it off.

Which entries answer a caller. A caller is given the registration entries whose selectors are a subset of the caller’s selectors, as SPIRE matches them (spiffe.attestWorkloads; turning it off, which hands every caller every entry, is development only). The entry’s selectors must be a subset of the caller’s — not equal to them, and not merely intersecting. A caller that matches no entry gets an empty SVID list, which is what a real agent answers an unregistered workload, and is the only way to exercise a client’s “I have no identity” path — one most client libraries have and almost nobody runs. In development, spiffe.autoCreateEntries instead creates an entry for the caller and issues it an SVID. The invented entry carries the caller’s stable selectors — transport and endpoint, never the peer, whose port is ephemeral — so the next caller of the same shape matches it instead of inventing another.

Sample entries. A development start seeds three registration entries — /workload, /ns/default/sa/web (with DNS names and a hint) and /ns/default/sa/db (with a different hint) — for the same reason the directory seeds three people: a Workload API that answers an empty list teaches a client author nothing, and the first thing they will do is assume they have misconfigured something. The two hints exist so that “more than one SVID came back” is a path a client can actually be driven down. Delete them and they stay deleted until a restart.

Authentication on the two gRPC surfaces

This looks like an inconsistency and is not: it is two documents making two different demands, and getting either the other way round breaks a real client.

The Workload API must not authenticate anybody. The SPIFFE Workload Endpoint specification says the endpoint “MUST NOT require any direct authentication of its clients”, and that “Transport Layer Security MUST NOT be required”. The reason is bootstrapping: a workload has no secret and no root of trust until this very call gives it one, so there is nothing it could present. A server that demanded a credential here would refuse every conforming client, which is why the mutual TLS of the other surface deliberately does not reach it. What the Workload API does instead is attest (below).

The SPIRE Server API is mutual TLS with an X509-SVID. A real spire-server binds a TCP port whose callers present an SVID from the trust domain, takes the caller’s SPIFFE ID off the certificate, and authorizes every method against what that caller is; its private Unix socket is trusted outright, which is how the spire-server CLI works. This service does the same: the SPIFFE ID comes from the URI subjectAltName, never from the subject, and the method is checked against SPIRE’s own table. It is not a setting and cannot be turned off; the socket is bound as mutual TLS on every start.

The bootstrapping case is handled the way SPIRE handles it: the port asks for a client certificate and does not require one, because AttestAgent is open to a caller that has no SVID yet. Fetch the bundle from the bundle endpoint, verify this server against it, attest, and come back with what you were issued.

Workload attestation on the Unix socket

The Workload API authenticates nobody, because its specification says it MUST NOT: a workload has no credential until this call gives it one. What it does is attest, as a SPIRE agent does. When a connection is accepted on the Unix socket, the kernel names the connecting process (SO_PEERCRED and a pidfd, read by a small native module built into the image). The workload attestors in spiffe.workloadAttestors then turn that process into SPIRE’s selectors:

• unix: uid:, user:, gid:, group: and the supplementary groups; with spiffe.unixDiscoverWorkloadPath, also the executable’s path: and sha256:.
• docker: the container’s label:, env:, image_id: and image_config_digest:, asked of the Docker Engine at spiffe.dockerSocketPath.
• k8s: the pod’s sa:, ns:, pod-name:, pod-label:, pod-owner:, container-name:, container-image: and the rest of SPIRE’s list, read from the kubelet.
• systemd: the unit’s id: and fragment_path:, asked of systemd over D-Bus. Install the optional package dbus-next in the image (STS_CLOUD_SDKS=dbus-next at build time); without it, a realm naming systemd refuses every connection and says which package is missing.

Podman. The docker attestor asks Podman’s Docker-compatible API instead of the Engine when the container’s cgroup says libpod: the rootful socket (spiffe.dockerPodmanSocketPath), or a rootless user’s socket (spiffe.dockerPodmanSocketPathTemplate) — the rootless one only with spiffe.dockerUseRootlessPodman on, because that socket belongs to the caller. The selectors are still docker:.

Signed images. With spiffe.dockerSigstoreEnabled, a docker workload’s image must carry a cosign signature that verifies, and the attestation adds SPIRE’s image-signature:verified, image-attestations:verified and image-signature-subject:, -issuer:, -value:, -log-id:, -log-index:, -integrated-time: and -signed-entry-timestamp: selectors. Configure:

1. what a signature may verify under — cosign public key FILES (spiffe.dockerSigstorePublicKeyFiles), and for keyless signatures the sigstore trust root: through TUF (spiffe.dockerSigstoreTufRootFile, the root.json you trust, refreshed by the scheduler job spiffe.sigstore-tuf-refresh), or pinned (spiffe.dockerSigstoreTrustedRootFile);
2. for keyless signatures, the signers you accept (spiffe.dockerSigstoreAllowedIdentities, issuer=subject);
3. the registries the signatures may be fetched from (spiffe.dockerSigstoreAllowedRegistries) — Docker Hub is index.docker.io, and list its token host auth.docker.io and blob host too.

Every signature must carry its Rekor transparency-log bundle, and a keyless certificate an embedded SCT. A signature that does not verify refuses the connection (UNAVAILABLE); it never merely leaves out a selector.

A connection is attested once, when it is accepted. Every call on it checks that the process is still the one attested. A process that has exited, a reused pid or an exec of another program is refused PERMISSION_DENIED. An attestor that fails refuses every call on the connection with UNAVAILABLE. A peer in a pid namespace this service cannot see is attested on its kernel uid and gid alone.

A caller over TCP

A caller over TCP is not attested, because there is no peer process to ask. It is identified by the selectors transport:, endpoint: and peer: — the transport it arrived on, the endpoint it reached and its peer address — and by nothing else. These are deliberately spelt unlike any attestor’s, and never unix: or k8s:: writing unix:uid:1000 for a uid nothing read would be inventing an attested fact, the same offence as minting a credential format nobody specified. In development, any caller that can reach the TCP port gets an identity, and what comes out is a credential another service will believe.

Asserted selectors. In development, with spiffe.acceptAssertedSelectors on, a caller may also assert its own selectors in an x-sts-workload-selector metadata header. They are passed through verbatim, because they are the caller’s claim rather than this service’s invention, and nothing verifies them. The setting is off by default and refused in product. It exists because selector matching is the interesting behaviour of a Workload API, and without it a TCP client’s “these matched and those did not” path could not be run here at all.

The Workload Endpoint specification allows TCP only where “the underlying network allows the Workload Endpoint server to strongly authenticate the workload based on source IP address” (section 3), and forbids the other fixes: TLS must not be required and a client must not be asked to authenticate. The source address is therefore the only identity a TCP caller carries, and whether the network guarantees it is something this service cannot see. So, in product mode (#166):

• The TCP port is not bound (STS-SPIFFE-0120) unless spiffe.workloadTcpSourceAuthenticated is on. Turning it on declares the section 3 condition: a pod network with anti-spoofing, a host-only bridge. Warning: every host that reaches the port from an address an entry selects is issued that entry’s SVIDs, so an address that can be spoofed, shared behind a NAT or reassigned hands the identity to whoever holds it.
• With it on, a wildcard spiffe.grpcHost (0.0.0.0, ::) is still refused (STS-SPIFFE-0121). Name the address on the network you vouch for.
• A realm switched to product with the port already bound keeps the socket and refuses every call on it (UNAVAILABLE).
• An entry must select something that identifies its workload: never only transport: and endpoint:, which every caller of the port carries, and never nothing (STS-SPIFFE-0122). The console, /admin-api and the SPIRE Server API (INVALID_ARGUMENT per item) all refuse it. For a TCP caller that is peer:<address>, matched exactly: peer:10.0.0.0/24 is a selector no caller carries, as in SPIRE. An entry written in development answers nobody once the realm is in product (STS-SPIFFE-0123).

GET /spiffe, /admin/spiffe and GET /admin-api/spiffe report the realm’s state under workloadAttestation.tcp: served (development, not attested), not served (product, source not declared authenticated), not served (product, wildcard bind address) or served (product, source declared authenticated), with whether the port is listening.

The SPIFFE Broker API

A broker — a node proxy, a service mesh’s per-node component — can ask for the SVIDs of a workload it acts for, by naming the workload rather than being it. This is the SPIFFE Broker API (Incubating), on a mutual-TLS listener of its own:

1. Set spiffe.brokerPort on the realm (and spiffe.grpcHost where the realm needs an address of its own), then turn the realm’s SPIFFE on.
2. Authorize the broker on SPIFFE → Brokers (/admin/spiffe/brokers) or POST /admin-api/spiffe/brokers/set with its SPIFFE ID and the references it may use: pid, k8s or *. A broker from another trust domain needs that domain’s bundle federated first.
3. The broker connects with its X509-SVID, verifies this server as spiffe://<trust domain>/spire/server against the bundle, and sends broker.spiffe.io: true on every call.

It calls SubscribeToX509SVID, SubscribeToX509Bundles, FetchJWTSVID and SubscribeToJWTBundles, each with a workload reference:

• a WorkloadPIDReference — a process on this host, attested by the workload attestors exactly as a Workload API caller is. The endpoint is TCP, so allow pid only to a broker running on this host;
• a KubernetesObjectReference to a pod (pods, group core), by UID or by namespace and name — found in this node’s kubelet pod list and attested by the k8s attestor’s pod selectors. Other Kubernetes objects are refused.

The workload gets the entries its selectors match, never an admin or downstream entry. A refusal follows the specification’s table — INVALID_ARGUMENT for a missing header or a bad reference, UNAUTHENTICATED for no SVID, PERMISSION_DENIED for a caller that is not a broker, a reference type it may not use or a workload with no entry, NOT_FOUND for a workload that does not exist — with a google.rpc.ErrorInfo in the spiffe.io domain. A stream ends NOT_FOUND when its workload stops.

The SPIRE Server API

SPIRE’s six services, Entry, Agent, Bundle, SVID, TrustDomain and Debug, with forty-two methods, on TCP spiffe.serverPort (8181, because SPIRE’s own 8081 is this service’s HTTP port). They are also on a Unix socket at spiffe.serverSocket when spiffe.serverSocketEnabled is on. Thirty-six methods are implemented. GET /spiffe lists every method, with a reason for each of the six that are not.

The TCP port is mutual TLS, in every mode. The server presents its own SVID (spiffe://<trust domain>/spire/server). A caller presents an X509-SVID, which is verified against the bundle, its validity window (with spiffe.clockSkew) and the revocation register. Revoking the SPIFFE Issuing CA on /admin/pki therefore refuses every SVID under it. The caller’s SPIFFE ID is taken from the URI subjectAltName. The port asks for a certificate without requiring one, so that AttestAgent and GetBundle stay open to an agent that has no SVID yet.

Each method is authorized against SPIRE’s own per-method table, copied row for row from policy_data.json. A caller is one or more of these entities, and the check asks whether it is any of the ones a method allows — the spire-server CLI on this host is local, and an agent that also holds an entry marked admin is both:

Where a row looks surprising, that is SPIRE’s own answer. For example, Debug.GetInfo is local-only, so an admin SVID over TCP is refused it. After SPIRE’s table has allowed a call, the XACML access gate is asked. It permits by default. An authenticated caller gets a session keyed on its SPIFFE ID.

A method the caller is not allowed is refused UNAUTHENTICATED when nothing was presented and PERMISSION_DENIED when something was and it was not enough. Those are different instructions to a client — “authenticate” and “you may not” — and SPIRE distinguishes them; collapsing them sends a client that needs a credential looking for a permission it will never get.

The admin and downstream flags on a registration entry are read on every call, and nothing caches them, so an ldapmodify of spiffeAdmin under ou=spiffe — or the form on /admin/spiffe/entries — changes what that identity may do on the next call.

RenewAgent renews the agent on the connection, never an agent named in the request: renewing whichever agent the caller named would be a way for anybody to obtain any agent’s identity.

Node attestation

Agent.AttestAgent accepts only an attestation type that the realm lists in spiffe.nodeAttestors and that this server can verify. Anything else is refused FAILED_PRECONDITION, as SPIRE refuses an attestor it has no plugin for. There is no fallback. All nine of SPIRE’s server node attestors are implemented, step for step:

An attestor returns only selectors it verified. A trust anchor is PEM text in a setting, not a file path, so the console and /admin-api can set it. No credential is ever a setting. Where SPIRE takes an access key, an app secret or a kubeconfig, this server takes a file path or uses the cloud SDK’s own credential chain. The cloud SDKs are optional packages: a realm that enables aws_iid, gcp_iit or azure_imds without the SDK installed is refused, and the refusal names the missing package.

Evidence that cannot be re-attested, namely a join token and the trust-on-first-use cloud documents (and http_challenge with spiffe.httpChallengeTofu), attests once. Attesting the same agent again is refused until an operator deletes the agent. Evidence is spent only after the agent’s SVID exists, so a refused attestation spends nothing. A challenge is a conversation on the same stream; with no answer inside spiffe.attestationChallengeTimeout, the call fails DEADLINE_EXCEEDED.

http_challenge is the one place this server dials an address a caller named. The host name must match spiffe.httpChallengeAllowedDnsPatterns before it is looked up. That list is empty by default, which refuses every agent; this is stricter than SPIRE, whose empty list allows any name. In product mode internal addresses are refused, and in every mode the request follows no redirect and reads at most 64 bytes.

The registry is the directory

Registration entries live in the LDAP directory under ou=entries,ou=spiffe and attested agents under ou=agents,ou=spiffe. Nothing caches them. A form on /admin/spiffe/entries, an ldapmodify and BatchCreateEntry / BatchUpdateEntry / BatchDeleteEntry are three doors to one store, all calling the same functions, and the next SVID reflects the change — an ldapmodify of spiffeX509SvidTtl changes the lifetime of the next SVID the Workload API hands out.

The two containers hold different kinds of thing. An entry is configuration deciding what will be issued; an agent is a record of something that happened, so nothing on it is editable, and ban and delete are the only controls. What may be changed on an entry is declared rather than derived: the SPIFFE ID, the parent, the selectors, the lifetimes and the flags are editable on the forms and the API, and the revision number and the SVID counter are not — a form that could rewrite a counter would make the page lie about this service’s own behaviour. ldapmodify still reaches everything.

GET /admin/ldap/spiffe publishes the whole schema, because the directory is schemaless and roughly thirty of these attribute names are this service’s own inventions: no registered LDAP schema has a SPIFFE ID or a selector on it.

A workload identity’s directory entry

An accepted SPIFFE credential is an identity, and it reaches the same authentication record every other protocol family feeds, so its holder appears on /admin/users and gets a directory entry. Three acceptances count:

Being issued an SVID is not one of them: receiving a credential is not presenting one. A Workload API caller appears on /admin/users with never in the authentication column, counted under “seen only as a subject” — but it does get a directory entry.

The entry is uid=spiffe-<12 hex>,ou=users, named by a digest because a SPIFFE ID is neither a name nor a DN, with the identifier whole on the entry as a multi-valued spiffeSubject and spiffeTrustDomain / spiffePath beside it. It is found by spiffeSubject, never by rebuilding the digest, which is what makes the same identity arriving every way one entry rather than several. It deliberately does not fold onto a person of a similar name: the last segment of a SPIFFE path is exactly the kind of short common word (db, web, api) that collides with a username, and a workload called db is not the DBA.

Every X509-SVID this trust domain mints is written onto that entry too, so “which identities hold a certificate, what is the current one, and can this one still get another” is answered by an ldapsearch. The certificate is read back off itself at the moment it is issued, and the entry carries the same x509* attributes a verified TLS client certificate writes, in the same strings:

• A rotation lands on the same object, because the entry is found by the SPIFFE ID and by nothing about the certificate: the fiftieth SVID for spiffe://…/sa/db updates the entry the first one created.
• The attributes are REPLACED here, where a TLS client certificate APPENDS them. A renewed client certificate is rare and seeing both serials is the point; an SVID is minted afresh at half its lifetime for as long as the workload runs, so appending would add values every hour for ever. The three counters are what is kept of the history, and the individual serials are all on /admin/metrics.
• The identity is the SPIFFE ID, not the subject DN. Filing an SVID by its subject, as a client certificate is filed, would fold every workload in the trust domain onto one entry called O=SPIRE. The certificate is a fact about the identity here, not the identity.

spiffeCredentialStatus is not a revocation

SPIFFE has no revocation. There is no CRL, no OCSP and no serial list; the answer is a short lifetime and rotation, the crl field in the Workload API’s responses is empty because empty is the conforming value, and an SVID already in a workload’s hands verifies against the bundle until it expires. Nothing reads this attribute back, and no certificate is ever refused because of it.

What it records is the three things in the registry that end an identity’s ability to obtain a new credential here, on the entry of the identity they happened to:

spiffeCredentialStatusReason is a sentence rather than a code, because it is the only thing that explains a status a reader did not expect. spiffeRevokedAt is when it was last revoked and is never cleared — the history the current-state flag deliberately does not keep.

The entry is never removed. An identity this trust domain used to issue certificates to is exactly what somebody points an LDAP client at the directory to find, and deleting it would answer “was there ever a workload called db?” with silence.

Federation

A foreign bundle is pushed in and never fetched. Set it with POST /admin-api/spiffe/federation-set, the form on /admin/spiffe, or BatchSetFederatedBundle. RefreshBundle refuses, naming the URL it will not follow. Federated bundles belong to a realm. None may be named after a trust domain that any realm of this service serves, and every JWK in one must carry a use.

The federation specification puts a bundle endpoint URL in the relationship, and a real implementation polls it. This one records the URL and refuses to follow it: fetching a URL somebody registered, in order to obtain a key that will then verify credentials, is a server-side request forgery with a specification citation attached. It is the same refusal this service gives WS-Federation’s wreqptr.

What is refused

The list is short, and not empty — a server that said yes to everything would be useless to the only people who call some of these methods:

• A Workload API call with no workload.spiffe.io: true metadata header. The Workload Endpoint specification requires it and requires a server to refuse without it (section 3). It is a hardening measure against server-side request forgery rather than an authentication — anybody can send a header, but a request an attacker merely causes a workload to make rarely carries it. A client that omits it has a bug, and this is the only thing that will ever tell them: every real implementation will refuse them, and a server that accepted it would let somebody ship code that works here and nowhere else. spiffe.requireSecurityHeader turns it off in development only.
• FetchJWTSVID and MintJWTSVID with no audience. A JWT-SVID is a bearer credential; the audience is what stops one issued for service A being replayed against service B, which is why the specification puts it in the request rather than in configuration.
• ValidateJWTSVID on anything that does not really verify — the signature against the trust domain’s JWT authorities, exp with no leeway, the audience, and that the sub belongs to the trust domain whose key verified it. The point of the call is to be told no.
• A registration entry whose SPIFFE ID is invalid, belongs to another trust domain, or sits under the reserved /spire path.
• AttestAgent for a banned agent, and a join token this server did not mint, one that has expired, one presented twice, or one minted for a named agent and presented by another. A ban that did not refuse would make the button on /admin/spiffe/agents a lie, and accepting a join token this server never minted would be accepting a forgery of its own credential.
• Every method the caller’s entity is not allowed, UNAUTHENTICATED or PERMISSION_DENIED as above.
• An X509-SVID that no authority in this trust domain or a federated one signed; one outside its validity window (spiffe.clockSkew); one with no URI subjectAltName, or with several — an SVID has exactly one, and choosing between two would be deciding which identity you have; and one whose SPIFFE ID names a different trust domain from the authority that signed it, which is precisely the cross-domain confusion a bundle exists to prevent.
• A federated bundle whose JWKs have no use member. A consumer MUST IGNORE a JWK whose use is missing or unknown, so a bundle full of them would be stored happily and then verify nothing, with no error anywhere pointing back at the bundle. Refusing it is the only way that failure ever gets diagnosed.

The SPIFFE ID grammar is stricter than a URL parser

A SPIFFE ID is checked as raw text, never with a URL parser, because a URL parser gets four things wrong here, each producing an identifier that looks right in a log:

• A trust domain is lower-case. spiffe://Example.org/x is not a valid SPIFFE ID, and it is not another spelling of spiffe://example.org/x either. A URL parser lower-cases the host for you, which hides the defect: the client that sent the wrong form gets an SVID naming the right one and never learns.
• The path is not a URL path. No percent-encoding, no empty segment (so no trailing slash and no //), no . or ... A URL parser accepts all of those and normalises three of them away.
• No port, no userinfo, no query, no fragment. Each is a way of writing an identifier that a naive prefix test treats as belonging to a trust domain it does not — an authorization bug in anything that federates. Membership here is a comparison of the parsed trust domain, never a prefix test.
• /spire is reserved for the server and the agents it attests, so a registration entry there is refused: it would be an identifier this service also mints on its own account.

Not implemented

• Six SPIRE Server API methods (listed with reasons on GET /spiffe) and the two Workload API WIT methods. Bundle.AppendBundle and Bundle.PublishJWTAuthority would add an authority to this trust domain’s bundle that this server holds no private key for, so every workload would trust an authority that can issue nothing — rotate instead. TrustDomain.RefreshBundle would fetch a URL somebody registered. The WIT methods (FetchWITSVID, FetchWITBundles, SVID.MintWITSVID, SVID.BatchNewWITSVID, Bundle.PublishWITAuthority) are in the current protos, but the Workload Identity Token’s own format is not settled in a document this service could implement against; minting something JWS-shaped and calling it a WIT-SVID would be inventing a credential format.
• Revocation of an SVID. The answer is a short lifetime and rotation, and the bundle’s crl field stays empty.
• Workload attestation of a TCP caller, which has no process to attest (so product mode serves TCP only on a declared network).
• In an image signature: the online Rekor lookup for a signature with no bundle (it is refused), the new sigstore bundle format and RFC 3161 timestamps.
• In the Broker API: references to Kubernetes objects other than pods, SPIRE’s cluster pod-reference scope, a Unix socket endpoint and gRPC server reflection.
• An interop run against a real spire-agent.

Development and product mode

These are the same in both modes: mutual TLS on the SPIRE Server API, SPIRE’s method table, node attestation, workload attestation where the native module is present, and automatic authority rotation. See what is not checked.

Configuration

SPIFFE has about a hundred settings, grouped below. Every runtime setting can be set per trust realm. The restart settings are fixed for the process at startup. On a realm, the socket settings take effect when that realm’s sockets are reconciled, which happens whenever one of the realm’s settings changes.

The surface and the trust domain

Authorities, keys and lifetimes

Sockets

The Workload API

Workload attestors

The SPIRE Server API

Node attestation: common settings

x509pop, sshpop and tpm_devid

k8s_psat and http_challenge

aws_iid

gcp_iit

azure_imds

These tables are a copy of the rows in the service’s settings table. The live source is Protocols → SPIFFE (/admin/spiffe), where every setting is drawn, and GET /admin-api/config. POST /admin-api/config/set changes one. See Configuration for how a value is resolved.

Design decisions

• A realm is told apart by address, not by path. gRPC’s path is the method name, fixed by the specifications, so a realm segment would be a method no client calls. A real deployment is the same: one SPIRE server is one trust domain.
• A realm starts with SPIFFE off. Turning SPIFFE on binds sockets and creates an authority. Creating a realm should not open ports or start issuing credentials nobody asked for.
• A new realm gets no TCP gRPC ports and no administrators. The inherited ports and address are already the default realm’s. The network-reachable API that mints credentials is opened only by somebody who sets an address and ports on the realm.
• The two gRPC surfaces are authenticated differently because their specifications say opposite things. The Workload API must not authenticate its caller. A SPIRE server authorizes every method against what the caller is. Neither half is a setting.
• SPIRE’s authorization table is copied, not reasoned out. A table derived from what each method “obviously” needs would differ from SPIRE in a few places, and a client author could not tell which end was wrong.
• Attestation is not authentication. The Unix socket attests the connecting process as an agent does. A TCP caller, which cannot be attested, is identified by selectors spelt so they cannot pass for attested facts.
• Node attestation refuses what it cannot verify, in every mode. A real agent pointed at a server that accepted any attestation type could join a trust domain with an invented one.
• No credential is a setting. Settings are shown on the console, returned by the management API and persisted. Cloud keys and tokens come from files or from the SDK’s own credential chain.
• A foreign bundle is pushed, never fetched. Fetching a URL somebody registered, to obtain a key that will verify credentials, is a server-side request forgery. http_challenge is the one exception, and its allow list is empty by default.
• Federated bundles belong to a realm, and none may shadow a served domain. Otherwise one realm could register a bundle under another realm’s trust domain and mint SVIDs that the other realm would accept.
• The registry is the directory. Entries are configuration an ldapmodify can change, with no cache to go stale. Agents are records, so they are not editable.
• SPIFFE has no revocation, and nothing here pretends to. spiffeCredentialStatus records who can no longer be issued an SVID. Short lifetimes and rotation are the mechanism. The streams re-send at half the lifetime, so clients exercise rotation.
• An unregistered workload gets an empty SVID list in product mode, and in development with spiffe.autoCreateEntries off, because that is what a real agent answers. It is the only way to test a client’s “I have no identity” path.
• A join token is stored only as a digest, and its selector is token-sha256:, so neither the store nor the directory holds a usable token.
• X.509 is EC P-256 by default, which is what SPIRE issues and what the X509-SVID specification recommends. The certificate code that makes it is shared, byte-identical, with the OAuth2/OIDC Debugger (node-forge, used elsewhere here, cannot sign with an EC key at all), and it comes with that project’s test, which builds about 240 certificates — every key algorithm against every signature algorithm, every extension, a four-deep chain — and checks each with OpenSSL rather than by reading back what the same code wrote.
• gRPC is @grpc/grpc-js, not a hand-rolled codec. A protobuf codec and a gRPC server over node’s http2 would have been about 900 lines and no dependency, but this service exists to be talked to by real clients — go-spiffe, spiffe-helper, a SPIRE agent, the spire-server CLI — and an interoperability bug in a hand-rolled HTTP/2 framer appears as a client that hangs or reports a truncated message, with no way for the client author to tell whose fault it is. About thirty packages buy the wire being right. Two traps in it: the loader’s keepCase: true does not reach the well-known types, so a google.protobuf.Struct has to be built with stringValue (string_value serialises to nothing, silently); and protobufjs converts only Any, so a plain object assigned to a Struct field becomes an empty Struct.

In the running service

• Protocols → SPIFFE → SPIFFE (/admin/spiffe): the trust domain, the X.509 and JWT authorities and the trust anchors, whether each of the four sockets actually bound, how Workload API callers are identified and attested, the federated bundles, and every spiffe.* setting. It has Rotate (X.509, JWT or both) and a form to set or remove a federated bundle.
• Protocols → SPIFFE → Registration entries (/admin/spiffe/entries): which workload gets which SPIFFE ID and what an SVID from each entry carries: parent, selectors, DNS names, federates-with, the two lifetimes, hint, expiry, and the admin, downstream and storeSvid flags. Create, edit and delete are here. A change takes effect on the next SVID.
• Protocols → SPIFFE → Agents (/admin/spiffe/agents): every agent that has attested, what it was given and when. Ban, unban and delete are the only controls. Deleting an agent lets trust-on-first-use evidence attest again.
• Directory → SPIFFE entries (/admin/ldap/spiffe): both containers as the directory holds them, with their attribute schema.
• GET /spiffe (add ?format=json): all three surfaces, the state of every socket, every SPIRE method with its authorization row, the six unimplemented methods with their reasons, the node attestors this build verifies, and whether the Workload API socket is attested.
• The management API: GET /admin-api/spiffe, POST /admin-api/spiffe/{action} (rotate, federation-set, federation-remove), /admin-api/spiffe/entries and /admin-api/spiffe/agents with their actions.

GET /admin/sts-metadata cannot list the gRPC sockets, because they register no HTTP route. GET /spiffe and /admin/spiffe report them. Every SPIFFE failure is recorded under an STS-SPIFFE-NNNN code on the audit row and the log line, and never sent to a client. See error codes.

Related

• PKI: the Root, the realm Intermediate and the SPIFFE Issuing CA
• LDAP: the registry under ou=spiffe and the workload entries under ou=users
• Trust realms
• TLS and mutual TLS
• XACML: the access gate after SPIRE’s table
• Sessions
• What is not checked, especially The Workload API is the opposite case
• Configuration