Federation

required

Under the federation option configuration related to OpenID Federation is set.

`entity_id`¶

uri required

The entity_id option is used to set the Federation Entity ID.

config.yaml

federation:
    entity_id: https://example.com

`client_name`¶

string OFFA - Openid Federation Forward Auth optional

The client_name option is used to set a custom client name.

config.yaml

federation:
    client_name: My Service

`logo_uri`¶

uri <entity_id>/static/img/offa-text.svg optional

The logo_uri option is used to set a custom logo uri. By default, the OFFA logo is used.

config.yaml

federation:
    logo_uri: https://static.example.com/logo.png

`scopes`¶

list of strings recommended

The scopes option is used to set which scopes should be requested from the OpenID Providers.

config.yaml

federation:
    scopes:
        - openid
        - profile
        - email

`trust_anchors`¶

list required

The trust_anchors option is used to specify the Trust Anchors that should be used.

config.yaml

federation:
    trust_anchors:
        - entity_id: https://ta.example.com
        - entity_id: https://other-ta.example.org
          jwks: {...}

For each list element the following options are defined:

`entity_id`¶

uri required

The entity_id of the Trust Anchor.

`jwks`¶

jwks recommended

The jwks of the Trust Anchor that was obtained out-of-band. If omitted, it will be obtained from the Trust Anchor's Entity Configuration and implicitly trusted. In that case you are trusting TLS.

Tip

We recommend to provide the jwks as json. json is valid yaml and can just be included. This way you can pass the whole jwks in a single line.

`authority_hints`¶

list of uris required

The authority_hints option is used to specify the Entity IDs of Federation Entities that are direct superior to OFFA and that issue a statement about OFFA.

config.yaml

federation:
    authority_hints:
        - https://ia.example.com

`organization_name`¶

string optional

The organization_name option is used to set the organization name published in the OpenID Federation Entity Configuration.

config.yaml

federation:
    organization_name: Example Organization

`key_storage`¶

directoy path required

The key_storage option is used to set a directory where signing keys are stored. To provide a pre-created signing key to OFFA place it in this directory. OFFA will use the signing key from the file fed.signing.key as the federation signing key and the key from the file oidc.signing.key for the OIDC related signing.

Tip

Currently only the ES512 signing algorithm is supported. OFFA will support additional keys in the future. But currently the key must use the P-521 curve.

Also 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

config.yaml

federation:
    key_storage: /data

`filter_to_automatic_ops`¶

boolean false optional

The filter_to_automatic_ops option is currently unused.

config.yaml

federation:
    filter_to_automatic_ops: true

`trust_marks`¶

list of trust mark configs optional

The trust_marks option is used to set Trust Marks that should be published in the Entity Configuration.

config.yaml

federation:
    trust_marks:
        - trust_mark_type: https://example.com/tm
          trust_mark_issuer: https://example.com/tmi
          refresh: true
          min_lifetime: 300
          refresh_grace_period: 7200

Each Trust Mark Config has the following options defined:

`trust_mark_type`¶

string required

The trust_mark_type option sets the Identifier for the type of this Trust Mark.

`trust_mark_issuer`¶

uri required if trust_mark_jwt not given

The trust_mark_issuer option is used to set the Entity ID of the Trust Mark Issuer of this Trust Mark.

Either a Trust Mark JWT (trust_mark_jwt) must be given or the Trust Mark Issuer (trust_mark_issuer).

If this option is given, refresh will be set to true and OFFA will obtain Trust Mark JWTs for this Trust Mark Type dynamically.

`trust_mark_jwt`¶

string required if trust_mark_issuer not given

The trust_mark_jwt option is used to set a Trust Mark JWT string. This will be published in the Entity Configuration. If the set Trust Mark JWT expires, it either must be manually updated before expiration, or automatic refreshing must be enabled through the refresh option.

`refresh`¶

boolean false optional

The refresh option indicates if this Trust Mark should automatically be refreshed. If set to true, OFFA will fetch a new Trust Mark JWT from the Trust Mark Issuer before the old one expires, assuring that always a valid Trust Mark JWT is published in the Entity Configuration.

`min_lifetime`¶

integer 10 optional

The min_lifetime option is used to set a minimum lifetime in seconds on this Trust Mark. If refresh is set to true OFFA will assure that the Trust Mark JWT published in the Entity Configuration will not expire before this lifetime whenever an Entity Configuration is requested.

`refresh_grace_period`¶

integer 3600 optional

The refresh_grace_period option is used to set a grace period given in seconds. The default grace period is one hour. If refresh is set to true, OFFA checks if the Trust Mark expires within the defined grace period, whenever its Entity Configuration is requested. If the Trust Mark expires within the grace period the old (but still valid) Trust Mark JWT will still be included in the Entity Configuration, but in parallel OFFA will refresh it by requesting a new Trust Mark JWT from the Trust Mark Issuer.

This allows OFFA to proactively request Trust Mark JWTs that are expiring soon in the background.

`use_resolve_endpoint`¶

boolean false optional

The use_resolve_endpoint option indicates if OFFA uses an external resolver (from the federation) to resolve Trust Chains or does the resolving by its own. It is generally more performant to rely on an external resolver.

config.yaml

federation:
    use_resolve_endpoint: true

`use_entity_collection_endpoint`¶

boolean false optional

The use_entity_collection_endpoint option indicates if OFFA uses an external entity collection endpoint (from the federation) to collect OpenID Providers in the federation. The collected providers are used to give the user a provider selection to they can choose the provider they want to use. It is generally more performant to rely on an external endpoint.

config.yaml

federation:
    use_entity_collection_endpoint: true

`entity_collection_interval`¶

integer 5 optional

The entity_collection_interval option defines in which interval OFFA will query the Entity Collection Endpoint or do entity collection on its own. The time is given in minutes!

config.yaml

federation:
    entity_collection_interval: 60

Federation

entity_id¶

client_name¶

logo_uri¶

scopes¶

trust_anchors¶

entity_id¶

jwks¶

authority_hints¶

organization_name¶

key_storage¶

filter_to_automatic_ops¶

trust_marks¶

trust_mark_type¶

trust_mark_issuer¶

trust_mark_jwt¶

refresh¶

min_lifetime¶

refresh_grace_period¶

use_resolve_endpoint¶

use_entity_collection_endpoint¶

entity_collection_interval¶

`entity_id`¶

`client_name`¶

`logo_uri`¶

`scopes`¶

`trust_anchors`¶

`entity_id`¶

`jwks`¶

`authority_hints`¶

`organization_name`¶

`key_storage`¶

`filter_to_automatic_ops`¶

`trust_marks`¶

`trust_mark_type`¶

`trust_mark_issuer`¶

`trust_mark_jwt`¶

`refresh`¶

`min_lifetime`¶

`refresh_grace_period`¶

`use_resolve_endpoint`¶

`use_entity_collection_endpoint`¶

`entity_collection_interval`¶