RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
authelia/docs/content/en/configuration/identity-providers/openid-connect/clients.md

414 lines
19 KiB
Markdown
Raw Normal View History

feat(oidc): private_key_jwt client auth (#5280) This adds support for the private_key_jwt client authentication method. Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com> Co-authored-by: Amir Zarrinkafsh <nightah@me.com>
2023-05-15 00:32:10 +00:00
---
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-08T13:38:08+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 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: 1w
enforce_par: false
enforce_pkce: false
pkce_challenge_method: S256
token_endpoint_auth_method: ''
token_endpoint_auth_signing_alg: RS256
id_token_signing_alg: RS256
request_object_signing_alg: RS256
userinfo_signing_alg: none
```
## 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.
### 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` |
### 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.
### 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.
### 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.
### 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.
##### 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 [issuer_certificate_chain](#issuercertificatechain) is provided the private key must include matching public
key data for the first certificate in the chain.
## 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