Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitfd24116

Browse files
bpmctEdwardAngertmatifali
authored
docs: clarify that CODER_EXTERNAL_AUTH_0_ID is used in callback URLs (#16879)
## Summary- Clarifies that the CODER_EXTERNAL_AUTH_0_ID value is used as part ofthe OAuth callback URL path- Adds explicit callback URL examples to GitLab and Bitbucket Serversections- Updates the GitHub OAuth app configuration instructions to be moreexplicit- 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 sectionsFixes#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>
1 parent00e1ea4 commitfd24116

File tree

1 file changed

+51
-20
lines changed

1 file changed

+51
-20
lines changed

‎docs/admin/external-auth.md

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,16 @@ application. The following providers have been tested and work with Coder:
1212
-[Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
1313
-[Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
1414
-[BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
15-
-[GitHub](#github)
15+
-[GitHub](#configure-a-github-oauth-app)
1616
-[GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
1717

1818
If you have experience with a provider that is not listed here, please
1919
[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)
2020

2121
##Configuration
2222

23+
###Set environment variables
24+
2325
After you create an OAuth application, set environment variables to configure the Coder server to use it:
2426

2527
```env
@@ -33,9 +35,15 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar"
3335
CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
3436
```
3537

36-
The`CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal
37-
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
38-
GitHub provider.
38+
The`CODER_EXTERNAL_AUTH_0_ID` environment variable is used as an identifier for the authentication provider.
39+
40+
This variable is used as part of the callback URL path that you must configure in your OAuth provider settings.
41+
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`.
42+
Set it with a value that helps you identify the provider.
43+
For example, if you use`CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your GitHub provider,
44+
configure your callback URL as`https://example.com/external-auth/primary-github/callback`.
45+
46+
###Add an authentication button to the workspace template
3947

4048
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:
4149

@@ -52,7 +60,8 @@ data "coder_external_auth" "github" {
5260
5361
```
5462

55-
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.
63+
Inside your Terraform code, you now have access to authentication variables.
64+
Reference the documentation for your chosen provider for more information on how to supply it with a token.
5665

5766
###Workspace CLI
5867

@@ -102,9 +111,13 @@ CODER_EXTERNAL_AUTH_0_ID="primary-bitbucket-server"
102111
CODER_EXTERNAL_AUTH_0_TYPE=bitbucket-server
103112
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx
104113
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
105-
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
114+
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.example.com/rest/oauth2/latest/authorize
106115
```
107116

117+
When configuring your Bitbucket OAuth application, set the redirect URI to
118+
`https://example.com/external-auth/primary-bitbucket-server/callback`.
119+
This callback path includes the value of`CODER_EXTERNAL_AUTH_0_ID`.
120+
108121
###Gitea
109122

110123
```env
@@ -116,21 +129,29 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
116129
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
117130
```
118131

119-
TheRedirect URI for Gitea should be
120-
`https://coder.company.org/external-auth/gitea/callback`.
132+
Theredirect URI for Gitea should be
133+
`https://coder.example.com/external-auth/gitea/callback`.
121134

122135
###GitHub
123136

124-
>[!TIP]
125-
>If you don't require fine-grained access control, it's easier to[configure a GitHub OAuth app](#configure-a-github-oauth-app).
137+
Use this section as a reference for environment variables to customize your setup
138+
or to integrate with an existing GitHub authentication.
139+
140+
For a more complete, step-by-step guide, follow the
141+
[configure a GitHub OAuth app](#configure-a-github-oauth-app) section instead.
126142

127143
```env
128-
CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
144+
CODER_EXTERNAL_AUTH_0_ID="primary-github"
129145
CODER_EXTERNAL_AUTH_0_TYPE=github
130146
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
131147
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
132148
```
133149

150+
When configuring your GitHub OAuth application, set the
151+
[authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url)
152+
as`https://example.com/external-auth/primary-github/callback`, where
153+
`primary-github` matches your`CODER_EXTERNAL_AUTH_0_ID` value.
154+
134155
###GitHub Enterprise
135156

136157
GitHub Enterprise requires the following environment variables:
@@ -145,6 +166,11 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize
145166
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
146167
```
147168

169+
When configuring your GitHub Enterprise OAuth application, set the
170+
[authorization callback URL](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url)
171+
as`https://example.com/external-auth/primary-github/callback`, where
172+
`primary-github` matches your`CODER_EXTERNAL_AUTH_0_ID` value.
173+
148174
###GitLab self-managed
149175

150176
GitLab self-managed requires the following environment variables:
@@ -155,12 +181,16 @@ CODER_EXTERNAL_AUTH_0_TYPE=gitlab
155181
# This value is the "Application ID"
156182
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
157183
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
158-
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.company.org/oauth/token/info"
159-
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.company.org/oauth/authorize"
160-
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
161-
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
184+
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.com/oauth/token/info"
185+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.com/oauth/authorize"
186+
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.com/oauth/token"
187+
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.example\.com
162188
```
163189

190+
When[configuring your GitLab OAuth application](https://docs.gitlab.com/17.5/integration/oauth_provider/),
191+
set the redirect URI to`https://example.com/external-auth/primary-gitlab/callback`.
192+
Note that the redirect URI must include the value of`CODER_EXTERNAL_AUTH_0_ID` (in this example,`primary-gitlab`).
193+
164194
###JFrog Artifactory
165195

166196
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.
173203
```env
174204
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
175205
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
176-
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
177-
CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
206+
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://example.com/oauth/token/info"
207+
CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.com
178208
```
179209

180210
>[!NOTE]
181-
>The`REGEX` variable must be set if using a customgit domain.
211+
>The`REGEX` variable must be set if using a customGit domain.
182212
183213
##Custom scopes
184214

@@ -194,8 +224,9 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
194224

195225
1.[Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
196226

197-
- Set the callback URL to
198-
`https://coder.example.com/external-auth/USER_DEFINED_ID/callback`.
227+
- Set the authorization callback URL to
228+
`https://coder.example.com/external-auth/primary-github/callback`, where`primary-github`
229+
is the value you set for`CODER_EXTERNAL_AUTH_0_ID`.
199230
- Deactivate Webhooks.
200231
- Enable fine-grained access to specific repositories or a subset of
201232
permissions for security.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp