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 (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,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.