--- title: "OpenID Connect 1.0 Clients" description: "OpenID Connect 1.0 Registered Clients Configuration" lead: "Authelia can operate as an OpenID Connect 1.0 Provider. This section describes how to configure the registered clients." date: 2023-05-15T10:32:10+10:00 draft: false images: [] menu: configuration: parent: "openid-connect" weight: 190220 toc: 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](provider.md) documentation. More information about OpenID Connect 1.0 can be found in the [roadmap](../../../roadmap/active/openid-connect.md) and in the [integration](../../../integration/openid-connect/introduction.md) 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. ```yaml 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 {{< confkey type="string" required="yes" >}} 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 {{< confkey type="string" required="situational" >}} 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](../../../integration/openid-connect/frequently-asked-questions.md#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](#public) configuration option. ### sector_identifier {{< confkey type="string" required="no" >}} *__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. 1. 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. 2. 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 {{< confkey type="bool" default="false" required="no" >}} 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](#secret) to a blank string. ### redirect_uris {{< confkey type="list(string)" required="yes" >}} 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](../../../integration/openid-connect/introduction.md). Some restrictions that have been placed on clients and their redirect URIs are as follows: 1. 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. 2. The redirect URIs are case-sensitive. 3. The URI must include a scheme and that scheme must be one of `http` or `https`. ### audience {{< confkey type="list(string)" required="no" >}} 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](../../../integration/openid-connect/introduction.md#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](../../../integration/openid-connect/introduction.md#grant-types) section of the [OpenID Connect 1.0 Integration Guide](../../../integration/openid-connect/introduction.md#grant-types) for more information. ### response_types {{< confkey type="list(string)" default="code" required="no" >}} *__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](../../../integration/openid-connect/introduction.md#response-types) section of the [OpenID Connect 1.0 Integration Guide](../../../integration/openid-connect/introduction.md#response-types) 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](../../../integration/openid-connect/introduction.md#response-modes) section of the [OpenID Connect 1.0 Integration Guide](../../../integration/openid-connect/introduction.md#response-modes) for more information. The default values are based on the [response_types](#responsetypes) values. When the [response_types](#responsetypes) 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 {{< confkey type="string" default="two_factor" required="no" >}} The authorization policy for this client: either `one_factor` or `two_factor`. ### consent_mode {{< confkey type="string" default="auto" required="no" >}} *__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]: #preconfiguredconsentduration ### pre_configured_consent_duration {{< confkey type="duration" default="1w" required="no" >}} *__Note:__ This setting uses the [duration notation format](../../prologue/common.md#duration-notation-format). Please see the [common options](../../prologue/common.md#duration-notation-format) 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. [consent_mode]: #consentmode ### enforce_par {{< confkey type="boolean" default="false" required="no" >}} 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.md#enforce) provider configuration option. ### enforce_pkce {{< confkey type="bool" default="false" required="no" >}} This configuration option enforces the use of [PKCE] for this registered client. To enforce it for all clients see the global [enforce_pkce](provider.md#enforcepkce) provider configuration option. ### pkce_challenge_method {{< confkey type="string" default="" required="no" >}} This setting enforces the use of the specified [PKCE] challenge method for this individual client. This setting also effectively enables the [enforce_pkce](#enforcepkce) 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 {{< confkey type="string" default="RS256" required="no" >}} The algorithm used to sign the ID Tokens in the token responses. See the response object section of the [integration guide](../../../integration/openid-connect/introduction.md#response-object) 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](provider.md#issuerprivatekeys) section to be considered valid. This option has no effect if the [id_token_signing_key_id](#idtokensigningkid) is specified as the algorithm is automatically assumed by the configured key. ### id_token_signing_key_id {{< confkey type="string" required="no" >}} 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](#idtokensigningalg). The value of this must one of those provided or calculated in the [issuer_private_keys](provider.md#issuerprivatekeys). ### userinfo_signing_alg {{< confkey type="string" default="none" required="no" >}} The algorithm used to sign the userinfo endpoint responses. See the response object section of the [integration guide](../../../integration/openid-connect/introduction.md#response-object) 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](provider.md#issuerprivatekeys) section to be considered valid. This option has no effect if the [userinfo_signing_key_id](#userinfosigningkeyid) is specified as the algorithm is automatically assumed by the configured key. ### userinfo_signing_key_id {{< confkey type="string" required="no" >}} 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](#userinfosigningalg). The value of this must one of those provided or calculated in the [issuer_private_keys](provider.md#issuerprivatekeys). ### request_object_signing_alg {{< confkey type="string" default="RSA256" required="no" >}} The JWT signing algorithm accepted for request objects. See the request object section of the [integration guide](../../../integration/openid-connect/introduction.md#request-object) for more information including the algorithm column for supported values. ### token_endpoint_auth_method {{< confkey type="string" default="" required="no" >}} 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](../../../integration/openid-connect/introduction.md#client-authentication-method) for more information. ### token_endpoint_auth_signing_alg {{< confkey type="string" default="RS256" required="no" >}} The JWT signing algorithm accepted when the [token_endpoint_auth_method](#tokenendpointauthmethod) is configured as `client_secret_jwt` or `private_key_jwt`. See the request object section of the [integration guide](../../../integration/openid-connect/introduction.md#request-object) 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](#tokenendpointauthsigningalg) | `private_key_jwt` | `RS256` | | [token_endpoint_auth_method](#tokenendpointauthsigningalg) | `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](#requestobjectsigningalg) - [token_endpoint_auth_signing_alg](#tokenendpointauthsigningalg) Required when the following options are configured to specific values: - [token_endpoint_auth_method](#tokenendpointauthsigningalg): `private_key_jwt` #### uri {{< confkey type="string" required="no" >}} The fully qualified, `https` scheme, and appropriately signed URI for the JWKS endpoint that implements [RFC7517 Section 5](https://datatracker.ietf.org/doc/html/rfc7517#section-5). Must not be configured at the same time as [values](#values). It's recommended that you do not configure this option, but statically configure [values](#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 {{< confkey type="list(object)" required="situational" >}} A list of static keys. ##### key_id {{< confkey type="string" required="yes" >}} The Key ID used to match the request object's JWT header `kid` value against. ##### use {{< confkey type="string" default="sig" required="no" >}} 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](../../../integration/openid-connect/introduction.md#request-object) for more information. The `Algorithm` column lists supported values, the `Key` column references the required [key](#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 {{< confkey type="string" required="yes" >}} 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](#certificatechain) is provided the private key must include matching public key data for the first certificate in the chain. ##### certificate_chain {{< confkey type="string" required="no" >}} The certificate chain/bundle to be used with the [key](#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](../../../integration/openid-connect/introduction.md). [token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration [OpenID Connect 1.0]: https://openid.net/connect/ [Token Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint [JWT]: https://datatracker.ietf.org/doc/html/rfc7519 [RFC6234]: https://datatracker.ietf.org/doc/html/rfc6234 [RFC4648]: https://datatracker.ietf.org/doc/html/rfc4648 [RFC7468]: https://datatracker.ietf.org/doc/html/rfc7468 [RFC6749 Section 2.1]: https://datatracker.ietf.org/doc/html/rfc6749#section-2.1 [PKCE]: https://datatracker.ietf.org/doc/html/rfc7636 [Authorization Code Flow]: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth [Subject Identifier Type]: https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes [Pairwise Identifier Algorithm]: https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg [Pushed Authorization Requests]: https://datatracker.ietf.org/doc/html/rfc9126