diff options
Diffstat (limited to 'docs/content/en')
5 files changed, 117 insertions, 56 deletions
diff --git a/docs/content/en/configuration/identity-providers/open-id-connect.md b/docs/content/en/configuration/identity-providers/open-id-connect.md index 89d35e63a..40b3bd695 100644 --- a/docs/content/en/configuration/identity-providers/open-id-connect.md +++ b/docs/content/en/configuration/identity-providers/open-id-connect.md @@ -451,38 +451,47 @@ A list of scopes to allow this client to consume. See 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="refresh_token, 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" >}} -*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.* +*__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. +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, fragment" required="no" >}} +{{< 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. +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. +[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. + +#### 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. #### authorization_policy @@ -522,6 +531,18 @@ The algorithm used to sign the userinfo endpoint responses. This can either be ` See the [integration guide](../../integration/openid-connect/introduction.md#user-information-signing-algorithm) for more information. +#### 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`, and `none`. + +See the [integration guide](../../integration/openid-connect/introduction.md#client-authentication-method) for +more information. + #### consent_mode {{< confkey type="string" default="auto" required="no" >}} @@ -565,6 +586,7 @@ To integrate Authelia's [OpenID Connect 1.0] implementation with a relying party [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 diff --git a/docs/content/en/integration/kubernetes/istio.md b/docs/content/en/integration/kubernetes/istio.md index c1c4927e3..60360c6b0 100644 --- a/docs/content/en/integration/kubernetes/istio.md +++ b/docs/content/en/integration/kubernetes/istio.md @@ -13,7 +13,7 @@ toc: true --- Istio uses [Envoy](../proxies/envoy.md) as an Ingress. This means it has a relatively comprehensive integration option. -Istio is supported with Authelia v4.37.0 and higher via [Envoy]'s [external authorization] filter. +Istio is supported with Authelia v4.37.0 and higher via the [Envoy] proxy [external authorization] filter. [external authorization]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz diff --git a/docs/content/en/integration/openid-connect/introduction.md b/docs/content/en/integration/openid-connect/introduction.md index 6ab7ba46c..37cca969d 100644 --- a/docs/content/en/integration/openid-connect/introduction.md +++ b/docs/content/en/integration/openid-connect/introduction.md @@ -21,8 +21,15 @@ documentation for some [OpenID Connect 1.0] Relying Party implementations. See the [configuration documentation](../../configuration/identity-providers/open-id-connect.md) for information on how to configure the Authelia [OpenID Connect 1.0] Provider. +This page is intended as an integration reference point for any implementers who wish to integrate an +[OpenID Connect 1.0] Relying Party (client application) either as a developer or user of the third party Reyling Party. + ## Scope Definitions +The following scope definitions describe each scope supported and the associated effects including the individual claims +returned by granting this scope. By default we do not issue any claims which reveal the users identity which allows +administrators semi-granular control over which claims the client is entitled to. + ### openid This is the default scope for [OpenID Connect 1.0]. This field is forced on every client by the configuration validation @@ -54,9 +61,16 @@ This scope is a special scope designed to allow applications to obtain a [Refres an application on behalf of a user. A [Refresh Token] is a special [Access Token] that allows refreshing previously issued token credentials, effectively it allows the relying party to obtain new tokens periodically. +As per [OpenID Connect 1.0] Section 11 [Offline Access] can only be granted during the [Authorization Code Flow] or a +[Hybrid Flow]. The [Refresh Token] will only ever be returned at the [Token Endpoint] when the client is exchanging +their [OAuth 2.0 Authorization Code]. + Generally unless an application supports this and actively requests this scope they should not be granted this scope via the client configuration. +It is also important to note that we treat a [Refresh Token] as single use and reissue a new [Refresh Token] during the +refresh flow. + ### groups This scope includes the groups the authentication backend reports the user is a member of in the [Claims] of the @@ -92,43 +106,21 @@ This scope includes the profile information the authentication backend reports a The following section describes advanced parameters which can be used in various endpoints as well as their related configuration options. -### Grant Types - -The following describes the various [OAuth 2.0] and [OpenID Connect 1.0] grant types and their support level. The value -field is both the required value for the `grant_type` parameter in the authorization request and the `grant_types` -configuration option. - -| Grant Type | Supported | Value | Notes | -|:-----------------------------------------------:|:---------:|:----------------------------------------------:|:-------------------------------------------------------------------:| -| [OAuth 2.0 Authorization Code] | Yes | `authorization_code` | | -| [OAuth 2.0 Resource Owner Password Credentials] | No | `password` | This Grant Type has been deprecated and should not normally be used | -| [OAuth 2.0 Client Credentials] | Yes | `client_credentials` | | -| [OAuth 2.0 Implicit] | Yes | `implicit` | This Grant Type has been deprecated and should not normally be used | -| [OAuth 2.0 Refresh Token] | Yes | `refresh_token` | | -| [OAuth 2.0 Device Code] | No | `urn:ietf:params:oauth:grant-type:device_code` | | -| - -[OAuth 2.0 Authorization Code]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 -[OAuth 2.0 Implicit]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2 -[OAuth 2.0 Resource Owner Password Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3 -[OAuth 2.0 Client Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4 -[OAuth 2.0 Refresh Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.5 -[OAuth 2.0 Device Code]: https://datatracker.ietf.org/doc/html/rfc8628#section-3.4 - ### Response Types The following describes the supported response types. See the [OAuth 2.0 Multiple Response Type Encoding Practices] for -more technical information. - -| Flow Type | Values | -|:-------------------------:|:---------------------:| -| [Authorization Code Flow] | `code` | -| [Implicit Flow] | `token id_token` | -| [Implicit Flow] | `id_token` | -| [Implicit Flow] | `token` | -| [Hybrid Flow] | `code token` | -| [Hybrid Flow] | `code id_token` | -| [Hybrid Flow] | `code token id_token` | +more technical information. The default response modes column indicates which response modes are allowed by default on +clients configured with this flow type value. If more than a single response type is configured + +| Flow Type | Value | Default [Response Modes](#response-modes) Values | +|:-------------------------:|:---------------------:|:------------------------------------------------:| +| [Authorization Code Flow] | `code` | `form_post`, `query` | +| [Implicit Flow] | `id_token token` | `form_post`, `fragment` | +| [Implicit Flow] | `id_token` | `form_post`, `fragment` | +| [Implicit Flow] | `token` | `form_post`, `fragment` | +| [Hybrid Flow] | `code token` | `form_post`, `fragment` | +| [Hybrid Flow] | `code id_token` | `form_post`, `fragment` | +| [Hybrid Flow] | `code id_token token` | `form_post`, `fragment` | [Authorization Code Flow]: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth [Implicit Flow]: https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth @@ -139,16 +131,60 @@ more technical information. ### Response Modes The following describes the supported response modes. See the [OAuth 2.0 Multiple Response Type Encoding Practices] for -more technical information. +more technical information. The default response modes of a client is based on the [Response Types](#response-types) +configuration. | Name | Value | |:---------------------:|:-----------:| +| [OAuth 2.0 Form Post] | `form_post` | | Query String | `query` | | Fragment | `fragment` | -| [OAuth 2.0 Form Post] | `form_post` | [OAuth 2.0 Form Post]: https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html +### Grant Types + +The following describes the various [OAuth 2.0] and [OpenID Connect 1.0] grant types and their support level. The value +field is both the required value for the `grant_type` parameter in the authorization request and the `grant_types` +configuration option. + +| Grant Type | Supported | Value | Notes | +|:-----------------------------------------------:|:---------:|:----------------------------------------------:|:-----------------------------------------------------------------------------------------------:| +| [OAuth 2.0 Authorization Code] | Yes | `authorization_code` | | +| [OAuth 2.0 Resource Owner Password Credentials] | No | `password` | This Grant Type has been deprecated and should not normally be used | +| [OAuth 2.0 Client Credentials] | No | `client_credentials` | | +| [OAuth 2.0 Implicit] | Yes | `implicit` | This Grant Type has been deprecated and should not normally be used | +| [OAuth 2.0 Refresh Token] | Yes | `refresh_token` | This Grant Type should genreally only be used for clients which have the `offline_access` scope | +| [OAuth 2.0 Device Code] | No | `urn:ietf:params:oauth:grant-type:device_code` | | +| + +[OAuth 2.0 Authorization Code]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 +[OAuth 2.0 Implicit]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2 +[OAuth 2.0 Resource Owner Password Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3 +[OAuth 2.0 Client Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4 +[OAuth 2.0 Refresh Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.5 +[OAuth 2.0 Device Code]: https://datatracker.ietf.org/doc/html/rfc8628#section-3.4 + +### Client Authentication Method + +The following describes the supported client authentication methods. See the [OpenID Connect 1.0 Client Authentication] +specification and the [OAuth 2.0 - Client Types] specification for more information. + +| Description | Value / Name | Supported Client Types | Default for Client Type | Assertion Type | +|:------------------------------------:|:-----------------------------:|:----------------------:|:-----------------------:|:--------------------------------------------------------:| +| Secret via HTTP Basic Auth Scheme | `client_secret_basic` | `confidential` | N/A | N/A | +| Secret via HTTP POST Body | `client_secret_post` | `confidential` | N/A | N/A | +| JWT (signed by secret) | `client_secret_jwt` | Not Supported | N/A | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | +| JWT (signed by private key) | `private_key_jwt` | Not Supported | N/A | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` | +| [OAuth 2.0 Mutual-TLS] | `tls_client_auth` | Not Supported | N/A | N/A | +| [OAuth 2.0 Mutual-TLS] (Self Signed) | `self_signed_tls_client_auth` | Not Supported | N/A | N/A | +| No Authentication | `none` | `public` | `public` | N/A | + + +[OpenID Connect 1.0 Client Authentication]: https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication +[OAuth 2.0 Mutual-TLS]: https://datatracker.ietf.org/doc/html/rfc8705 +[OAuth 2.0 - Client Types]: https://datatracker.ietf.org/doc/html/rfc8705#section-2.1 + ## Authentication Method References Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method @@ -289,10 +325,13 @@ The advantages of this approach are as follows: [JSON Web Key Set]: https://datatracker.ietf.org/doc/html/rfc7517#section-5 +[Offline Access]: https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess + [Authorization]: https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint -[Pushed Authorization Requests]: https://datatracker.ietf.org/doc/html/rfc9126 [Token]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint [UserInfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo + +[Pushed Authorization Requests]: https://datatracker.ietf.org/doc/html/rfc9126 [Introspection]: https://datatracker.ietf.org/doc/html/rfc7662 [Revocation]: https://datatracker.ietf.org/doc/html/rfc7009 [Proof Key Code Exchange]: https://www.rfc-editor.org/rfc/rfc7636.html diff --git a/docs/content/en/integration/proxies/envoy.md b/docs/content/en/integration/proxies/envoy.md index 0d45b7cea..af37d3cc8 100644 --- a/docs/content/en/integration/proxies/envoy.md +++ b/docs/content/en/integration/proxies/envoy.md @@ -87,7 +87,7 @@ Below you will find commented examples of the following configuration: ### Example -Support for [Envoy] is possible with Authelia v4.37.0 and higher via [Envoy]'s [external authorization] filter. +Support for [Envoy] is possible with Authelia v4.37.0 and higher via the [Envoy] proxy [external authorization] filter. [external authorization]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz diff --git a/docs/content/en/integration/proxies/support.md b/docs/content/en/integration/proxies/support.md index 6364fde3a..9b33f8de4 100644 --- a/docs/content/en/integration/proxies/support.md +++ b/docs/content/en/integration/proxies/support.md @@ -92,7 +92,7 @@ available in [Kubernetes]. You would likely have to build your own [HAProxy] ima ### Envoy -[Envoy] is supported with Authelia v4.37.0 and higher via [Envoy]'s [external authorization] filter. +[Envoy] is supported with Authelia v4.37.0 and higher via the [Envoy] proxy [external authorization] filter. [external authorization]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz |