From d1147f9ac4c0f1fe92c97e0804b1d2e9113426c8 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Wed, 8 Feb 2023 01:29:43 +1100 Subject: [PATCH] docs: refactor oidc config docs (#4892) --- .../identity-providers/open-id-connect.md | 33 ++++++---- .../openid-connect/introduction.md | 62 +++++++++++++++++++ 2 files changed, 82 insertions(+), 13 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 c13393cd7..6a2178442 100644 --- a/docs/content/en/configuration/identity-providers/open-id-connect.md +++ b/docs/content/en/configuration/identity-providers/open-id-connect.md @@ -402,9 +402,6 @@ This enables the public client type for this client. This is for clients that ar 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. -In addition to the standard rules for redirect URIs, public clients can use the `urn:ietf:wg:oauth:2.0:oob` redirect -URI. - #### redirect_uris {{< confkey type="list(string)" required="yes" >}} @@ -420,7 +417,6 @@ their redirect URIs are as follows: 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`. -4. The client can ignore rule 3 and use `urn:ietf:wg:oauth:2.0:oob` if it is a [public](#public) client type. #### audience @@ -434,30 +430,41 @@ A list of audiences this client is allowed to request. 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 want to use with Authelia will most-likely provide you with the scopes to allow. +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" >}} -A list of grant types this client can return. *It is recommended that this isn't configured at this time unless you -know what you're doing*. Valid options are: `implicit`, `refresh_token`, `authorization_code`, `password`, -`client_credentials`. +*__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" >}} -A list of response types this client can return. *It is recommended that this isn't configured at this time unless you -know what you're doing*. Valid options are: `code`, `code id_token`, `id_token`, `token id_token`, `token`, -`token id_token code`. +*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.* + +A list of response types this client supports. + +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" >}} -A list of response modes this client can return. It is recommended that this isn't configured at this time unless you -know what you're doing. Potential values are `form_post`, `query`, and `fragment`. +*__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. + +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. #### authorization_policy diff --git a/docs/content/en/integration/openid-connect/introduction.md b/docs/content/en/integration/openid-connect/introduction.md index 44267c1ac..4b06ae438 100644 --- a/docs/content/en/integration/openid-connect/introduction.md +++ b/docs/content/en/integration/openid-connect/introduction.md @@ -87,6 +87,68 @@ This scope includes the profile information the authentication backend reports a | preferred_username | string | username | The username the user used to login with | | name | string | display_name | The users display name | +## Parameters + +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` | + +[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 +[Hybrid Flow]: https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth + +[OAuth 2.0 Multiple Response Type Encoding Practices]: https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html + +### Response Modes + +The following describes the supported response modes. See the [OAuth 2.0 Multiple Response Type Encoding Practices] for +more technical information. + +| Name | Value | +|:---------------------:|:-----------:| +| 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 + ## Authentication Method References Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method