Signing

required

Under the signing config option the signatures are configured.

`key_storage`¶

directory path required

The key_storage option specifies the path to a directory that contains the private signing key(s), as well as a key set for public keys.

We strongly recommend letting OFFA auto-generate the keys. By default, generate_keys: true is enabled in both the federation and oidc sections.

Legacy File Format Migration

If you are upgrading from an older version of OFFA and have legacy files like federation_<alg>.pem, oidc_<alg>.pem, or keys.jwks, they will be automatically migrated to the new file format upon startup.

Providing Custom Keys¶

If you prefer to manually supply your own keys, you can do so by placing them into the key_storage directory:

Place the PEM encoded private key in a file named <kid>.pem (e.g., my-custom-key.pem).
Create or edit federation_public.json (or oidc_public.json) to include the public key metadata. This file is a JSON object mapping the Key ID (kid) to its configuration.

Example federation_public.json structure

{
  "my-custom-kid": {
    "kid": "my-custom-kid",
    "key": {
      "kty": "EC",
      "crv": "P-521",
      "x": "...",
      "y": "...",
      "kid": "my-custom-kid",
      "alg": "ES512"
    },
    "iat": 1714392000
  }
}

Tip

The private key must be PEM encoded.

Example Private Key

config.yaml

signing:
    key_storage: /path/to/keys

`federation`¶

Under the federation option the federation signing is configured.

`generate_keys`¶

boolean true optional

The generate_keys option enables the automatic generation of signing keys. We strongly recommend leaving this as true. If disabled (false), OFFA will not generate keys when none are found and will require manually provided keys.

config.yaml

signing:
    federation:
        generate_keys: false

`alg`¶

enum ES512 optional

The signing algorithm that is used.

Supported values are:

ES256
ES384
ES512
ES256K (ECDSA over the secp256k1 curve)
EdDSA (EdDSA, ed25519)
Ed25519 (Ed25519)
Ed448 (Ed448)
RS256
RS384
RS512
PS256
PS384
PS512
ML-DSA-44 (post-quantum, NIST FIPS 204)
ML-DSA-65 (post-quantum, NIST FIPS 204)
ML-DSA-87 (post-quantum, NIST FIPS 204)
ML-DSA-44-ES256 (composite ML-DSA-44 + ES256)
ML-DSA-65-ES256 (composite ML-DSA-65 + ES256)
ML-DSA-87-ES384 (composite ML-DSA-87 + ES384)
ML-DSA-44-Ed25519 (composite ML-DSA-44 + Ed25519)
ML-DSA-65-Ed25519 (composite ML-DSA-65 + Ed25519)
ML-DSA-87-Ed448 (composite ML-DSA-87 + Ed448)

config.yaml

signing:
    federation:
        alg: Ed25519

`rsa_key_len`¶

integer 2048 optional

The rsa_key_len option defines the length of the generated key, if an RSA-based signing key is used and the key is generated by OFFA because generate_keys is set to true.

config.yaml

signing:
    federation:
        alg: PS256
        rsa_key_len: 4096

`automatic_key_rollover`¶

object / mapping optional

Under the automatic_key_rollover option key rollover / key rotation is configured.

config.yaml

signing:
    key_storage: /path/to/keys
    federation:
        automatic_key_rollover:
            enabled: true
            interval: 30d
            overlap: 1h
            key_announcement_lead_time: 7d

`enabled`¶

boolean false optional

To enable automatic key rollover / rotation set enabled to true. If enabled, OFFA will automatically generate a new signing key when needed (according to the configured interval). The current and next public key are published in the entity configuration; this allows other entities to already have the public key of the next signing key when it will be used.

`interval`¶

duration 600000 seconds = ca. 1 week optional

The interval option is used to set the interval at which keys should be rotated, i.e. this defines the lifetime of a key. This cannot be smaller than the lifetime of the Entity Configuration.

`overlap`¶

duration 1h optional

The overlap period between the current and next key. During this window, OFFA transitions to using the new key while the old key's public key is still published.

`key_announcement_lead_time`¶

duration max(5 * configuration_lifetime, 24h) optional

The key_announcement_lead_time controls how far in advance a new signing key is published in the JWKS before it becomes the active signing key. This ensures clients that are temporarily unavailable (e.g., due to downtime or network issues) have sufficient time to fetch the new key before the old one is retired.

If not set (or zero), the default of max(5 * configuration_lifetime, 24h) is used. If the configured value is shorter than the Entity Configuration lifetime, the EC lifetime is used as a minimum and a warning is logged.

Takes precedence over the default, but is overridden by key_announcement_lead_time_ec_multiplier if that is also set.

`key_announcement_lead_time_ec_multiplier`¶

number (float) optional

If set to a value greater than 0, the key announcement lead time is computed as this multiplier times the Entity Configuration lifetime. For example, 5 means the new key is published 5 EC lifetimes before it becomes active. This takes precedence over key_announcement_lead_time.

The result is clamped to a minimum of the EC lifetime.

`oidc`¶

Under the oidc option the OIDC signing is configured.

`generate_keys`¶

boolean true optional

The generate_keys option enables the automatic generation of signing keys. We strongly recommend leaving this as true. If disabled (false), OFFA will not generate keys when none are found and will require manually provided keys.

