docs: update and enhance oidc documentation (#2142)

Update and adjust OIDC documentation. This also adds information for users about RP's that have been tested.

Co-authored-by: Georg Lauterbach <44545919+aendeavor@users.noreply.github.com>
Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>
Co-authored-by: Amir Zarrinkafsh <nightah@me.com>
Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>

docs/community/oidc-integrations.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: Community-Tested OIDC Integrations
+parent: Community
+nav_order: 4
+---
+
+# OIDC Integratins
+
+**Note** This is community-based content for which the core-maintainers cannot guarantee correctness. The parameters may change over time. If a parameter does not work as documented, please submit a PR to update the list.
+
+## Currently Tested Applications
+
+- GitLab (>= 13.0.0)
+- Grafana (8.0.5)
+- MinIO (problems with the `state` option which is not supplied by MinIO, see [minio/minio#11398])
+
+[minio/minio#11398]: https://github.com/minio/minio/issues/11398
+
+## Known Callback URLs
+
+If you do not find the application in the list below, you will need to search for yourself - and maybe come back to open a PR to add your application to this list so others won't have to search for them.
+
+`<DOMAIN>` needs to be substituted with the full URL on which the application runs on. If GitLab, as an example, was reachable under `https://gitlab.example.com`, `<DOMAIN>` would be exactly the same.
+
+| Application | Version              | Callback URL                                             |
+| :---------: | :------------------: | :------------------------------------------------------: |
+| GitLab      | `14.0.1`             | `<DOMAIN>/users/auth/openid_connect/callback`    |
+| MinIO       | `RELEASE.2021-06-17` | `<DOMAIN>/minio/login/openid`                    |

docs/configuration/identity-providers/oidc.md

@@ -8,7 +8,7 @@ nav_order: 2
 
 # OpenID Connect
 
-**Authelia** currently supports the [OpenID Connect] OP role as a [beta](#beta) feature. The OP role is the 
+**Authelia** currently supports the [OpenID Connect] OP role as a [**beta**](#beta) feature. The OP role is the 
 [OpenID Connect] Provider role, not the Relaying Party or RP role. This means other applications that implement the 
 [OpenID Connect] RP role can use Authelia as an authentication and authorization backend similar to how you may use 
 social media or development platforms for login.
@@ -16,10 +16,10 @@ social media or development platforms for login.
 The Relaying Party role is the role which allows an application to use GitHub, Google, or other [OpenID Connect]
 providers for authentication and authorization. We do not intend to support this functionality at this moment in time.
 
-## Beta
+## Roadmap
 
 We have decided to implement [OpenID Connect] as a beta feature, it's suggested you only utilize it for testing and
-providing feedback, and should take caution in relying on it in production. [OpenID Connect] and it's related endpoints
+providing feedback, and should take caution in relying on it in production as of now. [OpenID Connect] and it's related endpoints
 are not enabled by default unless you specifically configure the [OpenID Connect] section.
 
 The beta will be broken up into stages. Each stage will bring additional features. The following table is a *rough* plan
@@ -93,12 +93,14 @@ for which stage will have each feature, and may evolve over time:
     </tbody>
 </table>
 
-*<sup>1</sup> this stage has not been implemented as of yet*
+¹ _This stage has not been implemented as of yet_.
 
-*<sup>2</sup> this individual feature has not been implemented as of yet*
+² _This individual feature has not been implemented as of yet_.
 
 ## Configuration
 
+The following snippet provides a sample-configuration for the OIDC identity provider explaining each field in detail.
+
 ```yaml
 identity_providers:
   oidc:
@@ -138,6 +140,7 @@ identity_providers:
 ## Options
 
 ### hmac_secret
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
@@ -145,12 +148,13 @@ required: yes
 {: .label .label-config .label-red }
 </div>
 
-The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256 byte string for
+The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256
-the purpose of meeting the required format.
+byte string for the purpose of meeting the required format. You must [generate this option yourself](#generating-a-random-secret).
 
-Can also be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
+Should be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
 
 ### issuer_private_key
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
@@ -158,19 +162,19 @@ required: yes
 {: .label .label-config .label-red }
 </div>
 
-The private key in DER base64 encoded PEM format used to encrypt the [OpenID Connect] JWT's. This can easily be
+The private key in DER base64 encoded PEM format used to encrypt the [OpenID Connect] JWT's.[¹](../../faq.md#why_only_use_a_private_issue_key_with_oidc)
-generated using the Authelia binary using the following syntax:
+You must [generate this option yourself](#generating-a-random-secret). To create this option, use
+`docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia:latest authelia rsa generate --dir /keys`
+to generate both the private and public key in the current directory. You can then paste the
+private key into your configuration.
 
-```console
+Should be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
-authelia rsa generate --dir /config
-```
-
-Can also be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
 
 ### access_token_lifespan
+
 <div markdown="1">
 type: duration
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: 1h
 {: .label .label-config .label-blue }
 required: no
@@ -181,9 +185,10 @@ The maximum lifetime of an access token. It's generally recommended keeping this
 For more information read these docs about [token lifespan].
 
 ### authorize_code_lifespan
+
 <div markdown="1">
 type: duration
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: 1m
 {: .label .label-config .label-blue }
 required: no
@@ -194,9 +199,10 @@ The maximum lifetime of an authorize code. This can be rather short, as the auth
 obtain the other token types. For more information read these docs about [token lifespan].
 
 ### id_token_lifespan
+
 <div markdown="1">
 type: duration
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: 1h
 {: .label .label-config .label-blue }
 required: no
@@ -206,23 +212,25 @@ required: no
 The maximum lifetime of an ID token. For more information read these docs about [token lifespan].
 
 ### refresh_token_lifespan
+
 <div markdown="1">
 type: string
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: 30d
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 
-The maximum lifetime of a refresh token. This should typically be slightly more the other token lifespans. This is 
+The maximum lifetime of a refresh token. The
-because the refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an 
+refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an
 up-to-date expiration. For more information read these docs about [token lifespan].
 
 ### enable_client_debug_messages
+
 <div markdown="1">
 type: boolean
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: false
 {: .label .label-config .label-blue }
 required: no
@@ -232,9 +240,10 @@ required: no
 Allows additional debug messages to be sent to the clients.
 
 ### minimum_parameter_entropy
+
 <div markdown="1">
 type: integer
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: 8
 {: .label .label-config .label-blue }
 required: no
@@ -243,15 +252,16 @@ required: no
 
 This controls the minimum length of the `nonce` and `state` parameters.
 
-***Security Notice:*** Changing this value is generally discouraged, reducing it from the default can theoretically make
+***Security Notice:*** Changing this value is generally discouraged, reducing it from the default can theoretically
-certain scenarios less secure. It highly encouraged that if your OpenID Connect RP does not send these parameters or
+make certain scenarios less secure. It is highly encouraged that if your OpenID Connect RP does not send these parameters
-sends parameters with a lower length than the default that they implement a change rather than changing this value.
+or sends parameters with a lower length than the default that they implement a change rather than changing this value.
 
 ### clients
 
 A list of clients to configure. The options for each client are described below.
 
 #### id
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
@@ -259,9 +269,11 @@ required: yes
 {: .label .label-config .label-red }
 </div>
 
-The Client ID for this client. Must be configured in the application consuming this client.
+The Client ID for this client. It must exactly match the Client ID configured in the application
+consuming this client.
 
 #### description
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
@@ -274,6 +286,7 @@ required: no
 A friendly description for this client shown in the UI. This defaults to the same as the ID.
 
 #### secret
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
@@ -281,9 +294,12 @@ required: yes
 {: .label .label-config .label-red }
 </div>
 
-The shared secret between Authelia and the application consuming this client. Currently this is stored in plain text.
+The shared secret between Authelia and the application consuming this client. This secret must
+match the secret configured in the application. Currently this is stored in plain text.
+You must [generate this option yourself](#generating-a-random-secret).
 
 #### authorization_policy
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
@@ -293,9 +309,10 @@ required: no
 {: .label .label-config .label-green }
 </div>
 
-The authorization policy for this client. Either `one_factor` or `two_factor`.
+The authorization policy for this client: either `one_factor` or `two_factor`.
 
 #### redirect_uris
+
 <div markdown="1">
 type: list(string)
 {: .label .label-config .label-purple }
@@ -303,22 +320,27 @@ required: yes
 {: .label .label-config .label-red }
 </div>
 
-A list of valid callback URL's this client will redirect to. All other callbacks will be considered unsafe. The URL's
+A list of valid callback URL´s this client will redirect to. All other callbacks will be considered
-are case-sensitive.
+unsafe. The URL's are case-sensitive and they differ from application to application - the community has
+provided [a list of URL´s for common applications](../../community/oidc-integrations.md).
 
 #### scopes
+
 <div markdown="1">
 type: list(string)
-{: .label .label-config .label-purple } 
+{: .label .label-config .label-purple }
 default: openid, groups, profile, email
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 
-A list of scopes to allow this client to consume. See [scope definitions](#scope-definitions) for more information.
+A list of scopes to allow this client to consume. See [scope definitions](#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.
 
 #### grant_types
+
 <div markdown="1">
 type: list(string)
 {: .label .label-config .label-purple } 
@@ -328,11 +350,12 @@ required: no
 {: .label .label-config .label-green }
 </div>
 
-A list of grant types this client can return. It is recommended that this isn't configured at this time unless you know
+A list of grant types this client can return. _It is recommended that this isn't configured at this time unless you
-what you're doing. Valid options are: `implicit`, `refresh_token`, `authorization_code`, `password`, 
+know what you're doing_. Valid options are: `implicit`, `refresh_token`, `authorization_code`, `password`,
 `client_credentials`.
 
 #### response_types
+
 <div markdown="1">
 type: list(string)
 {: .label .label-config .label-purple } 
@@ -342,11 +365,12 @@ required: no
 {: .label .label-config .label-green }
 </div>
 
-A list of response types this client can return. It is recommended that this isn't configured at this time unless you 
+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`, 
+know what you're doing_. Valid options are: `code`, `code id_token`, `id_token`, `token id_token`, `token`,
 `token id_token code`.
 
 #### response_modes
+
 <div markdown="1">
 type: list(string)
 {: .label .label-config .label-purple } 
@@ -360,6 +384,7 @@ A list of response modes this client can return. It is recommended that this isn
 know what you're doing. Potential values are `form_post`, `query`, and `fragment`.
 
 #### userinfo_signing_algorithm
+
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
@@ -371,6 +396,18 @@ required: no
 
 The algorithm used to sign the userinfo endpoint responses. This can either be `none` or `RS256`. 
 
+## Generating a random secret
+
+If you must provide a random secret in configuration, you can generate a random string of sufficient length. The command
+
+```sh
+LENGTH=64
+tr -cd '[:alnum:]' < /dev/urandom | fold -w "${LENGTH}" | head -n 1 | tr -d '\n' ; echo
+```
+
+prints such a string with a length in characters of `${LENGTH}` on `stdout`. The string will only contain alphanumeric
+characters. For Kubernetes, see [this section too](../secrets.md#Kubernetes).
+
 ## Scope Definitions
 
 ### openid
@@ -435,6 +472,7 @@ Authelia via https://auth.example.com, the discovery URL is https://auth.example
 |Revoke       |api/oidc/revoke                 |
 |Userinfo     |api/oidc/userinfo               |
 
+[//]: # (Links)
 
 [OpenID Connect]: https://openid.net/connect/
-[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration
+[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration

docs/configuration/secrets.md

@@ -162,11 +162,46 @@ services:
       - TZ=Australia/Melbourne
 ```
 
-
 ## Kubernetes
 
 Secrets can be mounted as files using the following sample manifests.
 
+To create a secret, the following manifest can be used
+
+```yaml
+---
+kind: Secret
+apiVersion: v1
+
+metadata:
+  name: a-nice-name
+  namespace: your-authelia-namespace
+
+data:
+  duo_key: >-
+    UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K
+  
+  jwt_secret: >-
+    anotherBase64EncodedSecret
+
+...
+```
+
+where `UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K` is Base64 encoded for
+`Qq5Zc8KJevyzxtpCzlLjClZe9qnyErXFab14gMHDstE`, the actual content of the secret. You can generate these contents with
+
+```sh
+LENGTH=64
+tr -cd '[:alnum:]' < /dev/urandom \
+  | fold -w "${LENGTH}"           \
+  | head -n 1                     \
+  | tr -d '\n'                    \
+  | tee actualSecretContent.txt   \
+  | base64 --wrap 0               \
+  ; echo
+```
+
+which writes the secret's content to the `actualSecretContent.txt` file and print the Base64 encoded version on `stdout`. `${LENGTH}` is the length in characters of the secret content generated by this pipe. If you don't want the contents to be written to `actualSecretContent.txt`, just delete the line with the `tee` command.
 
 ### Kustomization
 

docs/faq.md

@@ -9,4 +9,9 @@ nav_order: 8
 ## How can the backend be aware of the authenticated users?
 
 This question is solved
-[here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
+[here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
+
+## Why only use a private issuer key and no public key with OIDC?
+
+The reason for using only the private key here is that one is able to calculate the public key easily from the private
+key (`openssl rsa -in rsa.key -pubout > rsa.pem`).