Skip to content

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:

  1. Place the PEM encoded private key in a file named <kid>.pem (e.g., my-custom-key.pem).
  2. 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 
-----BEGIN EC PRIVATE KEY-----
MIHcAgEBBEIBSH8dWhCVW1eBH6wubSLpdv3kqLpIFk8zkbdtWU43YCKaWa0GhSOG
88yp6j2FmrXyte7v69FtBvKS08mGWEdD+gugBwYFK4EEACOhgYkDgYYABAHVNodZ
NZeQcXKnwNqb8dWFcZaAYxRb7Iq3NCRpbKXaaVLS+5+s+Rmvh7BpIuOBMXxCmWe3
WMB7tQrXYueoaGnvrQA4D9ZSoGBZv0ZXh4w5q6Op2LNya5aEwJejvrSCyRyRqgUZ
jABzf/DoMvsjNfroP5SizcfYeRUB2L4A1Tn1BPbsRQ==
-----END EC 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
  • EdDSA (ed25519)
  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512
config.yaml 
signing:
    federation:
        alg: EdDSA

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

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.

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
  • EdDSA (ed25519)
  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512

By default, all supported algorithms are allowed.

config.yaml 
signing:
    oidc:
        algs: 
            - ES512
            - ES384
            - ES256
            - EdDSA

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

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.