From a8849f1b9e1a0903a4a54982805a0fd779d5d800 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Fri, 26 Aug 2022 13:26:58 +1000 Subject: [PATCH] docs: misc consistency adjustments (#3904) --- .../identity-providers/open-id-connect.md | 6 +- .../openid-connect/apache-guacamole/index.md | 5 +- .../openid-connect/argocd/index.md | 5 +- .../openid-connect/bookstack/index.md | 5 +- .../cloudflare-zerotrust/index.md | 5 +- .../integration/openid-connect/gitea/index.md | 5 +- .../openid-connect/gitlab/index.md | 5 +- .../openid-connect/grafana/index.md | 52 ++++++----- .../openid-connect/harbor/index.md | 6 +- .../openid-connect/hashicorp-vault/index.md | 7 +- .../openid-connect/introduction.md | 14 ++- .../integration/openid-connect/komga/index.md | 92 ++++++------------- .../openid-connect/nextcloud/index.md | 5 +- .../openid-connect/outline/index.md | 5 +- .../openid-connect/portainer/index.md | 5 +- .../openid-connect/proxmox/index.md | 5 +- .../openid-connect/seafile/index.md | 5 +- .../openid-connect/synapse/index.md | 5 +- 18 files changed, 114 insertions(+), 123 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 585c1310b..dde841d34 100644 --- a/docs/content/en/configuration/identity-providers/open-id-connect.md +++ b/docs/content/en/configuration/identity-providers/open-id-connect.md @@ -418,10 +418,8 @@ know what you're doing. Potential values are `form_post`, `query`, and `fragment The algorithm used to sign the userinfo endpoint responses. This can either be `none` or `RS256`. -| Signing Algorithm | Encoding | Content Type | -|:-----------------:|:------------:|:-----------------------------------:| -| `none` | JSON | `application/json; charset="UTF-8"` | -| `RS256` | JWT (Signed) | `application/jwt; charset="UTF-8"` | +See the [integration guide](../../integration/openid-connect/introduction.md#user-information-signing-algorithm) for +more information. ## Integration diff --git a/docs/content/en/integration/openid-connect/apache-guacamole/index.md b/docs/content/en/integration/openid-connect/apache-guacamole/index.md index e4419d52e..ebbe51752 100644 --- a/docs/content/en/integration/openid-connect/apache-guacamole/index.md +++ b/docs/content/en/integration/openid-connect/apache-guacamole/index.md @@ -58,16 +58,17 @@ The following YAML configuration is an example __Authelia__ ```yaml - id: guacamole + description: Apache Guacamole secret: guacamole_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://guacamole.example.com scopes: - openid - profile - groups - email - redirect_uris: - - https://guacamole.example.com response_types: - id_token grant_types: diff --git a/docs/content/en/integration/openid-connect/argocd/index.md b/docs/content/en/integration/openid-connect/argocd/index.md index 95dcda07e..75f7cdc34 100644 --- a/docs/content/en/integration/openid-connect/argocd/index.md +++ b/docs/content/en/integration/openid-connect/argocd/index.md @@ -62,6 +62,9 @@ which will operate with the above example: ```yaml - id: argocd description: Argo CD + secret: argocd_client_secret + public: false + authorization_policy: two_factor redirect_uris: - https://argocd.example.com/auth/callback scopes: @@ -69,11 +72,11 @@ which will operate with the above example: - groups - email - profile - secret: argocd_client_secret userinfo_signing_algorithm: none - id: argocd-cli description: Argo CD (CLI) public: true + authorization_policy: two_factor redirect_uris: - http://localhost:8085/auth/callback scopes: diff --git a/docs/content/en/integration/openid-connect/bookstack/index.md b/docs/content/en/integration/openid-connect/bookstack/index.md index 1cf008479..c26e341c5 100644 --- a/docs/content/en/integration/openid-connect/bookstack/index.md +++ b/docs/content/en/integration/openid-connect/bookstack/index.md @@ -57,15 +57,16 @@ which will operate with the above example: ```yaml - id: bookstack + description: BookStack secret: bookstack_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://bookstack.example.com/oidc/callback scopes: - openid - profile - email - redirect_uris: - - https://bookstack.example.com/oidc/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/cloudflare-zerotrust/index.md b/docs/content/en/integration/openid-connect/cloudflare-zerotrust/index.md index fc5d04bee..a2ab73579 100644 --- a/docs/content/en/integration/openid-connect/cloudflare-zerotrust/index.md +++ b/docs/content/en/integration/openid-connect/cloudflare-zerotrust/index.md @@ -60,16 +60,17 @@ which will operate with the above example: ```yaml - id: cloudflare + description: Cloudflare ZeroTrust secret: cloudflare_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://example-team.cloudflareaccess.com/cdn-cgi/access/callback scopes: - openid - profile - groups - email - redirect_uris: - - https://example-team.cloudflareaccess.com/cdn-cgi/access/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/gitea/index.md b/docs/content/en/integration/openid-connect/gitea/index.md index 9aea3fadd..3c395c414 100644 --- a/docs/content/en/integration/openid-connect/gitea/index.md +++ b/docs/content/en/integration/openid-connect/gitea/index.md @@ -78,15 +78,16 @@ will operate with the above example: ```yaml - id: gitea + description: Gitea secret: gitea_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://gitea.example.com/user/oauth2/authelia/callback scopes: - openid - email - profile - redirect_uris: - - https://gitea.example.com/user/oauth2/authelia/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/gitlab/index.md b/docs/content/en/integration/openid-connect/gitlab/index.md index 606f0e88a..3c3beaf2a 100644 --- a/docs/content/en/integration/openid-connect/gitlab/index.md +++ b/docs/content/en/integration/openid-connect/gitlab/index.md @@ -74,16 +74,17 @@ which will operate with the above example: ```yaml - id: gitlab + description: GitLab secret: gitlab_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://gitlab.example.com/users/auth/openid_connect/callback scopes: - openid - profile - groups - email - redirect_uris: - - https://gitlab.example.com/users/auth/openid_connect/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/grafana/index.md b/docs/content/en/integration/openid-connect/grafana/index.md index bbd6e47f3..a0fe50571 100644 --- a/docs/content/en/integration/openid-connect/grafana/index.md +++ b/docs/content/en/integration/openid-connect/grafana/index.md @@ -37,12 +37,13 @@ This example makes the following assumptions: ### Application -To configure [Grafana] to utilize Authelia as an [OpenID Connect] Provider, you either need to edit the config file, or specify overrides in the containers environment variables. +To configure [Grafana] to utilize Authelia as an [OpenID Connect] Provider you have two effective options: -#### Method 1: Configuration Files -1. Add the following Generic OAuth configuration to the [Grafana] configuration: +#### Configuration File -```ruby +Add the following Generic OAuth configuration to the [Grafana] configuration: + +```ini [server] root_url = https://grafana.example.com [auth.generic_oauth] @@ -62,24 +63,26 @@ name_attribute_path = name use_pkce = true ``` -#### Method 2: Container Environment Variables -**GF_AUTH_GENERIC_OAUTH_NAME=**`Authelia` -**GF_AUTH_GENERIC_OAUTH_ENABLED=**`true` -**GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=**`true` -**GF_AUTH_GENERIC_OAUTH_CLIENT_ID=**`grafana` -**GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=**`grafana_client_secret` -**GF_AUTH_GENERIC_OAUTH_SCOPES=**`openid profile email groups` -**GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_NAME=**`email` -**GF_AUTH_GENERIC_OAUTH_AUTH_URL=**`https://auth.example.com/api/oidc/authorization` -**GF_AUTH_GENERIC_OAUTH_TOKEN_URL=**`https://auth.example.com/api/oidc/token` -**GF_AUTH_GENERIC_OAUTH_API_URL=**`https://auth.example.com/api/oidc/userinfo` -**GF_AUTH_GENERIC_OAUTH_TLS_SKIP_VERIFY_INSECURE=**`true` -**GF_AUTH_GENERIC_OAUTH_EMPTY_SCOPES=**`false` -**GF_AUTH_GENERIC_OAUTH_ICON=**`signin` -**GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=**`preferred_username` -**GF_AUTH_GENERIC_OAUTH_GROUPS_ATTRIBUTE_PATH=**`groups` -**GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=**`name` -**GF_AUTH_GENERIC_OAUTH_USE_PKCE=**`true` +#### Environment Variables + +Configure the following environment variables: + +| Variable | Value | +|:-------------------------------------------:|:-----------------------------------------------:| +| GF_SERVER_ROOT_URL | https://grafana.example.com | +| GF_AUTH_GENERIC_OAUTH_ENABLED | true | +| GF_AUTH_GENERIC_OAUTH_NAME | Authelia | +| GF_AUTH_GENERIC_OAUTH_CLIENT_ID | grafana | +| GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET | grafana_client_secret | +| GF_AUTH_GENERIC_OAUTH_SCOPES | openid profile email groups | +| GF_AUTH_GENERIC_OAUTH_EMPTY_SCOPES | false | +| GF_AUTH_GENERIC_OAUTH_AUTH_URL | https://auth.example.com/api/oidc/authorization | +| GF_AUTH_GENERIC_OAUTH_TOKEN_URL | https://auth.example.com/api/oidc/token | +| GF_AUTH_GENERIC_OAUTH_API_URL | https://auth.example.com/api/oidc/userinfo | +| GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH | preferred_username | +| GF_AUTH_GENERIC_OAUTH_GROUPS_ATTRIBUTE_PATH | groups | +| GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH | name | +| GF_AUTH_GENERIC_OAUTH_USE_PKCE | true | ### Authelia @@ -89,16 +92,17 @@ which will operate with the above example: ```yaml - id: grafana + description: Grafana secret: grafana_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://grafana.example.com/login/generic_oauth scopes: - openid - profile - groups - email - redirect_uris: - - https://grafana.example.com/login/generic_oauth userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/harbor/index.md b/docs/content/en/integration/openid-connect/harbor/index.md index 0a0cfd4cf..2b32ca0ff 100644 --- a/docs/content/en/integration/openid-connect/harbor/index.md +++ b/docs/content/en/integration/openid-connect/harbor/index.md @@ -65,17 +65,17 @@ which will operate with the above example: ```yaml - id: harbor + description: Harbor secret: harbor_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://harbor.example.com/c/oidc/callback scopes: - openid - profile - groups - email - redirect_uris: - - https://vault.example.com/oidc/callback - - https://vault.example.com/ui/vault/auth/oidc/oidc/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/hashicorp-vault/index.md b/docs/content/en/integration/openid-connect/hashicorp-vault/index.md index 8cd5415cd..dd0a53c3b 100644 --- a/docs/content/en/integration/openid-connect/hashicorp-vault/index.md +++ b/docs/content/en/integration/openid-connect/hashicorp-vault/index.md @@ -48,17 +48,18 @@ which will operate with the above example: ```yaml - id: vault + description: HashiCorp Vault secret: vault_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://vault.example.com/oidc/callback + - https://vault.example.com/ui/vault/auth/oidc/oidc/callback scopes: - openid - profile - groups - email - redirect_uris: - - https://vault.example.com/oidc/callback - - https://vault.example.com/ui/vault/auth/oidc/oidc/callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/introduction.md b/docs/content/en/integration/openid-connect/introduction.md index c452c470b..bc7939fca 100644 --- a/docs/content/en/integration/openid-connect/introduction.md +++ b/docs/content/en/integration/openid-connect/introduction.md @@ -108,6 +108,16 @@ Below is a list of the potential values we place in the [Claim] and their meanin | hwk | User used a hardware key to login | Have | Browser | | sms | User used Duo to login | Have | External | +## User Information Signing Algorithm + +The following table describes the response from the [UserInfo] endpoint depending on the +[userinfo_signing_algorithm](../../configuration/identity-providers/open-id-connect.md#userinfo_signing_algorithm). + +| Signing Algorithm | Encoding | Content Type | +|:-----------------:|:------------:|:-----------------------------------:| +| `none` | JSON | `application/json; charset="UTF-8"` | +| `RS256` | JWT (Signed) | `application/jwt; charset="UTF-8"` | + ## Endpoint Implementations The following section documents the endpoints we implement and their respective paths. This information can @@ -141,7 +151,7 @@ These endpoints implement OpenID Connect elements. | [JSON Web Key Sets] | https://auth.example.com/jwks.json | jwks_uri | | [Authorization] | https://auth.example.com/api/oidc/authorization | authorization_endpoint | | [Token] | https://auth.example.com/api/oidc/token | token_endpoint | -| [Userinfo] | https://auth.example.com/api/oidc/userinfo | userinfo_endpoint | +| [UserInfo] | https://auth.example.com/api/oidc/userinfo | userinfo_endpoint | | [Introspection] | https://auth.example.com/api/oidc/introspection | introspection_endpoint | | [Revocation] | https://auth.example.com/api/oidc/revocation | revocation_endpoint | @@ -161,7 +171,7 @@ These endpoints implement OpenID Connect elements. [Authorization]: https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint [Token]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint -[Userinfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo +[UserInfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo [Introspection]: https://www.rfc-editor.org/rfc/rfc7662.html [Revocation]: https://www.rfc-editor.org/rfc/rfc7009.html diff --git a/docs/content/en/integration/openid-connect/komga/index.md b/docs/content/en/integration/openid-connect/komga/index.md index 0b055cce3..53820a63e 100644 --- a/docs/content/en/integration/openid-connect/komga/index.md +++ b/docs/content/en/integration/openid-connect/komga/index.md @@ -11,15 +11,13 @@ menu: weight: 620 toc: true community: true -aliases: - - /docs/community/oidc-integrations/komga.html --- ## Tested Versions * [Authelia] * [v4.36.4](https://github.com/authelia/authelia/releases/tag/v4.36.4) -* [Komga] +* [Komga] * [v0.157.1](https://github.com/gotson/komga/releases/tag/v0.157.1) ## Before You Begin @@ -32,7 +30,7 @@ This example makes the following assumptions: * __Application Root URL:__ `https://komga.example.com` * __Authelia Root URL:__ `https://auth.example.com` -* __Client ID:__ `komga-auth` +* __Client ID:__ `komga` * __Client Secret:__ `komga_client_secret` ## Configuration @@ -41,89 +39,55 @@ This example makes the following assumptions: To configure [Komga] to utilize Authelia as an [OpenID Connect] Provider: -1. Create an `Application.yml` according to the [configuration options](https://komga.org/installation/configuration.html) -2. Add a section that describes the spring boot security configuration - - -```spring: +1. Configure the security section of the [Komga] configuration: +```yaml +komga: + ## Comment if you don't want automatic account creation. + oauth2-account-creation: true +spring: security: oauth2: client: registration: authelia: - client-id: `komga-auth` + client-id: `komga` client-secret: `komga_client_secret` client-name: Authelia - scope: openid, email + scope: openid,profile,email authorization-grant-type: authorization_code redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/login/oauth2/code/authelia" provider: authelia: - issuer-uri: `https:\\auth.example.com` - user-name-attribute: email + issuer-uri: https://auth.example.com + user-name-attribute: preferred_username ```` -### Optional configuration - -You can enable some useful additional debug logging to `application.yml` by adding the `logging.level.org.springframework.security attribute`: - -``` -logging: - file.name: /config/logs/komga.log - level: - org: - springframework: - security: info #when changed to 'TRACE' adds additional spring security logging on top of komga logging. - gotson: - komga: info -``` - -Automatic creation of accounts (in Komga) by logging in with Authelia can be enabled with: - -``` -komga: - oauth2-account-creation: true -``` - -In certain cases it might be necessary to add: - -``` -server: - use-forward-headers: true -``` - - ### Authelia The following YAML configuration is an example __Authelia__ -[client configuration](../../../configuration/identity-providers/open-id-connect.md#clients) for use with [Portainer] +[client configuration](../../../configuration/identity-providers/open-id-connect.md#clients) for use with [Komga] which will operate with the above example: ```yaml - - - id: komga-auth - description: Komga Comics OpenID - secret: `komga_client_secret` - public: false - authorization_policy: two_factor - audience: [] - scopes: - - openid - - email - redirect_uris: - - https://komga.example.com/login/oauth2/code/authelia - - grant_types: - - authorization_code - - userinfo_signing_algorithm: none +- id: komga + description: Komga + secret: komga_client_secret + public: false + authorization_policy: two_factor + redirect_uris: + - https://komga.example.com/login/oauth2/code/authelia + scopes: + - openid + - preferred_username + - email + grant_types: + - authorization_code + userinfo_signing_algorithm: none ``` -Note: make sure that the `userinfo_signing_algorithm` is set to `none`, or Komga will throw an `application\jwt` error. - - ## See Also +* [Komga Configuration options Documentation](https://komga.org/installation/configuration.html) * [Komga Social login Documentation](https://komga.org/installation/oauth2.html) [Authelia]: https://www.authelia.com diff --git a/docs/content/en/integration/openid-connect/nextcloud/index.md b/docs/content/en/integration/openid-connect/nextcloud/index.md index 2e82413d8..c54586060 100644 --- a/docs/content/en/integration/openid-connect/nextcloud/index.md +++ b/docs/content/en/integration/openid-connect/nextcloud/index.md @@ -86,15 +86,16 @@ which will operate with the above example: ```yaml - id: nextcloud + description: NextCloud secret: nextcloud_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://nextcloud.example.com/apps/oidc_login/oidc scopes: - openid - profile - groups - redirect_uris: - - https://nextcloud.example.com/apps/oidc_login/oidc userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/outline/index.md b/docs/content/en/integration/openid-connect/outline/index.md index 1c570fdb6..db55add2b 100644 --- a/docs/content/en/integration/openid-connect/outline/index.md +++ b/docs/content/en/integration/openid-connect/outline/index.md @@ -62,15 +62,16 @@ which will operate with the above example: ```yaml - id: outline + description: Outline secret: outline_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://outline.example.com/auth/oidc.callback scopes: - openid - profile - email - redirect_uris: - - https://outline.example.com/auth/oidc.callback userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/portainer/index.md b/docs/content/en/integration/openid-connect/portainer/index.md index 08a67a5f5..7e9c6afd4 100644 --- a/docs/content/en/integration/openid-connect/portainer/index.md +++ b/docs/content/en/integration/openid-connect/portainer/index.md @@ -66,16 +66,17 @@ which will operate with the above example: ```yaml - id: portainer + description: Portainer secret: portainer_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://portainer.example.com scopes: - openid - profile - groups - email - redirect_uris: - - https://portainer.example.com userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/proxmox/index.md b/docs/content/en/integration/openid-connect/proxmox/index.md index 9fd17e3e9..eee1d305a 100644 --- a/docs/content/en/integration/openid-connect/proxmox/index.md +++ b/docs/content/en/integration/openid-connect/proxmox/index.md @@ -64,15 +64,16 @@ which will operate with the above example: ```yaml - id: proxmox + description: Proxmox secret: proxmox_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://proxmox.example.com scopes: - openid - profile - email - redirect_uris: - - https://proxmox.example.com userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/seafile/index.md b/docs/content/en/integration/openid-connect/seafile/index.md index 9b2a24e6a..f7a690a2f 100644 --- a/docs/content/en/integration/openid-connect/seafile/index.md +++ b/docs/content/en/integration/openid-connect/seafile/index.md @@ -72,15 +72,16 @@ which will operate with the above example: ```yaml - id: seafile + description: Seafile secret: seafile_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://seafile.example.com/oauth/callback/ scopes: - openid - profile - email - redirect_uris: - - https://seafile.example.com/oauth/callback/ userinfo_signing_algorithm: none ``` diff --git a/docs/content/en/integration/openid-connect/synapse/index.md b/docs/content/en/integration/openid-connect/synapse/index.md index 140122724..bbdac2740 100644 --- a/docs/content/en/integration/openid-connect/synapse/index.md +++ b/docs/content/en/integration/openid-connect/synapse/index.md @@ -68,15 +68,16 @@ which will operate with the above example: ```yaml - id: synapse + description: Synapse secret: synapse_client_secret public: false authorization_policy: two_factor + redirect_uris: + - https://synapse.example.com/_synapse/client/oidc/callback scopes: - openid - profile - email - redirect_uris: - - https://synapse.example.com/_synapse/client/oidc/callback userinfo_signing_algorithm: none ```