From 76ae807243cfe5a7491ec46b498425248bb6d2b6 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 21 Jun 2022 16:40:55 -0500 Subject: [PATCH 1/3] init: oauth docs --- docs/oauth.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/oauth.md diff --git a/docs/oauth.md b/docs/oauth.md new file mode 100644 index 0000000000000..930a801ab65c9 --- /dev/null +++ b/docs/oauth.md @@ -0,0 +1,38 @@ +# GitHub OAuth + +By default, Coder is accessible via built-in authentication. Alternatively, you +can configure Coder to enable logging in through GitHub OAuth. See below for +configuration steps. + +## Step 1: Configure the OAuth application in GitHub + +When [https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/](creating an OAuth app), +GitHub will ask you for the following Coder parameters: + +- **Homepage URL**: Set to your Coder domain, e.g. `https://coder.domain.com` +- **User Authorization Callback URL**: Set to `https://coder.domain.com/api/v2/users/oauth2/github/callback` + +Note the Client ID and Client secret generated by GitHub. You will use these +values in the next step. + +## Step 2: Configure Coder with the OAuth credentials + +Navigate to your Coder host and run the following command to start up the Coder +server: + +```console +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" +``` + +Alternatively, if you already have a running Coder instance, you can achieve the +same result as the command above by adding the following environment variables +to the `/etc/coder.d/coder.env` file: + +```console +CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true +CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" +CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" +CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" +``` + +Once complete, run `sudo systemctl enable --now coder` to reboot Coder. From 0607e8cd6dcf48251c4c187391542b0c07351a12 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 21 Jun 2022 17:04:10 -0500 Subject: [PATCH 2/3] chore: update directories --- docs/{ => install}/oauth.md | 0 docs/{ => install}/postgres.md | 0 docs/manifest.json | 9 +++++++-- 3 files changed, 7 insertions(+), 2 deletions(-) rename docs/{ => install}/oauth.md (100%) rename docs/{ => install}/postgres.md (100%) diff --git a/docs/oauth.md b/docs/install/oauth.md similarity index 100% rename from docs/oauth.md rename to docs/install/oauth.md diff --git a/docs/postgres.md b/docs/install/postgres.md similarity index 100% rename from docs/postgres.md rename to docs/install/postgres.md diff --git a/docs/manifest.json b/docs/manifest.json index c2cd73c15bba6..2989021d437dc 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -26,8 +26,13 @@ { "title": "Postgres", "description": "Learn how to create and use your own Postgres database.", - "path": "./postgres.md" - } + "path": "./install/postgres.md" + }, + { + "title": "GitHub OAuth", + "description": "Learn how to authenticate with GitHub.", + "path": "./install/oauth.md" + } ] }, { From 5720279323d37e978e44d1612eaa1b9458410c7d Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Wed, 22 Jun 2022 11:48:52 -0500 Subject: [PATCH 3/3] update: feedback --- docs/install/oauth.md | 12 ++++++------ docs/manifest.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/install/oauth.md b/docs/install/oauth.md index 930a801ab65c9..db654aa66081c 100644 --- a/docs/install/oauth.md +++ b/docs/install/oauth.md @@ -6,13 +6,13 @@ configuration steps. ## Step 1: Configure the OAuth application in GitHub -When [https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/](creating an OAuth app), -GitHub will ask you for the following Coder parameters: +First, [https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/](register a GitHub OAuth app). GitHub will ask you for the following Coder parameters: -- **Homepage URL**: Set to your Coder domain, e.g. `https://coder.domain.com` + +- **Homepage URL**: Set to your Coder domain (e.g. `https://coder.domain.com`) - **User Authorization Callback URL**: Set to `https://coder.domain.com/api/v2/users/oauth2/github/callback` -Note the Client ID and Client secret generated by GitHub. You will use these +Note the Client ID and Client Secret generated by GitHub. You will use these values in the next step. ## Step 2: Configure Coder with the OAuth credentials @@ -24,7 +24,7 @@ server: 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" ``` -Alternatively, if you already have a running Coder instance, you can achieve the +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: @@ -35,4 +35,4 @@ CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" ``` -Once complete, run `sudo systemctl enable --now coder` to reboot Coder. +Once complete, run `sudo service coder restart` to reboot Coder. diff --git a/docs/manifest.json b/docs/manifest.json index 2989021d437dc..ad6b25e6a33f9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -30,7 +30,7 @@ }, { "title": "GitHub OAuth", - "description": "Learn how to authenticate with GitHub.", + "description": "Learn how to set up OAuth using your GitHub organization.", "path": "./install/oauth.md" } ]