authelia

21 KiB

Raw Permalink Blame History

title

description

lead

date

draft

images

weight

toc

OpenID Connect 1.0 Clients

OpenID Connect 1.0 Registered Clients Configuration

Authelia can operate as an OpenID Connect 1.0 Provider. This section describes how to configure the registered clients.

2023-05-15T10:32:10+10:00

false

configuration

parent
openid-connect

190220

true

This section covers specifics regarding configuring the providers registered clients for OpenID Connect 1.0. For the provider specific configuration and information not related to clients see the OpenID Connect 1.0 Provider documentation.

More information about OpenID Connect 1.0 can be found in the roadmap and in the integration documentation.

Configuration

The following snippet provides a configuration example for the OpenID Connect 1.0 Registered Clients. This is not intended for production use it's used to provide context and an indentation example.

identity_providers:
  oidc:
    clients:
      - id: 'myapp'
        description: 'My Application'
        secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng'  # The digest of 'insecure_secret'.
        sector_identifier: ''
        public: false
        redirect_uris:
          - 'https://oidc.example.com:8080/oauth2/callback'
        audience: []
        scopes:
          - 'openid'
          - 'groups'
          - 'email'
          - 'profile'
        grant_types:
          - 'refresh_token'
          - 'authorization_code'
        response_types:
          - 'code'
        response_modes:
          - 'form_post'
          - 'query'
          - 'fragment'
        authorization_policy: 'two_factor'
        consent_mode: 'explicit'
        pre_configured_consent_duration: '1 week'
        enforce_par: false
        enforce_pkce: false
        pkce_challenge_method: 'S256'
        id_token_signing_alg: 'RS256'
        id_token_signing_key_id: ''
        userinfo_signing_alg: 'none'
        userinfo_signing_key_id: ''
        request_object_signing_alg: 'RS256'
        token_endpoint_auth_signing_alg: 'RS256'
        token_endpoint_auth_method: ''

Options

id

The Client ID for this client. It must exactly match the Client ID configured in the application consuming this client.

description

{{< confkey type="string" default="same as id" required="no" >}}

A friendly description for this client shown in the UI. This defaults to the same as the ID.

secret

The shared secret between Authelia and the application consuming this client. This secret must match the secret configured in the application.

This secret must be generated by the administrator and can be done by following the How Do I Generate Client Secrets FAQ.

This must be provided when the client is a confidential client type, and must be blank when using the public client type. To set the client type to public see the public configuration option.

sector_identifier

Important Note: because adjusting this option will inevitably change the sub claim of all tokens generated for the specified client, changing this should cause the relying party to detect all future authorizations as completely new users.

Must be an empty string or the host component of a URL. This is commonly just the domain name, but may also include a port.

Authelia utilizes UUID version 4 subject identifiers. By default the public Subject Identifier Type is utilized for all clients. This means the subject identifiers will be the same for all clients. This configuration option enables Pairwise Identifier Algorithm for this client, and configures the sector identifier utilized for both the storage and the lookup of the subject identifier.

All clients who do not have this configured will generate the same subject identifier for a particular user regardless of which client obtains the ID token.
All clients which have the same sector identifier will:
1. have the same subject identifier for a particular user when compared to clients with the same sector identifier.
2. have a completely different subject identifier for a particular user whe compared to:
  1. any client with the public subject identifier type.
  2. any client with a differing sector identifier.

In specific but limited scenarios this option is beneficial for privacy reasons. In particular this is useful when the party utilizing the Authelia OpenID Connect 1.0 Authorization Server is foreign and not controlled by the user. It would prevent the third party utilizing the subject identifier with another third party in order to track the user.

Keep in mind depending on the other claims they may still be able to perform this tracking and it is not a silver bullet. There are very few benefits when utilizing this in a homelab or business where no third party is utilizing the server.

public

This enables the public client type for this client. This is for clients that are not capable of maintaining confidentiality of credentials, you can read more about client types in RFC6749 Section 2.1. This is particularly useful for SPA's and CLI tools. This option requires setting the client secret to a blank string.

redirect_uris

A list of valid callback URIs this client will redirect to. All other callbacks will be considered unsafe. The URIs are case-sensitive and they differ from application to application - the community has provided a list of URL´s for common applications.

