docs: clarify that CODER_EXTERNAL_AUTH_0_ID is used in callback URLs (#16879)

bpmct · EdwardAngert · matifali · web-flow · commit fd241164a949 · 2025-04-01T17:03:25.000-04:00
## Summary - Clarifies that the CODER_EXTERNAL_AUTH_0_ID value is used as part of the OAuth callback URL path - Adds explicit callback URL examples to GitLab and Bitbucket Server sections - Updates the GitHub OAuth app configuration instructions to be more explicit - Fixes the documentation mistake where it claimed this ID was only for "internal reference" ## Test plan - Documentation change only - Verified consistency across all OAuth provider sections Fixes #16851 [preview](https://coder.com/docs/@fix-external-auth-docs-16851/admin/external-auth) <sub>🤖 Generated with [Claude Code](https://claude.ai/code)</sub> --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com> Co-authored-by: M Atif Ali <atif@coder.com>
diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md
@@ -12,14 +12,16 @@ 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
 [file an issue](https://github.com/coder/internal/issues/new?title=request%28docs%29%3A+external-auth+-+request+title+here%0D%0A&labels=["customer-feedback","docs"]&body=doc%3A+%5Bexternal-auth%5D%28https%3A%2F%2Fcoder.com%2Fdocs%2Fadmin%2Fexternal-auth%29%0D%0A%0D%0Aplease+enter+your+request+here%0D%0A)
 
 ## Configuration
 
+### Set environment variables
+
 After you create an OAuth application, set environment variables to configure the Coder server to use it:
 
 ```env
@@ -33,9 +35,15 @@ 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 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,
+configure your callback URL as `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:
 
@@ -52,7 +60,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
 
@@ -102,9 +111,13 @@ 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://example.com/external-auth/primary-bitbucket-server/callback`.
+This callback path includes the value of `CODER_EXTERNAL_AUTH_0_ID`.
+
 ### Gitea
 
 ```env
@@ -116,21 +129,29 @@ 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.com/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"
+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
 ```
 
+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/primary-github/callback`, where
+`primary-github` matches your `CODER_EXTERNAL_AUTH_0_ID` value.
+
 ### GitHub Enterprise
 
 GitHub Enterprise requires the following environment variables:
@@ -145,6 +166,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
+`primary-github` matches your `CODER_EXTERNAL_AUTH_0_ID` value.
+
 ### GitLab self-managed
 
 GitLab self-managed requires the following environment variables:
@@ -155,12 +181,16 @@ 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.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/),
+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
 
 Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
@@ -173,12 +203,12 @@ 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]
-> 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
 
@@ -194,8 +224,9 @@ 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`.
+   - Set the authorization callback URL to
+     `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
      permissions for security.
