Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Security reference

Reference tables for operators and for downstream manufacturers who integrate Keystone into a product. They complement the checklist in Security and back the Cyber Resilience Act mapping in CRA requirements. Every row states behaviour verified against the code at the time of writing; a row marked Gap is a known weakness, not a recommendation.

Secure defaults

One row per option that weakens the deployment when changed, or that is off by default and should be turned on.

OptionDefaultEffect of the defaultRecommended
[fernet_tokens] insecure_allow_null_key, [credential] insecure_allow_null_keyfalseKeystone refuses to start with the well-known Null Key.Keep false; set true only during a controlled key migration.
[distributed_storage] dev_modefalseKEK source and process hardening pre-flight checks are enforced.Never set in production.
[distributed_storage] kek_providerenvThe env KEK is accepted only with dev_mode = true, so a production node does not start until pkcs11 or tpm is set explicitly.pkcs11 or tpm.
[distributed_storage] local_reads_modedisabledEvery read is linearizable; no stale reads.Keep disabled unless a consumer needs stale PUBLIC/INTERNAL reads.
[api_policy]engine = opa, OPA at http://localhost:8181Every authorised endpoint is evaluated by the selected engine: OPA over HTTP, or in-process regorus (experimental, engine = regorus, reloaded on SIGHUP).Run OPA beside Keystone; see policy.
[rate_limit_global_ip], [rate_limit_user_auth]enabled = true, burst_size = 100, replenish_rate_per_second = 10Both limiters are active without configuration. Limits are per node and held in memory (ADR 0022). Enabled values outside 1..=100000 stop startup.Size the buckets for the deployment; set enabled = false only when a proxy already limits.
[rate_limit_trusted_proxies] trusted_proxiesemptyNo forwarding header is trusted; the peer address is used. Behind an unlisted proxy every client shares the proxy’s bucket.List the proxies that sanitise the header, and set trusted_header.
[interface_admin]not configuredThe admin interface is not started. When configured it is a Unix socket only, with optional peer_uid and peer_gid checks.Configure peer_uid or peer_gid, and restrict the socket directory.
[interface_internal]not configuredNo second TCP listener.Configure only when a separate trust zone is needed.
[DEFAULT] debugfalseNo DEBUG log level for the file sink.Keep false in production.
[interface_metrics] http_requests_enabledtrueHTTP request metrics are recorded.Keep.

Container images run as the unprivileged user keystone (uid and gid 65532). The reference manifests under deploy/ run non-root with a read-only root filesystem and no capabilities; see Verifying release artifacts for the image digests.

Interfaces and ports

Keystone does not terminate public TLS. Put a trusted proxy in front of the public listener.

InterfaceConfig sectionDefault bindTransport and authenticationNotes
Public REST[interface_public]0.0.0.0:8080type = http (default, plain HTTP, bearer tokens) or type = spiffe (mTLS with trust domains)
Internal REST[interface_internal]0.0.0.0:8081 when the section is present without tcp_addressSame type choices as publicDisabled when the section is absent.
Admin[interface_admin]Unix socket /var/lib/keystone/keystone.sockSPIFFE mTLS over the socket, plus peer_uid and peer_gidadmin_svid maps a matching SVID to the system admin role. Used for bootstrap.
Health and metrics[interface_metrics]0.0.0.0:8099Plain HTTP, no authentication: /health, /ready, /metricsBind to a monitoring network.
Raft peer[distributed_storage] node_listener_addr0.0.0.0:8081gRPC with mTLS, SPIFFE or certificate basedOnly with distributed storage. Needs a node-specific port when it shares a host with the public listener.
Database[database]outboundTLS through system OpenSSL (NET-3)Operator-managed.
OPA[api_policy] opa_base_urloutbound, http://localhost:8181HTTP, or a Unix socket URLKeep on loopback or a Unix socket. With opa_policies_path set, Keystone starts OPA itself.
Auth plugins[auth_plugins]in-process WASMCapability list and SHA-256 artefact pinning (TOK-10)Pre-authentication attack surface; load only reviewed plugins.

Policy enforcement has no off switch: an enforcer (OPA by default, or regorus) is always created.

Failure semantics

Keystone fails closed. A dependency outage denies or stops work; it never widens access.

