Secret Management

Configure how heimdall obtains secrets, credentials, key material, and certificate bundles.

Secret management in heimdall separates the location of secret material from the components that consume it. A secret source defines where and how secrets are stored; a secret reference points a consuming component to a specific entry within a source.

This separation means you can switch the underlying secret source without changing any consuming configuration.

Secret Types

heimdall distinguishes between three kinds of secret material:

Secret: A single secret value such as an API key, a symmetric key, or an asymmetric key pair (including its certificate chain). Consuming components reference this type via a secret property.
Credentials: Structured authentication data, such as a client ID and client secret, or a username and password. Consuming components reference this type via a credentials property. The exact fields required depend on the consumer and are documented at each consumer’s configuration reference.
Certificate Bundle: A set of X.509 certificates used as trust anchors to validate certificate chains. Consuming components reference this type via a trust_anchors property.

Secret Source Configuration

Secret sources are configured under the top-level secret_management key. Each source has a unique, freely chosen name, a secret provider type, provider-specific config, and an optional allow_in_rules flag.

secret_management:
  # Freely chosen name for this source
  <source-name>:
    # The provider type to use.
    type: <type>
    # Whether secrets from this source may be read from within rules.
    # Optional, defaults to false.
    allow_in_rules: false
    # Provider-specific configuration.
    config: {}

Multiple sources can share the same secret provider type. For example, you can define two pem sources that load different files.

The allow_in_rules flag controls whether secrets from a source can be referenced from rule definitions via the secret template function. If set to false (the default) and a rule attempts to reference a secret from that source, the rule will fail to load and the entire rule set will not be applied.

Only set allow_in_rules: true for sources whose secrets you are comfortable making available to rule authors. A principal with write access to a rule source (e.g., a Kubernetes RuleSet resource) could craft a rule that causes heimdall to use a secret in an unintended way. Restrict this flag to sources containing only the secrets that rule authors legitimately need.

Secret References

Consuming components reference a secret by specifying a source and optionally a selector:

# For Secret and Credentials types:
secret:        # or: credentials:
  source: <source-name>
  selector: <selector>

# For Certificate Bundle types:
trust_anchors:
  source: <source-name>
  selector: <selector>

source — required. Names one of the configured entries under secret_management.
selector — a provider-local, path-style identifier in the form segment[/segment]*, where each segment is a string containing no /. Whether it is required or optional depends on the used secret provider (see below).

Secret Providers

PEM

The PEM provider reads a PEM-encoded file and exposes either asymmetric key material or a certificate bundle, depending on the file’s contents. PKCS#1 and PKCS#8 encodings are supported for private keys.

A PEM file containing one or more private keys is treated as a key store. Any certificates present in the same file are associated with the matching private keys to form certificate chains. When loading such a file, heimdall performs the following checks:
- Key IDs must be unique. Files with duplicate key IDs are rejected.
- Each key’s certificate chain must be internally consistent. Heimdall refuses to start if chain construction fails.
- Each constructed chain must pass certificate validation. Heimdall refuses to start if validation fails.
A PEM file containing only certificates (no keys) is treated as a certificate bundle and can be used as trust anchors.

A PEM file must not change its material kind at runtime. If file watching is enabled, a reload is only applied if the new content has the same kind (key store or certificate bundle) as the previously loaded content. A transition between the two kinds at runtime is rejected, and the last known good state is kept.

To configure this provider, specify pem as provider type. The following options are available under config:

path: string (mandatory)
Path to the PEM file.
password: string (optional)
Passphrase to decrypt password-protected key material. Only applicable to PKCS#8 encoded keys.
If the key store contains multiple password-protected keys, all keys must share the same password.

watch: bool (optional, default: false)

When enabled, heimdall watches the file for changes and reloads the secrets automatically when the file is modified.

Components that consume certificate bundles as trust_anchors - such as the jwt_authenticator - do not hot-reload trust anchors. Changes to a certificate bundle file take effect for such consumers only after a restart of heimdall.

