From fff9d8459b63c545ef05699309fabea93fec97aa Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Tue, 11 Mar 2025 14:13:58 +0000 Subject: [PATCH 1/6] docs: clarify that CODER_EXTERNAL_AUTH_0_ID is used in callback URLs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit clarifies that the CODER_EXTERNAL_AUTH_0_ID value is used as part of the callback URL path when configuring external authentication providers. The documentation previously stated it was only for internal reference, which was misleading as it's a critical part of the OAuth provider configuration. Fixes #16851 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/admin/external-auth.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 1fbc2b600a430..b7e0ae8ecdaf2 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -33,9 +33,7 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar" CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg" ``` -The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal -reference. Set it with a value that helps you identify it. For example, you can use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your -GitHub provider. +The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider. **This ID is also used as part of the callback URL path** that you must configure in your OAuth provider settings. Set it with a value that helps you identify the provider. For example, you can use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your GitHub provider. Your callback URL would then be `https://your-coder-domain.com/external-auth/primary-github/callback`. Add the following code to any template to add a button to the workspace setup page which will allow you to authenticate with your provider: @@ -105,6 +103,8 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize ``` +When configuring your Bitbucket OAuth application, set the Redirect URI to `https://your-coder-domain.com/external-auth/primary-bitbucket-server/callback`. The callback path includes the value of `CODER_EXTERNAL_AUTH_0_ID`. + ### Gitea ```env @@ -161,6 +161,9 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org ``` +> [!IMPORTANT] +> When configuring your GitLab OAuth application, set the Redirect URI to `https://your-coder-domain.com/external-auth/primary-gitlab/callback`. Note that the callback URL must include the value of `CODER_EXTERNAL_AUTH_0_ID` (in this example, "primary-gitlab"). + ### JFrog Artifactory Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory. @@ -195,7 +198,8 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key" 1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) - Set the callback URL to - `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`. + `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`, where `USER_DEFINED_ID` + is the value you set for `CODER_EXTERNAL_AUTH_0_ID`. - Deactivate Webhooks. - Enable fine-grained access to specific repositories or a subset of permissions for security. From 632663ec00689d5df1fdff58abed1f57caf54557 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 18 Mar 2025 03:10:12 +0000 Subject: [PATCH 2/6] more consistent examples --- docs/admin/external-auth.md | 61 ++++++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 18 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index b7e0ae8ecdaf2..d5cb1ff0da0d5 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -12,7 +12,7 @@ application. The following providers have been tested and work with Coder: - [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) - [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2) - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) -- [GitHub](#github) +- [GitHub](#configure-a-github-oauth-app - [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) If you have experience with a provider that is not listed here, please @@ -20,6 +20,8 @@ If you have experience with a provider that is not listed here, please ## Configuration +### Set environment variables + After you create an OAuth application, set environment variables to configure the Coder server to use it: ```env @@ -33,7 +35,13 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar" CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg" ``` -The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider. **This ID is also used as part of the callback URL path** that you must configure in your OAuth provider settings. Set it with a value that helps you identify the provider. For example, you can use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your GitHub provider. Your callback URL would then be `https://your-coder-domain.com/external-auth/primary-github/callback`. +The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider. +This variable is used as part of the callback URL path that you must configure in your OAuth provider settings. +Set it with a value that helps you identify the provider. +For example, if you use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your GitHub provider, +your callback URL will be `https://example.com/external-auth/primary-github/callback`. + +### Add an authentication button to the workspace template Add the following code to any template to add a button to the workspace setup page which will allow you to authenticate with your provider: @@ -50,7 +58,8 @@ data "coder_external_auth" "github" { ``` -Inside your Terraform code, you now have access to authentication variables. Reference the documentation for your chosen provider for more information on how to supply it with a token. +Inside your Terraform code, you now have access to authentication variables. +Reference the documentation for your chosen provider for more information on how to supply it with a token. ### Workspace CLI @@ -100,10 +109,12 @@ CODER_EXTERNAL_AUTH_0_ID="primary-bitbucket-server" CODER_EXTERNAL_AUTH_0_TYPE=bitbucket-server CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx -CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize +CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.example.com/rest/oauth2/latest/authorize ``` -When configuring your Bitbucket OAuth application, set the Redirect URI to `https://your-coder-domain.com/external-auth/primary-bitbucket-server/callback`. The callback path includes the value of `CODER_EXTERNAL_AUTH_0_ID`. +When configuring your Bitbucket OAuth application, set the redirect URI to +`https://example.com/external-auth/primary-bitbucket-server/callback`. +This callback path includes the value of `CODER_EXTERNAL_AUTH_0_ID`. ### Gitea @@ -116,13 +127,16 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize" ``` -The Redirect URI for Gitea should be -`https://coder.company.org/external-auth/gitea/callback`. +The redirect URI for Gitea should be +`https://coder.example.org/external-auth/gitea/callback`. ### GitHub -> [!TIP] -> If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app). +Use this section as a reference for environment variables to customize your setup +or to integrate with an existing GitHub authentication. + +For a more complete, step-by-step guide, follow the +[configure a GitHub OAuth app](#configure-a-github-oauth-app) section instead. ```env CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID" @@ -131,6 +145,11 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx ``` +When configuring your GitHub OAuth application, set the +[authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url) +as `https://example.com/external-auth/USER_DEFINED_ID/callback`, where +`USER_DEFINED_ID` matches your `CODER_EXTERNAL_AUTH_0_ID` value (in this example, `USER_DEFINED_ID`). + ### GitHub Enterprise GitHub Enterprise requires the following environment variables: @@ -145,6 +164,11 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token" ``` +When configuring your GitHub Enterprise OAuth application, set the +[authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url) +as `https://example.com/external-auth/primary-github/callback`, where +`USER_DEFINED_ID` matches your `CODER_EXTERNAL_AUTH_0_ID` value (in this example, `primary-github`). + ### GitLab self-managed GitLab self-managed requires the following environment variables: @@ -155,14 +179,15 @@ CODER_EXTERNAL_AUTH_0_TYPE=gitlab # This value is the "Application ID" CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx -CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.company.org/oauth/token/info" -CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.company.org/oauth/authorize" -CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" -CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org +CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.org/oauth/token/info" +CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.org/oauth/authorize" +CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.org/oauth/token" +CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.example\.org ``` -> [!IMPORTANT] -> When configuring your GitLab OAuth application, set the Redirect URI to `https://your-coder-domain.com/external-auth/primary-gitlab/callback`. Note that the callback URL must include the value of `CODER_EXTERNAL_AUTH_0_ID` (in this example, "primary-gitlab"). +When [configuring your GitLab OAuth application](https://docs.gitlab.com/17.5/integration/oauth_provider/), +set the redirect URI to `https://example.com/external-auth/primary-gitlab/callback`. +Note that the redirect URI must include the value of `CODER_EXTERNAL_AUTH_0_ID` (in this example, `primary-gitlab`). ### JFrog Artifactory @@ -181,7 +206,7 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org ``` > [!NOTE] -> The `REGEX` variable must be set if using a custom git domain. +> The `REGEX` variable must be set if using a custom Git domain. ## Custom scopes @@ -197,8 +222,8 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key" 1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) - - Set the callback URL to - `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`, where `USER_DEFINED_ID` + - Set the authorization callback URL to + `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`, where `USER_DEFINED_ID` is the value you set for `CODER_EXTERNAL_AUTH_0_ID`. - Deactivate Webhooks. - Enable fine-grained access to specific repositories or a subset of From 21b35bd73eee3dc1fb4c74e056cf2ae693a79685 Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Tue, 18 Mar 2025 07:40:00 -0400 Subject: [PATCH 3/6] Update docs/admin/external-auth.md Co-authored-by: M Atif Ali --- docs/admin/external-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index d5cb1ff0da0d5..5aee556636122 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -128,7 +128,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize" ``` The redirect URI for Gitea should be -`https://coder.example.org/external-auth/gitea/callback`. +`https://coder.example.com/external-auth/gitea/callback`. ### GitHub From b3f4a7a8324085092ce3cf4e26054eb9e57a2a28 Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Tue, 18 Mar 2025 09:55:34 -0400 Subject: [PATCH 4/6] Update docs/admin/external-auth.md --- docs/admin/external-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 5aee556636122..4f8970c53d824 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -12,7 +12,7 @@ application. The following providers have been tested and work with Coder: - [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) - [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2) - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) -- [GitHub](#configure-a-github-oauth-app +- [GitHub](#configure-a-github-oauth-app) - [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) If you have experience with a provider that is not listed here, please From 429ee1d6e758251539c7ab0d7c0528977ac69e7b Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Tue, 18 Mar 2025 09:56:53 -0400 Subject: [PATCH 5/6] more consistent example urls --- docs/admin/external-auth.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 4f8970c53d824..09d3cd25f24d1 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -179,10 +179,10 @@ CODER_EXTERNAL_AUTH_0_TYPE=gitlab # This value is the "Application ID" CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx -CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.org/oauth/token/info" -CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.org/oauth/authorize" -CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.org/oauth/token" -CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.example\.org +CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.com/oauth/token/info" +CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.com/oauth/authorize" +CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.com/oauth/token" +CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.example\.com ``` When [configuring your GitLab OAuth application](https://docs.gitlab.com/17.5/integration/oauth_provider/), @@ -201,8 +201,8 @@ provider deployments. ```env CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token" -CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info" -CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org +CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://example.com/oauth/token/info" +CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.com ``` > [!NOTE] From 9461b64acb4b2d59523a355607189896479a0cfd Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 1 Apr 2025 20:52:25 +0000 Subject: [PATCH 6/6] set a better example --- docs/admin/external-auth.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 09d3cd25f24d1..5ea502102bb60 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -36,10 +36,12 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg" ``` The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider. + This variable is used as part of the callback URL path that you must configure in your OAuth provider settings. +If the value in your callback URL doesn't match the `CODER_EXTERNAL_AUTH_0_ID` value, authentication will fail with `redirect URI is not valid`. Set it with a value that helps you identify the provider. For example, if you use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your GitHub provider, -your callback URL will be `https://example.com/external-auth/primary-github/callback`. +configure your callback URL as `https://example.com/external-auth/primary-github/callback`. ### Add an authentication button to the workspace template @@ -66,7 +68,7 @@ Reference the documentation for your chosen provider for more information on how Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace: ```shell -coder external-auth access-token +coder external-auth access-token ``` ## Git-provider specific env variables @@ -139,7 +141,7 @@ For a more complete, step-by-step guide, follow the [configure a GitHub OAuth app](#configure-a-github-oauth-app) section instead. ```env -CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID" +CODER_EXTERNAL_AUTH_0_ID="primary-github" CODER_EXTERNAL_AUTH_0_TYPE=github CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx @@ -147,8 +149,8 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx When configuring your GitHub OAuth application, set the [authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url) -as `https://example.com/external-auth/USER_DEFINED_ID/callback`, where -`USER_DEFINED_ID` matches your `CODER_EXTERNAL_AUTH_0_ID` value (in this example, `USER_DEFINED_ID`). +as `https://example.com/external-auth/primary-github/callback`, where +`primary-github` matches your `CODER_EXTERNAL_AUTH_0_ID` value. ### GitHub Enterprise @@ -167,7 +169,7 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_t When configuring your GitHub Enterprise OAuth application, set the [authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url) as `https://example.com/external-auth/primary-github/callback`, where -`USER_DEFINED_ID` matches your `CODER_EXTERNAL_AUTH_0_ID` value (in this example, `primary-github`). +`primary-github` matches your `CODER_EXTERNAL_AUTH_0_ID` value. ### GitLab self-managed @@ -223,7 +225,7 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key" 1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) - Set the authorization callback URL to - `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`, where `USER_DEFINED_ID` + `https://coder.example.com/external-auth/primary-github/callback`, where `primary-github` is the value you set for `CODER_EXTERNAL_AUTH_0_ID`. - Deactivate Webhooks. - Enable fine-grained access to specific repositories or a subset of