Authentication

Authentication

By default, Coder is accessible via password authentication.

The following steps explain how to set up GitHub OAuth or OpenID Connect.

GitHub

Step 1: Configure the OAuth application in GitHub

First, 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)
  • 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:

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 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:

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 service coder restart to reboot Coder.

OpenID Connect with Google

We describe how to set up the most popular OIDC provider, Google, but any (Okta, Azure Active Directory, GitLab, Auth0, etc.) may be used.

Step 1: Configure the OAuth application on Google Cloud

First, register a Google OAuth app. Google will ask you for the following Coder parameters:

  • Authorized JavaScript origins: Set to your Coder domain (e.g. https://coder.domain.com)
  • Redirect URIs: Set to https://coder.domain.com/api/v2/users/oidc/callback

Step 2: Configure Coder with the OpenID Connect credentials

Navigate to your Coder host and run the following command to start up the Coder server:

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"

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:

CODER_OIDC_ISSUER_URL="https://accounts.google.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain"
CODER_OIDC_CLIENT_ID="533...ent.com"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"

Once complete, run sudo service coder restart to reboot Coder.

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).

See an opportunity to improve our docs? Make an edit.