secret_management:
  my_pem_source:
    type: pem
    config:
      path: /etc/heimdall/secrets.pem
      password: "${PEM_PASSWORD}"
      watch: true

When running on Kubernetes with cert-manager, the PEM provider requires a single file containing both the private key and the certificate chain. cert-manager’s additionalOutputFormats: CombinedPEM produces exactly this as tls-combined.pem in the resulting Secret. This feature is available by default since cert-manager 1.15 (GA since 1.18); for older versions the AdditionalCertificateOutputFormats feature gate must be enabled explicitly.

Selector

For key stores, the selector identifies a key by its key ID. If no selector is specified, the first key in the file is used.

The key ID is determined by the following algorithm, in order:

If the PEM block containing the private key has an X-Key-ID header, its value is used.
Otherwise, if an X.509 certificate is present for the key and has the Subject Key Identifier extension set, the hex representation of that extension is used.
Otherwise, heimdall computes a Subject Key Identifier according to RFC 3280, Section 4.2.1.2 and uses its hex representation.

For certificate bundles, no selector is required or used.

Example 1. Referencing a key by ID

Given a PEM file at /opt/heimdall/keystore.pem with an EC private key whose X-Key-ID header is set to foo:

-----BEGIN EC PRIVATE KEY-----
X-Key-ID: foo

MIGkAgEBBDBRLr783dIM5NHJnDDMRVBiFSF56xqHle5lZk1ZCyyow9wKZGuF4EWK
...
-----END EC PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Configure the source and reference the key by its ID:

secret_management:
  my_pem_source:
    type: pem
    config:
      path: /opt/heimdall/keystore.pem

tls:
  secret:
    source: my_pem_source
    selector: foo

File

The file secret provider reads secret values and structured credentials from a YAML or JSON file. Unlike the inline provider, it keeps sensitive material out of the heimdall configuration file and supports hot-reloading.

To configure this provider, specify file as provider type. The following options are available under config:

path: string (mandatory)
Path to a YAML or JSON file containing the secrets and credentials exposed by this source.
watch: bool (optional, default: false)
When enabled, heimdall watches the file for changes and reloads the provider automatically when the file is modified. If the updated file is invalid, the reload is rejected and the last known good state is kept.

secret_management:
  my_file_source:
    type: file
    config:
      path: /etc/heimdall/secrets.yaml
      watch: true

The file contents follow the same structure as the config map of the inline provider - each top-level entry is addressed by its selector and represents either a plain secret value or a structured credentials object. Nesting is not supported; all entries must be top-level keys.

api-token: some_api_token
oauth-github:
  client_id: heimdall
  client_secret: VerySecret!
redis:
  username: Aladdin
  password: SesameOpen!

Avoid storing sensitive values in plain text on disk or in version control. Consider using secrets injection mechanism (e.g., a Kubernetes Secret mounted as a volume) to protect the file at rest.

Selector

The selector is the top-level key in the file, for example api-token, oauth-github, or redis.

Inline

The inline secret provider defines secret material directly inside the heimdall configuration. It is intended for local development, integration tests, or deployments where actual values are injected via environment variables.

To configure this provider, specify inline as provider type. The config block contains the entries exposed by this provider, addressed by their key name as the selector.

Each entry is either:

a plain string, exposed as a Secret, or
a YAML map, exposed as Credentials. The map keys must match what the consuming component expects.

secret_management:
  my_inline_source:
    type: inline
    config:
      github-token: "${GITHUB_TOKEN}"          (1)
      oauth-github:                            (2)
        client_id: heimdall
        client_secret: "${GITHUB_CLIENT_SECRET}"

1	A plain string secret, referenced with `selector: github-token`.
2	A credentials object, referenced with `selector: oauth-github`.

Selector

The selector is the top-level key under config. Nesting is not supported; all entries must be top-level keys.

Avoid placing sensitive values as literal strings in the configuration file. Use environment variable interpolation (as shown above) so that secrets are never stored in plain text on disk or in version control.

Last updated on Jun 3, 2026

Caching Security