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.

To provide a pre-created signing key to OFFA place it in this directory. OFFA will use the signing key from the file federation_<alg>.pem as the federation signing key and the key from the file oidc_<alg>.pem for the OIDC related signing.

Tip

The private key must be PEM encoded. One does not need to provide a public key. The public key is derived from the private key.

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.

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 it was not provided externally.

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.

old_keys_kept_in_jwks

number 0 optional

The old_keys_kept_in_jwks option sets a number of old keys that are still published in the jwks in the entity configuration. This option should only be changed when it is needed. Usually, it will not be required to publish old keys here.

oidc

Under the oidc option the OIDC signing is configured.

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 it was not provided externally.

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.

old_keys_kept_in_jwks

number 0 optional

The old_keys_kept_in_jwks option sets a number of old keys that are still published in the jwks in the entity configuration. This option should only be changed when it is needed. Usually, it will not be required to publish old keys here.