|
| 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 | +> This is an example using Google as an OpenID connect provider that can be used as guidance. Any OpenID connect provider can be used with Coder (e.g. Okta, Azure Active Directory, GitLab, Auth0). |
| 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. `[email protected]` becomes `example`). |
0 commit comments