Dependency is unreachableBehaviourSignal
OPAThe decision cannot be made, so the request fails with 500. Only a real OPA deny returns 403. No request is allowed without a decision./ready reports the policy engine; the policy errors_total metric counts the failure.
DatabaseRequests that need it fail./ready returns 503 for a degraded database.
Audit queueA provider operation whose attempt audit record cannot be queued is not performed. Perimeter records are best effort and are dropped and counted when the channel is full.keystone_audit_* metrics; see Audit trail.
KEK provider (PKCS#11, TPM)A node cannot unwrap the storage DEK and does not start.Process exits at startup.
Raft quorumReads that cannot be confirmed linearizable return Unavailable rather than a possibly stale copy. A node with no quorum is not ready.keystone_raft_* metrics; /ready.
SPIRE agentA node whose SVID is about to expire drains proposals and halts; it never falls back to an expired SVID.Node stops; peers log refused SVIDs.
Fernet or credential key repositoryA missing or Null key stops startup unless insecure_allow_null_key is set.Process exits at startup.
Upstream IdP, LDAPAuthentication through that source fails; local sources are unaffected.Authentication failure metrics and audit failure records.

Encryption coverage

“At rest” means on the storage Keystone controls. Where Keystone relies on the database, encryption is the operator’s responsibility. Algorithms and FIPS status are in the crypto inventory.

Data classStored inProtected by KeystoneOperator duty
Bearer tokensnot stored (Fernet) or signed JWSFernet (TOK-1) or ES256/RS256 (TOK-2)Protect and rotate key repositories.
Credential blobs (EC2, TOTP, …)SQL databaseFernet encryption of the blob (TOK-1)Protect the credential key repository.
PasswordsSQL databaseSalted hashes: bcrypt, scrypt, PBKDF2 (PWD-1…3)Database access control and backup protection.
API keys, OAuth2 client secretsRaft (default driver)Argon2id hashes (TOK-7)None beyond KEK custody.
Raft log, state machine, backupsRaft storageAES-256-GCM under a DEK wrapped by the KEK (STO-1…8)Choose PKCS#11 or TPM; protect the KEK.
Raft peer trafficnetworkmTLS (STO-9, STO-12)Issue and rotate certificates or SVIDs.
Audit spoollocal diskHMAC-SHA256 signed, tamper-evident; not encrypted (AUD-1)Restrict the spool directory; use a TLS sink (AUD-4).
Identity data (users, groups, projects, assignments, trusts, revocation events, …)SQL databaseNot encrypted by KeystoneDatabase and backup encryption.
Database connectionsnetworkTLS to MySQL and PostgreSQL when configured (NET-3)Require TLS at the server.
Client connectionsnetworkTLS only through a proxy, or SPIFFE mTLSTerminate TLS in front of the public listener.

Data inventory

Personal and security-relevant data Keystone holds or emits. Retention is the operator’s unless a row says otherwise.

DataPurposeWhereRetention
User name, ID, domain, email and other attributesIdentification and authenticationSQL identity backend, or the external LDAPUntil the user is deleted. See Data removal.
Password hash, failed-attempt counters, last activityAuthentication, lockoutSQLUntil user deletion.
Passkey public keys and stateWebAuthn loginRaftUntil removed.
Federated identity linksFederationFederation backendUntil removed.
Role assignments, trusts, application credentialsAuthorisation and delegationSQLUntil the owning user or project is deleted (assignments, trusts and application credentials are removed with the user).
Revocation eventsToken revocationSQLPruned after the token expiry plus [revoke] expiration_buffer.
Audit records: initiator ID, domain, project, source address, target ID, action, outcomeAccountability and incident forensicsLocal signed spool, then the configured sinkKept until shipped; deleted only after the sink acknowledges, or by spool_max_segments.
Application logsOperationsLog sinkOperator-defined. May carry user IDs and source addresses; never bearer tokens.
Traces and metricsOperationsOTLP / PrometheusOperator-defined.

Audit records carry identifiers, not names, emails or secrets. Secrets are stripped from policy input and audit payloads. See Audit trail and ADR 0023.

Data removal

What DELETE /v3/users/{id} (and the v4 equivalent) removes. The identity service deletes the user record, then, in the same audited operation, the user’s credentials, application credentials, trusts and role assignments, the cached user entries, and the identity mapping on domain-specific backends. Event hooks then remove passkeys, revoke OAuth2 sessions and purge the auth-plugin identity index.

LocationRemoved on user delete?Notes
User record in the SQL identity backendYes
Credentials, application credentials, trusts, role assignmentsYesCascade in the identity service. A retry after a partial failure finishes the cascade.
In-process user cachesYesPer node; other nodes expire entries by TTL.
Passkeys and pending passkey ceremony stateYes, best effortRemoved by an event hook after the delete succeeds. A failure is logged (failed to purge passkeys of deleted user) and not retried; the janitor expires ceremony state.
OAuth2 refresh-token families, pending authorisations and device grantsRevokedThe OAuth2 session hook tombstones them on delete, so none can mint a new token.
Federated user linksYesDatabase foreign key with ON DELETE CASCADE (SQL identity backend).
API keysNot user dataAPI keys belong to a domain and SCIM provider, not to a user.
Issued tokensNo (stateless)Valid until expiry; revoke by user.
Revocation eventsNoKept so revocation outlives the user.
Audit recordsNoRetained by design for accountability; they hold identifiers only.
Raft snapshots and logIndirectA deleted Raft record leaves the live state, but older log entries and snapshots hold it until Raft log compaction purges them.
Database and Raft backupsNoBackups keep the data until the operator expires them. Plan backup retention accordingly.
LDAP identity backendNoKeystone does not write to LDAP; deletion is in the directory.

Export: Keystone has no bulk personal-data export API. The user record, role assignments and application credentials can be read through the REST API; the audit trail can be searched in the sink by initiator.id and target.id.

Release build hardening

PropertyValue
Memory-safe languageRust. unsafe_code = "forbid" workspace-wide; unwrap, expect and println! are denied by lint.
Profile[profile.release]: strip = true, debug = false, lto = "thin". Release archives use [profile.dist] (inherits release); container images use --release.
Compiler flagsNone overridden. No RUSTFLAGS.
Linker and loader hardeningThe rustc default for x86_64-unknown-linux-gnu: position-independent executable, full RELRO with BIND_NOW, non-executable stack. Checked by building a sample binary with the project toolchain and reading its ELF headers.
Dependency metadataRelease binaries embed cargo-auditable data, so installed binaries can be scanned.
Supply chainRelease gate (cargo audit, cargo deny, VEX check), CycloneDX SBOM and OpenVEX attached to each release, build provenance attestation. See Verifying release artifacts.
Not appliedStack protector, -Z sanitizers and control-flow integrity flags are not used.

Recheck the linker row against a shipped release binary when the toolchain or target set changes.