From e97a3422684bd0c2d5ed221d74e274ed8045a552 Mon Sep 17 00:00:00 2001 From: Hugo Dutka Date: Mon, 12 May 2025 14:08:08 +0000 Subject: [PATCH 1/7] update docs --- docs/admin/users/github-auth.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index c556c87a2accb..1478c45fc8bee 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -5,11 +5,8 @@ By default, new Coder deployments use a Coder-managed GitHub app to authenticate users. We provide it for convenience, allowing you to experiment with Coder without setting up your own GitHub OAuth app. Once you authenticate with it, you -grant Coder server read access to: - -- Your GitHub user email -- Your GitHub organization membership -- Other metadata listed during the authentication flow +grant Coder server read access to your GitHub user email and other metadata listed +during the authentication flow. This access is necessary for the Coder server to complete the authentication process. To the best of our knowledge, Coder, the company, does not gain access @@ -27,7 +24,17 @@ up with GitHub, add the following environment variable: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true ``` -To limit sign ups to members of specific GitHub organizations, set: +You may limit sign ups to members of specific GitHub organizations, but the +GitHub app must be installed in the organizations you want to limit sign ups to. +**This will grant Coder, the company, access to your organizations' data as +described in the installation flow.** In a production environment, we recommend +configuring your own GitHub OAuth app as outlined further below, so all of your +data is kept private. + +If you'd like to proceed with the default GitHub app, install it in the +organizations you want to limit sign ups to by visiting +[this page](https://github.com/apps/coder/installations/select_target) and set +the following environment variable: ```env CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" From 87f5dfac402d7840e9267062453998a059eaec38 Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Wed, 28 May 2025 16:07:16 -0400 Subject: [PATCH 2/7] Apply suggestions from code review --- docs/admin/users/github-auth.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 1478c45fc8bee..856ec62a949d7 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -24,8 +24,7 @@ up with GitHub, add the following environment variable: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true ``` -You may limit sign ups to members of specific GitHub organizations, but the -GitHub app must be installed in the organizations you want to limit sign ups to. +[Install the GitHub app](https://github.com/apps/coder/installations/select_target) in every GitHub organization that you need to limit sign ups to. **This will grant Coder, the company, access to your organizations' data as described in the installation flow.** In a production environment, we recommend configuring your own GitHub OAuth app as outlined further below, so all of your From 70c254867bab883d1874137826276572bcbbac46 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Wed, 28 May 2025 20:51:31 +0000 Subject: [PATCH 3/7] reorganize github-auth --- docs/admin/users/github-auth.md | 47 ++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 856ec62a949d7..d318a5d3ef775 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -1,34 +1,36 @@ # GitHub -## Default Configuration - By default, new Coder deployments use a Coder-managed GitHub app to authenticate -users. We provide it for convenience, allowing you to experiment with Coder -without setting up your own GitHub OAuth app. Once you authenticate with it, you -grant Coder server read access to your GitHub user email and other metadata listed -during the authentication flow. +users. +We provide it for convenience, allowing you to experiment with Coder +without setting up your own GitHub OAuth app. + +If you authenticate with it, you grant Coder server read access to your GitHub +user email and other metadata listed during the authentication flow. This access is necessary for the Coder server to complete the authentication -process. To the best of our knowledge, Coder, the company, does not gain access +process. +To the best of our knowledge, Coder, the company, does not gain access to this data by administering the GitHub app. +## Default Configuration + > [!IMPORTANT] > The default GitHub app requires [device flow](#device-flow) to authenticate. -> This is enabled by default when using the default GitHub app. If you disable -> device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. +> +> This is enabled by default when using the default GitHub app. +> If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. -By default, only the admin user can sign up. To allow additional users to sign -up with GitHub, add the following environment variable: +By default, only the admin user can sign up. +To allow additional users to sign up with GitHub, add the following environment variable: ```env CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true ``` [Install the GitHub app](https://github.com/apps/coder/installations/select_target) in every GitHub organization that you need to limit sign ups to. -**This will grant Coder, the company, access to your organizations' data as -described in the installation flow.** In a production environment, we recommend -configuring your own GitHub OAuth app as outlined further below, so all of your -data is kept private. +This will grant Coder, the company, access to your organizations' data as described in the installation flow. +In a production environment, we recommend configuring your own GitHub OAuth app as outlined further below, so all of your data is kept private. If you'd like to proceed with the default GitHub app, install it in the organizations you want to limit sign ups to by visiting @@ -135,23 +137,24 @@ To upgrade Coder, run: helm upgrade coder-v2/coder -n -f values.yaml ``` -We recommend requiring and auditing MFA usage for all users in your GitHub -organizations. This can be enforced from the organization settings page in the -"Authentication security" sidebar tab. +We recommend requiring and auditing MFA usage for all users in your GitHub organizations. +This can be enforced from the organization settings page in the **Authentication security** sidebar tab. ## Device Flow Coder supports [device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow) -for GitHub OAuth. This is enabled by default for the default GitHub app and cannot be disabled -for that app. For your own custom GitHub OAuth app, you can enable device flow by setting: +for GitHub OAuth. +This is enabled by default for the default GitHub app and cannot be disabled for that app. + +For your own custom GitHub OAuth app, you can enable device flow by setting: ```env CODER_OAUTH2_GITHUB_DEVICE_FLOW=true ``` -Device flow is optional for custom GitHub OAuth apps. We generally recommend using -the standard OAuth flow instead, as it is more convenient for end users. +Device flow is optional for custom GitHub OAuth apps. +We generally recommend using the standard OAuth flow instead, as it is more convenient for end users. > [!NOTE] > If you're using the default GitHub app, device flow is always enabled regardless of From bf646fe7ee7601b32900bbb85fe6262bec97ced3 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Wed, 28 May 2025 21:38:05 +0000 Subject: [PATCH 4/7] reorganize github-auth --- docs/admin/users/github-auth.md | 64 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index d318a5d3ef775..1d164366b613f 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -16,46 +16,50 @@ to this data by administering the GitHub app. ## Default Configuration > [!IMPORTANT] -> The default GitHub app requires [device flow](#device-flow) to authenticate. +> The default GitHub app grants Coder access to your organizations' GitHub data. > -> This is enabled by default when using the default GitHub app. -> If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. +> For production environments, we strongly recommend that you +> [configure your own GitHub OAuth app](#step-1-configure-the-oauth-application-in-github) +> to ensure that your data is not shared with Coder (the company). -By default, only the admin user can sign up. -To allow additional users to sign up with GitHub, add the following environment variable: +To use the default configuration: -```env -CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true -``` +1. [Install the GitHub app](https://github.com/apps/coder/installations/select_target) + in any GitHub organization that you want to use with Coder. -[Install the GitHub app](https://github.com/apps/coder/installations/select_target) in every GitHub organization that you need to limit sign ups to. -This will grant Coder, the company, access to your organizations' data as described in the installation flow. -In a production environment, we recommend configuring your own GitHub OAuth app as outlined further below, so all of your data is kept private. + The default GitHub app requires [device flow](#device-flow) to authenticate. + This is enabled by default when using the default GitHub app. + If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. -If you'd like to proceed with the default GitHub app, install it in the -organizations you want to limit sign ups to by visiting -[this page](https://github.com/apps/coder/installations/select_target) and set -the following environment variable: +1. By default, only the admin user can sign up. + To allow additional users to sign up with GitHub, add: -```env -CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" -``` + ```shell + CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true + ``` + +1. **Configure Organization Restrictions (Optional)** + If you want to limit sign-ups to specific GitHub organizations, set: -For production deployments, we recommend configuring your own GitHub OAuth app -as outlined below. The default is automatically disabled if you configure your -own app or set: + ```shell + CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" + ``` -```env +## Disable the Default GitHub App + +You can disable the default GitHub app by [configuring your own app](#step-1-configure-the-oauth-application-in-github) +or by adding the following environment variable to your [Coder server configuration](../../reference/cli/server.md#options): + +```shell CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false ``` > [!NOTE] -> After you disable the default GitHub provider with the setting above, the -> **Sign in with GitHub** button might still appear on your login page even though -> the authentication flow is disabled. +> After you disable the default GitHub provider, the **Sign in with GitHub** button +> might still appear on your login page even though the authentication flow is disabled. > -> To completely hide the GitHub sign-in button, you must both disable the default -> provider and ensure you don't have a custom GitHub OAuth app configured. +> To completely hide the GitHub sign-in button, you must disable the default provider +> and ensure you don't have a custom GitHub OAuth app configured. ## Step 1: Configure the OAuth application in GitHub @@ -95,7 +99,7 @@ Alternatively, if you are running Coder as a system service, you can achieve the same result as the command above by adding the following environment variables to the `/etc/coder.d/coder.env` file: -```env +```shell CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" @@ -105,7 +109,7 @@ CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" > [!TIP] > To allow everyone to sign up using GitHub, set: > -> ```env +> ```shell > CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true > ``` @@ -149,7 +153,7 @@ This is enabled by default for the default GitHub app and cannot be disabled for For your own custom GitHub OAuth app, you can enable device flow by setting: -```env +```shell CODER_OAUTH2_GITHUB_DEVICE_FLOW=true ``` From e5c7ee361be03e30ae3b8bd5b3bdcee63fe6393e Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Thu, 29 May 2025 10:37:51 -0400 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Hugo Dutka --- docs/admin/users/github-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 1d164366b613f..903dcefc95b3a 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -16,7 +16,7 @@ to this data by administering the GitHub app. ## Default Configuration > [!IMPORTANT] -> The default GitHub app grants Coder access to your organizations' GitHub data. +> Installation of the default GitHub app grants Coder (the company) access to your organization's GitHub data. > > For production environments, we strongly recommend that you > [configure your own GitHub OAuth app](#step-1-configure-the-oauth-application-in-github) From cea427b37796e37c5682bd502be5f15e06e80f1b Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Thu, 29 May 2025 14:53:35 +0000 Subject: [PATCH 6/7] edit limit sign-ups step --- docs/admin/users/github-auth.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 903dcefc95b3a..f7c79bda4eee6 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -38,8 +38,7 @@ To use the default configuration: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true ``` -1. **Configure Organization Restrictions (Optional)** - If you want to limit sign-ups to specific GitHub organizations, set: +1. (Optional) If you want to limit sign-ups to specific GitHub organizations, set: ```shell CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" From 9bb8e5f0c4489d284eec10426f4a16be23f04041 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Thu, 29 May 2025 15:34:39 +0000 Subject: [PATCH 7/7] add step numbers --- docs/admin/users/github-auth.md | 34 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index f7c79bda4eee6..57ed6f9eeb37a 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -62,30 +62,30 @@ CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false ## Step 1: Configure the OAuth application in GitHub -First, -[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). -GitHub will ask you for the following Coder parameters: +1. [Register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). -- **Homepage URL**: Set to your Coder deployments - [`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g. - `https://coder.domain.com`) -- **User Authorization Callback URL**: Set to `https://coder.domain.com` +1. GitHub will ask you for the following Coder parameters: -If you want to allow multiple Coder deployments hosted on subdomains, such as -`coder1.domain.com`, `coder2.domain.com`, to authenticate with the -same GitHub OAuth app, then you can set **User Authorization Callback URL** to -the `https://domain.com` + - **Homepage URL**: Set to your Coder deployment's + [`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g. + `https://coder.domain.com`) + - **User Authorization Callback URL**: Set to `https://coder.domain.com` -Take note of the Client ID and Client Secret generated by GitHub. You will use these -values in the next step. + If you want to allow multiple Coder deployments hosted on subdomains, such as + `coder1.domain.com`, `coder2.domain.com`, to authenticate with the + same GitHub OAuth app, then you can set **User Authorization Callback URL** to + the `https://domain.com` -Coder will need permission to access user email addresses. Find the "Account -Permissions" settings for your app and select "read-only" for "Email addresses". +1. Take note of the Client ID and Client Secret generated by GitHub. + You will use these values in the next step. + +1. Coder needs permission to access user email addresses. + + Find the **Account Permissions** settings for your app and select **read-only** for **Email addresses**. ## Step 2: Configure Coder with the OAuth credentials -Navigate to your Coder host and run the following command to start up the Coder -server: +Go to your Coder host and run the following command to start up the Coder server: ```shell 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"