config.yaml

signing:
    oidc:
        generate_keys: false

`algs`¶

list of enum strings optional

The algs config option is used to set the list of supported signing algorithms. This should only be set if there are reasons to disallow certain algorithms. The order also gives a preference where the most preferred algorithm is the first one in the list.

OFFA will select a signing algorithm for OIDC communication based on this list and the signing algorithms supported by the OP.

Supported values are:

ES256
ES384
ES512
ES256K (ECDSA over the secp256k1 curve)
EdDSA (EdDSA, ed25519)
Ed25519 (Ed25519)
Ed448 (Ed448)
RS256
RS384
RS512
PS256
PS384
PS512
ML-DSA-44 (post-quantum, NIST FIPS 204)
ML-DSA-65 (post-quantum, NIST FIPS 204)
ML-DSA-87 (post-quantum, NIST FIPS 204)
ML-DSA-44-ES256 (composite ML-DSA-44 + ES256)
ML-DSA-65-ES256 (composite ML-DSA-65 + ES256)
ML-DSA-87-ES384 (composite ML-DSA-87 + ES384)
ML-DSA-44-Ed25519 (composite ML-DSA-44 + Ed25519)
ML-DSA-65-Ed25519 (composite ML-DSA-65 + Ed25519)
ML-DSA-87-Ed448 (composite ML-DSA-87 + Ed448)

By default, the following algorithms are allowed: - ES256 - ES384 - ES512 - Ed25519 (Ed25519) - Ed448 (Ed448) - RS256 - RS384 - RS512 - PS256 - PS384 - PS512

config.yaml

signing:
    oidc:
        algs: 
            - ES512
            - ES384
            - ES256
            - Ed448

`default_alg`¶

enum ES512 optional

The default_alg option is used to set a default signing algorithm, that should be used if the OP does not indicate which algorithms it supports.

config.yaml

signing:
    oidc:
        default_alg: RS512

`rsa_key_len`¶

integer 2048 optional

The rsa_key_len option defines the length of the generated key, if an RSA-based signing key is used and the key is generated by OFFA because generate_keys is set to true.

config.yaml

signing:
    oidc:
        rsa_key_len: 4096

`automatic_key_rollover`¶

object / mapping optional

Under the automatic_key_rollover option key rollover / key rotation is configured.

config.yaml

signing:
    key_storage: /path/to/keys
    oidc:
        automatic_key_rollover:
            enabled: true
            interval: 30d
            overlap: 1h
            key_announcement_lead_time: 7d

`enabled`¶

boolean false optional

To enable automatic key rollover / rotation set enabled to true. If enabled, OFFA will automatically generate a new signing key when needed (according to the configured interval). The current and next public key are published in the entity configuration; this allows other entities to already have the public key of the next signing key when it will be used.

`interval`¶

duration 600000 seconds = ca. 1 week optional

The interval option is used to set the interval at which keys should be rotated, i.e. this defines the lifetime of a key. This cannot be smaller than the lifetime of the Entity Configuration.

`overlap`¶

duration 1h optional

The overlap period between the current and next key. During this window, OFFA transitions to using the new key while the old key's public key is still published.

`key_announcement_lead_time`¶

duration max(5 * configuration_lifetime, 24h) optional

The key_announcement_lead_time controls how far in advance a new signing key is published in the JWKS before it becomes the active signing key. This ensures clients that are temporarily unavailable (e.g., due to downtime or network issues) have sufficient time to fetch the new key before the old one is retired.

If not set (or zero), the default of max(5 * configuration_lifetime, 24h) is used. If the configured value is shorter than the Entity Configuration lifetime, the EC lifetime is used as a minimum and a warning is logged.

Takes precedence over the default, but is overridden by key_announcement_lead_time_ec_multiplier if that is also set.

`key_announcement_lead_time_ec_multiplier`¶

number (float) 0 (disabled) optional

If set to a value greater than 0, the key announcement lead time is computed as this multiplier times the Entity Configuration lifetime. For example, 5 means the new key is published 5 EC lifetimes before it becomes active. This takes precedence over key_announcement_lead_time.

The result is clamped to a minimum of the EC lifetime.

Signing

key_storage¶

Providing Custom Keys¶

federation¶

generate_keys¶

alg¶

rsa_key_len¶

automatic_key_rollover¶

enabled¶

interval¶

overlap¶

key_announcement_lead_time¶

key_announcement_lead_time_ec_multiplier¶

oidc¶

generate_keys¶

algs¶

default_alg¶

rsa_key_len¶

automatic_key_rollover¶

enabled¶

interval¶

overlap¶

key_announcement_lead_time¶

key_announcement_lead_time_ec_multiplier¶

`key_storage`¶

`federation`¶

`generate_keys`¶

`alg`¶

`rsa_key_len`¶

`automatic_key_rollover`¶

`enabled`¶

`interval`¶

`overlap`¶

`key_announcement_lead_time`¶

`key_announcement_lead_time_ec_multiplier`¶

`oidc`¶

`generate_keys`¶

`algs`¶

`default_alg`¶

`rsa_key_len`¶

`automatic_key_rollover`¶

`enabled`¶

`interval`¶

`overlap`¶

`key_announcement_lead_time`¶

`key_announcement_lead_time_ec_multiplier`¶