Skip to content

Commit 345001f

Browse files
hugodutkaEdwardAngert
hugodutka
and
EdwardAngert
authored
docs: update the GitHub Auth section (#17769)
Addresses #17752 [preview](https://coder.com/docs/@hugodutka%2Fgithub%2Dauth%2Dorg%2Ddocs/admin/users/github-auth) --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
1 parent 177bda3 commit 345001f

File tree

1 file changed

+69
-57
lines changed

1 file changed

+69
-57
lines changed

‎docs/admin/users/github-auth.md

Lines changed: 69 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,91 @@
11
# GitHub
22

3-
## Default Configuration
4-
53
By default, new Coder deployments use a Coder-managed GitHub app to authenticate
6-
users. We provide it for convenience, allowing you to experiment with Coder
7-
without setting up your own GitHub OAuth app. Once you authenticate with it, you
8-
grant Coder server read access to:
4+
users.
5+
We provide it for convenience, allowing you to experiment with Coder
6+
without setting up your own GitHub OAuth app.
97

10-
- Your GitHub user email
11-
- Your GitHub organization membership
12-
- Other metadata listed during the authentication flow
8+
If you authenticate with it, you grant Coder server read access to your GitHub
9+
user email and other metadata listed during the authentication flow.
1310

1411
This access is necessary for the Coder server to complete the authentication
15-
process. To the best of our knowledge, Coder, the company, does not gain access
12+
process.
13+
To the best of our knowledge, Coder, the company, does not gain access
1614
to this data by administering the GitHub app.
1715

16+
## Default Configuration
17+
1818
> [!IMPORTANT]
19-
> The default GitHub app requires [device flow](#device-flow) to authenticate.
20-
> This is enabled by default when using the default GitHub app. If you disable
21-
> device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored.
19+
> Installation of the default GitHub app grants Coder (the company) access to your organization's GitHub data.
20+
>
21+
> For production environments, we strongly recommend that you
22+
> [configure your own GitHub OAuth app](#step-1-configure-the-oauth-application-in-github)
23+
> to ensure that your data is not shared with Coder (the company).
2224
23-
By default, only the admin user can sign up. To allow additional users to sign
24-
up with GitHub, add the following environment variable:
25+
To use the default configuration:
2526

26-
```env
27-
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
28-
```
27+
1. [Install the GitHub app](https://github.com/apps/coder/installations/select_target)
28+
in any GitHub organization that you want to use with Coder.
2929

30-
To limit sign ups to members of specific GitHub organizations, set:
30+
The default GitHub app requires [device flow](#device-flow) to authenticate.
31+
This is enabled by default when using the default GitHub app.
32+
If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored.
3133

32-
```env
33-
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
34-
```
34+
1. By default, only the admin user can sign up.
35+
To allow additional users to sign up with GitHub, add:
36+
37+
```shell
38+
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
39+
```
3540

36-
For production deployments, we recommend configuring your own GitHub OAuth app
37-
as outlined below. The default is automatically disabled if you configure your
38-
own app or set:
41+
1. (Optional) If you want to limit sign-ups to specific GitHub organizations, set:
3942

40-
```env
43+
```shell
44+
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
45+
```
46+
47+
## Disable the Default GitHub App
48+
49+
You can disable the default GitHub app by [configuring your own app](#step-1-configure-the-oauth-application-in-github)
50+
or by adding the following environment variable to your [Coder server configuration](../../reference/cli/server.md#options):
51+
52+
```shell
4153
CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false
4254
```
4355

4456
> [!NOTE]
45-
> After you disable the default GitHub provider with the setting above, the
46-
> **Sign in with GitHub** button might still appear on your login page even though
47-
> the authentication flow is disabled.
57+
> After you disable the default GitHub provider, the **Sign in with GitHub** button
58+
> might still appear on your login page even though the authentication flow is disabled.
4859
>
49-
> To completely hide the GitHub sign-in button, you must both disable the default
50-
> provider and ensure you don't have a custom GitHub OAuth app configured.
60+
> To completely hide the GitHub sign-in button, you must disable the default provider
61+
> and ensure you don't have a custom GitHub OAuth app configured.
5162
5263
## Step 1: Configure the OAuth application in GitHub
5364

54-
First,
55-
[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
56-
GitHub will ask you for the following Coder parameters:
65+
1. [Register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
66+
67+
1. GitHub will ask you for the following Coder parameters:
5768

58-
- **Homepage URL**: Set to your Coder deployments
59-
[`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g.
60-
`https://coder.domain.com`)
61-
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
69+
- **Homepage URL**: Set to your Coder deployment's
70+
[`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g.
71+
`https://coder.domain.com`)
72+
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
6273

63-
If you want to allow multiple Coder deployments hosted on subdomains, such as
64-
`coder1.domain.com`, `coder2.domain.com`, to authenticate with the
65-
same GitHub OAuth app, then you can set **User Authorization Callback URL** to
66-
the `https://domain.com`
74+
If you want to allow multiple Coder deployments hosted on subdomains, such as
75+
`coder1.domain.com`, `coder2.domain.com`, to authenticate with the
76+
same GitHub OAuth app, then you can set **User Authorization Callback URL** to
77+
the `https://domain.com`
6778

68-
Take note of the Client ID and Client Secret generated by GitHub. You will use these
69-
values in the next step.
79+
1. Take note of the Client ID and Client Secret generated by GitHub.
80+
You will use these values in the next step.
7081

71-
Coder will need permission to access user email addresses. Find the "Account
72-
Permissions" settings for your app and select "read-only" for "Email addresses".
82+
1. Coder needs permission to access user email addresses.
83+
84+
Find the **Account Permissions** settings for your app and select **read-only** for **Email addresses**.
7385

7486
## Step 2: Configure Coder with the OAuth credentials
7587

76-
Navigate to your Coder host and run the following command to start up the Coder
77-
server:
88+
Go to your Coder host and run the following command to start up the Coder server:
7889

7990
```shell
8091
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
@@ -87,7 +98,7 @@ Alternatively, if you are running Coder as a system service, you can achieve the
8798
same result as the command above by adding the following environment variables
8899
to the `/etc/coder.d/coder.env` file:
89100

90-
```env
101+
```shell
91102
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
92103
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
93104
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
@@ -97,7 +108,7 @@ CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
97108
> [!TIP]
98109
> To allow everyone to sign up using GitHub, set:
99110
>
100-
> ```env
111+
> ```shell
101112
> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
102113
> ```
103114
@@ -129,23 +140,24 @@ To upgrade Coder, run:
129140
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
130141
```
131142

132-
We recommend requiring and auditing MFA usage for all users in your GitHub
133-
organizations. This can be enforced from the organization settings page in the
134-
"Authentication security" sidebar tab.
143+
We recommend requiring and auditing MFA usage for all users in your GitHub organizations.
144+
This can be enforced from the organization settings page in the **Authentication security** sidebar tab.
135145

136146
## Device Flow
137147

138148
Coder supports
139149
[device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)
140-
for GitHub OAuth. This is enabled by default for the default GitHub app and cannot be disabled
141-
for that app. For your own custom GitHub OAuth app, you can enable device flow by setting:
150+
for GitHub OAuth.
151+
This is enabled by default for the default GitHub app and cannot be disabled for that app.
142152

143-
```env
153+
For your own custom GitHub OAuth app, you can enable device flow by setting:
154+
155+
```shell
144156
CODER_OAUTH2_GITHUB_DEVICE_FLOW=true
145157
```
146158

147-
Device flow is optional for custom GitHub OAuth apps. We generally recommend using
148-
the standard OAuth flow instead, as it is more convenient for end users.
159+
Device flow is optional for custom GitHub OAuth apps.
160+
We generally recommend using the standard OAuth flow instead, as it is more convenient for end users.
149161

150162
> [!NOTE]
151163
> If you're using the default GitHub app, device flow is always enabled regardless of

0 commit comments

Comments
 (0)