From 9d7cfb8455e2d45eb84bcc00359730bc3df9d95e Mon Sep 17 00:00:00 2001 From: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com> Date: Wed, 14 Jul 2021 03:36:07 +0200 Subject: [PATCH] docs: update and enhance oidc documentation (#2142) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Amir Zarrinkafsh Co-authored-by: James Elliott --- docs/community/oidc-integrations.md | 29 +++++ docs/configuration/identity-providers/oidc.md | 114 ++++++++++++------ docs/configuration/secrets.md | 37 +++++- docs/faq.md | 7 +- 4 files changed, 147 insertions(+), 40 deletions(-) create mode 100644 docs/community/oidc-integrations.md diff --git a/docs/community/oidc-integrations.md b/docs/community/oidc-integrations.md new file mode 100644 index 000000000..416b3aca1 --- /dev/null +++ b/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. + +`` 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`, `` would be exactly the same. + +| Application | Version | Callback URL | +| :---------: | :------------------: | :------------------------------------------------------: | +| GitLab | `14.0.1` | `/users/auth/openid_connect/callback` | +| MinIO | `RELEASE.2021-06-17` | `/minio/login/openid` | diff --git a/docs/configuration/identity-providers/oidc.md b/docs/configuration/identity-providers/oidc.md index a08df2451..31c5fc7de 100644 --- a/docs/configuration/identity-providers/oidc.md +++ b/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: -*1 this stage has not been implemented as of yet* +¹ _This stage has not been implemented as of yet_. -*2 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 +
type: string {: .label .label-config .label-purple } @@ -145,12 +148,13 @@ required: yes {: .label .label-config .label-red }
-The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256 byte string for -the purpose of meeting the required format. +The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256 +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 +
type: string {: .label .label-config .label-purple } @@ -158,19 +162,19 @@ required: yes {: .label .label-config .label-red }
-The private key in DER base64 encoded PEM format used to encrypt the [OpenID Connect] JWT's. This can easily be -generated using the Authelia binary using the following syntax: +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) +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 -authelia rsa generate --dir /config -``` - -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. ### access_token_lifespan +
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 +
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 +
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 +
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 }
-The maximum lifetime of a refresh token. This should typically be slightly more the other token lifespans. This is -because the refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an +The maximum lifetime of a refresh token. The +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 +
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 +
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 -certain scenarios less secure. It highly encouraged that if your OpenID Connect RP does not send these parameters or -sends parameters with a lower length than the default that they implement a change rather than changing this value. +***Security Notice:*** Changing this value is generally discouraged, reducing it from the default can theoretically +make certain scenarios less secure. It is highly encouraged that if your OpenID Connect RP does not send these parameters +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 +
type: string {: .label .label-config .label-purple } @@ -259,9 +269,11 @@ required: yes {: .label .label-config .label-red }
-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 +
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 +
type: string {: .label .label-config .label-purple } @@ -281,9 +294,12 @@ required: yes {: .label .label-config .label-red }
-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 +
type: string {: .label .label-config .label-purple } @@ -293,9 +309,10 @@ required: no {: .label .label-config .label-green }
-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 +
type: list(string) {: .label .label-config .label-purple } @@ -303,22 +320,27 @@ required: yes {: .label .label-config .label-red }
-A list of valid callback URL's this client will redirect to. All other callbacks will be considered unsafe. The URL's -are case-sensitive. +A list of valid callback URL´s this client will redirect to. All other callbacks will be considered +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 +
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 }
-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 +
type: list(string) {: .label .label-config .label-purple } @@ -328,11 +350,12 @@ required: no {: .label .label-config .label-green }
-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`, +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`. #### response_types +
type: list(string) {: .label .label-config .label-purple } @@ -342,11 +365,12 @@ required: no {: .label .label-config .label-green }
-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`, +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`. #### response_modes +
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 +
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 \ No newline at end of file +[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration diff --git a/docs/configuration/secrets.md b/docs/configuration/secrets.md index fa3374229..00ce029e3 100644 --- a/docs/configuration/secrets.md +++ b/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 diff --git a/docs/faq.md b/docs/faq.md index 4772a4f5c..4fdf839fb 100644 --- a/docs/faq.md +++ b/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). \ No newline at end of file +[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`).