|
| 1 | +# Authentication |
| 2 | + |
| 3 | +By default, Coder is accessible via password authentication. Alternatively, you |
| 4 | +can configure Coder to enable logging in through GitHub OAuth or OpenID Connect. |
| 5 | +See below for configuration steps. |
| 6 | + |
| 7 | +## GitHub |
| 8 | + |
| 9 | +### Step 1: Configure the OAuth application in GitHub |
| 10 | + |
| 11 | +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: |
| 12 | + |
| 13 | +- **Homepage URL**: Set to your Coder domain (e.g. `https://coder.domain.com`) |
| 14 | +- **User Authorization Callback URL**: Set to `https://coder.domain.com/api/v2/users/oauth2/github/callback` |
| 15 | + |
| 16 | +Note the Client ID and Client Secret generated by GitHub. You will use these |
| 17 | +values in the next step. |
| 18 | + |
| 19 | +### Step 2: Configure Coder with the OAuth credentials |
| 20 | + |
| 21 | +Navigate to your Coder host and run the following command to start up the Coder |
| 22 | +server: |
| 23 | + |
| 24 | +```console |
| 25 | +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" |
| 26 | +``` |
| 27 | + |
| 28 | +Alternatively, if you are running Coder as a system service, you can achieve the |
| 29 | +same result as the command above by adding the following environment variables |
| 30 | +to the `/etc/coder.d/coder.env` file: |
| 31 | + |
| 32 | +```console |
| 33 | +CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true |
| 34 | +CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" |
| 35 | +CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" |
| 36 | +CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" |
| 37 | +``` |
| 38 | + |
| 39 | +Once complete, run `sudo service coder restart` to reboot Coder. |
| 40 | + |
| 41 | +## OpenID Connect with Google |
| 42 | + |
| 43 | +> Any OpenID connect provider can be used with Coder (e.g. Okta, Azure Active Directory, GitLab, Auth0). This example with Google should be used as guidance. |
| 44 | +
|
| 45 | +### Step 1: Configure the OAuth application on Google Cloud |
| 46 | + |
| 47 | +First, [register a Google OAuth app](https://support.google.com/cloud/answer/6158849?hl=en). Google will ask you for the following Coder parameters: |
| 48 | + |
| 49 | +- **Authorized JavaScript origins**: Set to your Coder domain (e.g. `https://coder.domain.com`) |
| 50 | +- **Redirect URIs**: Set to `https://coder.domain.com/api/v2/users/oidc/callback` |
| 51 | + |
| 52 | +### Step 2: Configure Coder with the OpenID Connect credentials |
| 53 | + |
| 54 | +Navigate to your Coder host and run the following command to start up the Coder |
| 55 | +server: |
| 56 | + |
| 57 | +```console |
| 58 | +coder server --oidc-issuer-url="https://accounts.google.com" --oidc-email-domain="your-domain" --oidc-client-id="533...ent.com" --oidc-client-secret="G0CSP...7qSM" |
| 59 | +``` |
| 60 | + |
| 61 | +Alternatively, if you are running Coder as a system service, you can achieve the |
| 62 | +same result as the command above by adding the following environment variables |
| 63 | +to the `/etc/coder.d/coder.env` file: |
| 64 | + |
| 65 | +```console |
| 66 | +CODER_OIDC_ISSUER_URL="https://accounts.google.com" |
| 67 | +CODER_OIDC_EMAIL_DOMAIN="your-domain" |
| 68 | +CODER_OIDC_CLIENT_ID="533...ent.com" |
| 69 | +CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM" |
| 70 | +``` |
| 71 | + |
| 72 | +Once complete, run `sudo service coder restart` to reboot Coder. |
| 73 | + |
| 74 | +> When a new user is created, the `preferred_username` claim becomes the username. If this claim is empty, the email address will be stripped of the domain, and become the username (e.g. `example@coder.com` becomes `example`). |
0 commit comments