Some restrictions that have been placed on clients and their redirect URIs are as follows:

If a client attempts to authorize with Authelia and its redirect URI is not listed in the client configuration the attempt to authorize will fail and an error will be generated.
The redirect URIs are case-sensitive.
The URI must include a scheme and that scheme must be one of http or https.

audience

A list of audiences this client is allowed to request.

scopes

{{< confkey type="list(string)" default="openid, groups, profile, email" required="no" >}}

A list of scopes to allow this client to consume. See scope definitions for more information. The documentation for the application you are trying to configure OpenID Connect 1.0 for will likely have a list of scopes or claims required which can be matched with the above guide.

grant_types

{{< confkey type="list(string)" default="authorization_code" required="no" >}}

Important Note: It is recommended that this isn't configured at this time unless you know what you're doing.

The list of grant types this client is permitted to use in order to obtain access to the relevant tokens.

See the Grant Types section of the OpenID Connect 1.0 Integration Guide for more information.

response_types

Security Note: It is recommended that only the code response type (i.e. the default) is used. The other response types are not as secure as this response type.

A list of response types this client supports. If a response type not in this list is requested by a client then an error will be returned to the client. The response type indicates the types of values that are returned to the client.

See the Response Types section of the OpenID Connect 1.0 Integration Guide for more information.

response_modes

{{< confkey type="list(string)" default="form_post, query" required="no" >}}

Important Note: It is recommended that this isn't configured at this time unless you know what you're doing.

A list of response modes this client supports. If a response mode not in this list is requested by a client then an error will be returned to the client. The response mode controls how the response type is returned to the client.

See the Response Modes section of the OpenID Connect 1.0 Integration Guide for more information.

The default values are based on the response_types values. When the response_types values include the code type then the query response mode will be included. When any other type is included the fragment response mode will be included. It's important to note at this time we do not support the none response type, but when it is supported it will include the query response mode.

authorization_policy

The authorization policy for this client: either one_factor or two_factor.

consent_mode

Important Note: the implicit consent mode is not technically part of the specification. It theoretically could be misused in certain conditions specifically with the public client type or when the client credentials (i.e. client secret) has been exposed to an attacker. For these reasons this mode is discouraged.

Configures the consent mode. The following table describes the different modes:

Value	Description
auto	Automatically determined (default). Uses `explicit` unless pre_configured_consent_duration is specified in which case uses `pre-configured`.
explicit	Requires the user provide unique explicit consent for every authorization.
implicit	Automatically assumes consent for every authorization, never asking the user if they wish to give consent.
pre-configured	Allows the end-user to remember their consent for the pre_configured_consent_duration.

pre_configured_consent_duration

Note: This setting uses the duration notation format. Please see the common options documentation for information on this format.

Specifying this in the configuration without a consent consent_mode enables the pre-configured mode. If this is specified as well as the consent_mode then it only has an effect if the consent_mode is pre-configured or auto.

The period of time dictates how long a users choice to remember the pre-configured consent lasts.

Pre-configured consents are only valid if the subject, client id are exactly the same and the requested scopes/audience match exactly with the granted scopes/audience.

enforce_par

This configuration option enforces the use of a Pushed Authorization Requests flow for this registered client. To enforce it for all clients see the global pushed_authorizations enforce provider configuration option.

enforce_pkce

This configuration option enforces the use of PKCE for this registered client. To enforce it for all clients see the global enforce_pkce provider configuration option.

pkce_challenge_method

This setting enforces the use of the specified PKCE challenge method for this individual client. This setting also effectively enables the enforce_pkce option for this client.

Valid values are an empty string, plain, or S256. It should be noted that S256 is strongly recommended if the relying party supports it.

id_token_signing_alg

The algorithm used to sign the ID Tokens in the token responses.

See the response object section of the integration guide for more information including the algorithm column for supported values. In addition to the values listed we also support none as a value for this endpoint.

The algorithm chosen must have a key configured in the issuer_private_keys section to be considered valid.

This option has no effect if the id_token_signing_key_id is specified as the algorithm is automatically assumed by the configured key.

id_token_signing_key_id

The key id of the JWK used to sign the ID Tokens in the token responses. This option takes precedence over id_token_signing_alg. The value of this must one of those provided or calculated in the issuer_private_keys.

