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

`client_uri`¶

uri optional

The client_uri option is used to set a client URI to be published in the relying party metadata in the entity configuration.

config.yaml

federation:
    client_uri: https://client.example.com

`display_name`¶

string optional

The display_name option is used to set a display name to be published in the relying party metadata.

config.yaml

federation:
    display_name: My Service Display Name

`description`¶

string optional

The description option is used to set a description to be published in the relying party metadata.

config.yaml

federation:
    description: This is a description of the service

`keywords`¶

list of strings optional

The keywords option is used to set keywords to be published in the relying party metadata.

config.yaml

federation:
    keywords:
        - service
        - authentication
        - federation

`contacts`¶

list of strings optional

The contacts option is used to set contact information to be published in the relying party metadata.

config.yaml

federation:
    contacts:
        - admin@example.com
        - support@example.com

`policy_uri`¶

uri optional

The policy_uri option is used to set a URI to the privacy policy to be published in the relying party metadata.

config.yaml

federation:
    policy_uri: https://example.com/privacy-policy

`tos_uri`¶

uri optional

The tos_uri option is used to set a URI to the terms of service to be published in the relying party metadata.

config.yaml

federation:
    tos_uri: https://example.com/terms-of-service

`information_uri`¶

uri optional

The information_uri option is used to set a URI to additional information about the service to be published in the relying party metadata.

config.yaml

federation:
    information_uri: https://example.com/info

`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

`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

`organization_uri`¶

uri optional

The organization_uri option is used to set a URI to the organization's website to be published in the relying party metadata.

config.yaml

federation:
    organization_uri: https://organization.example.com

`extra_rp_metadata`¶

mapping / object optional

The extra_rp_metadata option is used to add custom key-value pairs to the relying party metadata in the entity configuration.

config.yaml

federation:
    extra_rp_metadata:
        custom_field: custom_value
        another_field: another_value

`extra_entity_configuration_data`¶

mapping / object optional

The extra_entity_configuration_data option is used to add custom key-value pairs to the entity configuration.

config.yaml

federation:
    extra_entity_configuration_data:
        custom_entity_field: custom_value
        another_entity_field: another_value

`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

`configuration_lifetime`¶

duration 1 day optional

The configuration_lifetime option sets the lifetime of Entity Configurations, i.e. this options defines for how long the Entity Configuration JWTs are valid.

config.yaml

federation:
    configuration_lifetime: 1w

`

`key_storage`¶

deprecated

The key_storage option is deprecated. Use signing.key_storage instead.

`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`¶

duration 5 minutes optional

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

config.yaml

federation:
    entity_collection_interval: 1h

Federation

entity_id¶

client_name¶

client_uri¶

display_name¶

description¶

keywords¶

contacts¶

policy_uri¶

tos_uri¶

information_uri¶

logo_uri¶

organization_name¶

organization_uri¶

extra_rp_metadata¶

extra_entity_configuration_data¶

scopes¶

trust_anchors¶

entity_id¶

jwks¶

authority_hints¶

configuration_lifetime¶

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`¶

`client_uri`¶

`display_name`¶

`description`¶

`keywords`¶

`contacts`¶

`policy_uri`¶

`tos_uri`¶

`information_uri`¶

`logo_uri`¶

`organization_name`¶

`organization_uri`¶

`extra_rp_metadata`¶

`extra_entity_configuration_data`¶

`scopes`¶

`trust_anchors`¶

`entity_id`¶

`jwks`¶

`authority_hints`¶

`configuration_lifetime`¶

`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`¶