synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
## 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>
This commit is contained in:
Ben Potter
2025-04-01 16:03:25 -05:00
committed by GitHub
parent 00e1ea4ccf
commit fd241164a9
1 changed files with 51 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/admin/external-auth.md
View File

@ -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](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) - [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/) - [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) - [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
If you have experience with a provider that is not listed here, please 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 ## Configuration
### Set environment variables
After you create an OAuth application, set environment variables to configure the Coder server to use it: After you create an OAuth application, set environment variables to configure the Coder server to use it:
```env ```env
@ -33,9 +35,15 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar"
CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg" CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
``` ```
The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider.
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. 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: 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 ### 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_TYPE=bitbucket-server
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=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 ### Gitea
```env ```env
@ -116,21 +129,29 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize" CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
``` ```
The Redirect URI for Gitea should be The redirect URI for Gitea should be
`https://coder.company.org/external-auth/gitea/callback`. `https://coder.example.com/external-auth/gitea/callback`.
### GitHub ### GitHub
> [!TIP] Use this section as a reference for environment variables to customize your setup
> If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app). 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 ```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_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx 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
GitHub Enterprise requires the following environment variables: 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" 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
GitLab self-managed requires the following environment variables: GitLab self-managed requires the following environment variables:
@ -155,12 +181,16 @@ CODER_EXTERNAL_AUTH_0_TYPE=gitlab
# This value is the "Application ID" # This value is the "Application ID"
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.company.org/oauth/token/info" CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.com/oauth/token/info"
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.company.org/oauth/authorize" CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.com/oauth/authorize"
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.com/oauth/token"
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org 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 ### JFrog Artifactory
Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for 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 ```env
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" 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_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_VALIDATE_URL="https://example.com/oauth/token/info"
CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.com
``` ```
> [!NOTE] > [!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 ## 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) 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 - Set the authorization callback URL to
`https://coder.example.com/external-auth/USER_DEFINED_ID/callback`. `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. - Deactivate Webhooks.
- Enable fine-grained access to specific repositories or a subset of - Enable fine-grained access to specific repositories or a subset of
permissions for security. permissions for security.