From 9e8db3c3f3544c7457fecc0caded307eeda77649 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Sat, 15 Apr 2023 22:25:21 +1000 Subject: [PATCH] docs(oidc): faq refresh (#5254) Signed-off-by: James Elliott --- .../identity-providers/open-id-connect.md | 2 +- ...ation.md => frequently-asked-questions.md} | 32 ++++++++++--------- .../openid-connect/nextcloud/index.md | 5 +++ .../guides/frequently-asked-questions.md | 2 +- docs/layouts/shortcodes/oidc-common.html | 8 ++--- 5 files changed, 28 insertions(+), 21 deletions(-) rename docs/content/en/integration/openid-connect/{specific-information.md => frequently-asked-questions.md} (66%) 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 a01f33f3c..83abaa8d7 100644 --- a/docs/content/en/configuration/identity-providers/open-id-connect.md +++ b/docs/content/en/configuration/identity-providers/open-id-connect.md @@ -375,7 +375,7 @@ The shared secret between Authelia and the application consuming this client. Th configured in the application. This secret must be generated by the administrator and can be done by following the -[Generating Client Secrets](../../integration/openid-connect/specific-information.md#generating-client-secrets) guide. +[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. diff --git a/docs/content/en/integration/openid-connect/specific-information.md b/docs/content/en/integration/openid-connect/frequently-asked-questions.md similarity index 66% rename from docs/content/en/integration/openid-connect/specific-information.md rename to docs/content/en/integration/openid-connect/frequently-asked-questions.md index 648d81924..f7b8939df 100644 --- a/docs/content/en/integration/openid-connect/specific-information.md +++ b/docs/content/en/integration/openid-connect/frequently-asked-questions.md @@ -1,7 +1,7 @@ --- -title: "Specific Information" -description: "Specific information regarding integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party" -lead: "Specific information regarding integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party." +title: "Frequently Asked Questions" +description: "Frequently Asked Questions regarding integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party" +lead: "Frequently Asked Questionsregarding integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party." date: 2022-10-20T15:27:09+11:00 draft: false images: [] @@ -12,7 +12,7 @@ weight: 615 toc: true --- -## Generating Client Secrets +## How Do I Generate Client Secrets We strongly recommend the following guidelines for generating client secrets: @@ -26,9 +26,12 @@ We strongly recommend the following guidelines for generating client secrets: when using it to access the token endpoint. Authelia provides an easy way to perform such actions via the [Generating a Random Password Hash] guide. Users can -perform a command such as `authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72` command to +perform a command such as +`authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random-charset rfc3986` command to both generate a client secret with 72 characters which is printed and is to be used with the relying party and hash it -using PBKDF2 which can be stored in the Authelia configuration. +using PBKDF2 which can be stored in the Authelia configuration. This random command also avoids issues with a relying +party / client application encoding the characters correctly as it uses the +[RFC3986 Unreserved Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3). [Generating a Random Password Hash]: ../../reference/guides/generating-secure-values.md#generating-a-random-password-hash @@ -45,20 +48,19 @@ that is implemented by the authorization server which requires access to the sec which case the secret should be encrypted and not be stored in plaintext. The most likely long term outcome is that the client configurations will be stored in the database with the secret both salted and peppered. -Authelia currently does not implement any of the specifications or protocols which require secrets being accessible in -the clear such as most notibly the `client_secret_jwt` grant and currently we no plans to implement any of these. As -such it's *__strongly discouraged and heavily deprecated__* and we instead recommended that users remove this from their -configuration entirely and use the [Generating Client Secrets](#generating-client-secrets) guide. At such a time as we -support one of these protocols we will very likely only allow plaintext for clients configured expressly for this -purpose i.e. a client that only allows `client_secret_jwt` and no other grants. +Authelia currently does implement the `client_secret_jwt` assertion client authentication method. Warnings will be +generated for any client not explicitly configured to utilize this client authentication method. We do not support any +of the other the specifications or protocols which require secrets being accessible in the clear and currently we no +plans to implement any of these. We only officially support utilization of the plaintext digest types where it's backed +by specifications and as such we plan to make the use outside of the `client_secret_jwt` a fatal error in the future. +For these reasons we recommended that users remove this from their configuration entirely and use the +[How Do I Generate Client Secrets](#how-do-i-generate-client-secrets) FAQ. Plaintext is either denoted by the `$plaintext$` prefix where everything after the prefix is the secret. In addition if the secret does not start with the `$` character it's considered as a plaintext secret for the time being but is deprecated as is the `$plaintext$` prefix. -## Frequently Asked Questions - -### Why isn't my application able to retrieve the token even though I've consented? +## Why isn't my application able to retrieve the token even though I've consented? The most common cause for this issue is when the affected application can not make requests to the Token [Endpoint]. This becomes obvious when the log level is set to `debug` or `trace` and a presence of requests to the Authorization diff --git a/docs/content/en/integration/openid-connect/nextcloud/index.md b/docs/content/en/integration/openid-connect/nextcloud/index.md index d144b71dd..83249dc46 100644 --- a/docs/content/en/integration/openid-connect/nextcloud/index.md +++ b/docs/content/en/integration/openid-connect/nextcloud/index.md @@ -33,6 +33,11 @@ This example makes the following assumptions: * __Client ID:__ `nextcloud` * __Client Secret:__ `insecure_secret` +*__Important Note:__ it has been reported that some of the [Nextcloud] plugins do not properly encode the client secret. +as such it's important to only use alphanumeric characters as well as the other +[RFC3986 Unreserved Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3). We recommend using the +generating client secrets guidance above.* + ## Configuration ### Application diff --git a/docs/content/en/reference/guides/frequently-asked-questions.md b/docs/content/en/reference/guides/frequently-asked-questions.md index 25e0e0588..2ce131a3c 100644 --- a/docs/content/en/reference/guides/frequently-asked-questions.md +++ b/docs/content/en/reference/guides/frequently-asked-questions.md @@ -14,4 +14,4 @@ toc: true ## Identity Providers -- [OpenID Connect 1.0 Integration](../../integration/openid-connect/specific-information.md#frequently-asked-questions) +- [OpenID Connect 1.0 Integration](../../integration/openid-connect/frequently-asked-questions.md) diff --git a/docs/layouts/shortcodes/oidc-common.html b/docs/layouts/shortcodes/oidc-common.html index 0d6c73715..8b6034c29 100644 --- a/docs/layouts/shortcodes/oidc-common.html +++ b/docs/layouts/shortcodes/oidc-common.html @@ -1,5 +1,5 @@ -{{ $specificinfo := "../specific-information/" }}{{ $config := "../../../configuration/identity-providers/open-id-connect.md" }} -{{- with .Get "specificinfo" }}{{ $specificinfo = . }}{{ end }} +{{ $faq := "../frequently-asked-questions/" }}{{ $config := "../../../configuration/identity-providers/open-id-connect.md" }} +{{- with .Get "faq" }}{{ $faq = . }}{{ end }} {{- with .Get "config" }}{{ $config = . }}{{ end }} ### Common Notes @@ -10,9 +10,9 @@ 2. The [OpenID Connect 1.0](https://openid.net/specs/openid-connect-core-1_0.html) `secret` parameter: 1. The value used in this guide is merely for demonstration purposes and you *__should absolutely not__* use this in production and should instead utilize the - [Generating Client Secrets]({{ $specificinfo }}#generating-client-secrets) guide. + [How Do I Generate Client Secrets]({{ $faq }}#how-do-i-generate-client-secrets) FAQ. 2. This string may be stored as plaintext in the Authelia configuration but this behaviour is deprecated and is not - guaranteed to be supported in the future. See the [Plaintext]({{ $specificinfo }}#plaintext) guide for more + guaranteed to be supported in the future. See the [Plaintext]({{ $faq }}#plaintext) guide for more information. 3. The Configuration example for Authelia is only a portion of the required configuration and it should be used as a guide in conjunction with the standard [OpenID Connect 1.0 Configuration]({{ $config }}) guide. \ No newline at end of file