Configuration Options

This reference follows the public fields of openstack-keystone-config. Defaults come from the corresponding Rust Default implementation; options without a usable default are required when their feature is enabled. Consult the feature guide for constraints and safe production values.

Service and Interfaces

The public interface is enabled by default. Internal and admin interfaces are optional. The metrics listener defaults to 0.0.0.0:8099.

Telemetry

Telemetry is off by default. [oslo_middleware_tracing] is an alias that accepts the options of oslo.middleware’s tracing middleware and drives traces only; where an option is set in both sections [otel] wins and a warning is logged at startup. protocol is http/protobuf (default, endpoint http://localhost:4318) or grpc (http://localhost:4317). headers and resource_attributes are comma separated name=value lists; headers may carry credentials and is never logged. Request spans are named after the route template (for example GET /v3/users/{user_id}). include_user_ids is false by default because spans leave the host: it gates the authenticated user, project and domain ids and the raw request path, which contains resource ids. include_client_address is separate and also false by default: it adds the caller’s IP as client.address. Anything these options add can be removed again in the collector. response_traceparent echoes the trace context in responses, and legacy_http_attributes adds the http.method family of names that oslo.middleware emits. insecure applies to grpc only, as in oslo.middleware. span_level (default info) is the most verbose span exported. A malformed value fails startup even while telemetry is disabled.

Export needs a build with the otel cargo feature (otlp-grpc adds the gRPC transport). Without it the options are validated but nothing is exported, and startup logs a warning. Traces and metrics are exported in the background and never block requests; if the pipeline cannot be built, Keystone logs it and starts without telemetry.

Authentication, Tokens, and Security

insecure_allow_null_key defaults to false. Keep it disabled in production. See Fernet tokens and Security.

Policy and Domain Providers

OPA policy is enabled by default. See API policy enforcement.

Feature Providers

See the corresponding pages under Administrator Guides for validation rules and complete operational examples. [mapping].cluster_salt is required before mapping-backed authentication (SPIFFE, Kubernetes, federation, API client) works at all; see Identity Mapping Administration for that requirement and for rule-matching precision (narrow claim matches, is_system scoping, least-privilege roles) as a security concern distinct from it.

Dynamic Plugins and Audit

[audit] enabled defaults to true. Setting it to false skips creating the spool directory, spool lock, HMAC key and writer, and discards audit events; use it only for development or deployments that do not need an audit trail.

Audit signing key and node identity:

• node_id identifies the node in every event, names its spool files and keys its signing key, so it must be unique per node. It defaults to the HOSTNAME environment variable, then the system hostname; Keystone refuses to start with auditing enabled if it is empty, unset (the unknown-node fallback) or contains characters outside A-Z a-z 0-9 . _ -.
• hmac_kek_file is the keyring holding the audit key-encryption-keys, one per key version, created with mode 0600 if missing. It must not be inside spool_dir (startup fails if it is): whoever can write the spool must not be able to read the key that signs it. When unset, the legacy <spool_dir>/hmac-key.bin is used so existing deployments keep working, and a warning is logged. A legacy 32-byte key file is read as key version 1.
• Rotate the signing key with keystone-manage audit rotate-hmac-key. It adds a new version and makes it current; old versions are kept so events already signed stay verifiable. Running servers pick the new version up within about 30 seconds. Back up the keyring and give the SIEM verifier the updated copy.

Spool and queue limits:

The three spool limits are unset by default, so no audit record is deleted unless an operator opts in. They are evaluated at startup and whenever the live spool rotates. A segment deleted by a limit was never acknowledged by a sink: each deletion is logged at ERROR and counted in keystone_audit_spool_retention_deleted_total.

Audit sink ([audit] sink): sealed spool segments are shipped to the sink and deleted only after the sink has accepted every event.

The syslog sink takes endpoint (host:port, required), tls (default false), ca_file (PEM bundle; defaults to the system trust store), app_name (default keystone), connect_timeout_secs (default 10) and write_timeout_secs (default 30):

[audit]
sink = { type = "syslog", endpoint = "siem.example.com:6514", tls = true, ca_file = "/etc/keystone/siem-ca.pem" }

Each message carries the signed CADF JSON as its MSG and is framed with octet counting (RFC 6587), so the receiver can verify the HMAC as it would from the spool. Delivery is at-least-once: a failed or timed-out batch is retried with backoff and the segment is kept until delivery succeeds, so receivers should deduplicate on the event id. TCP has no application acknowledgement; a batch counts as delivered once it is written and flushed to the peer. If Keystone was built without audit-syslog, configuring this sink makes startup fail.

See Audit trail.

See Dynamic authentication plugin operations.

Distributed Storage and Emergency Operations

Distributed storage is optional. When enabled in production, use the complete distributed-storage runbook; the option list alone is not a safe deployment procedure.