userinfo_signing_alg

The algorithm used to sign the userinfo endpoint responses.

The algorithm chosen must have a key configured in the issuer_private_keys section to be considered valid.

This option has no effect if the userinfo_signing_key_id is specified as the algorithm is automatically assumed by the configured key.

userinfo_signing_key_id

The key id of the JWK used to sign the userinfo endpoint responses in the token responses. This option takes precedence over userinfo_signing_alg. The value of this must one of those provided or calculated in the issuer_private_keys.

request_object_signing_alg

The JWT signing algorithm accepted for request objects.

See the request object section of the integration guide for more information including the algorithm column for supported values.

token_endpoint_auth_method

The registered client authentication mechanism used by this client for the Token Endpoint. If no method is defined the confidential client type will accept any supported method. The public client type defaults to none as this is required by the specification. This may be required as a breaking change in future versions. Supported values are client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, and none.

See the integration guide for more information.

token_endpoint_auth_signing_alg

The JWT signing algorithm accepted when the token_endpoint_auth_method is configured as client_secret_jwt or private_key_jwt.

See the request object section of the integration guide for more information including the algorithm column for supported values.

It's recommended that you specifically configure this when the following options are configured to specific values otherwise we assume the default value:

Configuration Option	Value	Default
token_endpoint_auth_method	`private_key_jwt`	`RS256`
token_endpoint_auth_method	`client_secret_jwt`	`HS256`

public_keys

This section configures the trusted JSON Web Keys or JWKS for this registered client. This can either be static values (recommended) or a URI using the https scheme. This section is situational required. These are used to validate the JWT assertions from clients.

Required when the following options are configured:

request_object_signing_alg
token_endpoint_auth_signing_alg

Required when the following options are configured to specific values:

token_endpoint_auth_method: private_key_jwt

uri

The fully qualified, https scheme, and appropriately signed URI for the JWKS endpoint that implements RFC7517 Section 5. Must not be configured at the same time as values. It's recommended that you do not configure this option, but statically configure values instead.

Important Note: the URL given in this value MUST be resolvable by Authelia and MUST present a certificate signed by a certificate trusted by your environment. It is beyond our intentions to support anything other than this.

values

A list of static keys.

key_id

The Key ID used to match the request object's JWT header kid value against.

use

The key usage. Defaults to sig which is the only available option at this time.

algorithm

{{< confkey type="string" default="RS256" required="situational" >}}

The algorithm for this key. This value typically optional as it can be automatically detected based on the type of key in some situations. It is however strongly recommended this is set.

See the request object table in the integration guide for more information. The Algorithm column lists supported values, the Key column references the required key type constraints that exist for the algorithm, and the JWK Default Conditions column briefly explains the conditions under which it's the default algorithm.

key

The public key portion of the JSON Web Key.

The public key the clients use to sign/encrypt the OpenID Connect 1.0 asserted JWT's. The key is generated by the client application or the administrator of the client application.

The key MUST:

Be a PEM block encoded in the DER base64 format (RFC4648).
Be either:
- An RSA public key:
  - With a key size of at least 2048 bits.
- An ECDSA public key with one of:
  - A P-256 elliptical curve.
  - A P-384 elliptical curve.
  - A P-512 elliptical curve.

If the certificate_chain is provided the private key must include matching public key data for the first certificate in the chain.

certificate_chain

The certificate chain/bundle to be used with the key DER base64 (RFC4648) encoded PEM format used to sign/encrypt the OpenID Connect 1.0 JWT's.

Integration

To integrate Authelia's OpenID Connect 1.0 implementation with a relying party please see the integration docs.

21 KiB Raw Permalink Blame History Unescape Escape

Configuration

Options

id

description

secret

sector_identifier

public

redirect_uris

audience

scopes

grant_types

response_types

response_modes

authorization_policy

consent_mode

pre_configured_consent_duration

enforce_par

enforce_pkce

pkce_challenge_method

id_token_signing_alg

id_token_signing_key_id

userinfo_signing_alg

userinfo_signing_key_id

request_object_signing_alg

token_endpoint_auth_method

token_endpoint_auth_signing_alg

public_keys

uri

values

key_id

use

algorithm

key

certificate_chain

Integration

21 KiB

Raw Permalink Blame History