5.7 KiB
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"
For GitHub Enterprise support, specify the
--oauth2-github-enterprise-base-url
flag.
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"
Note: To allow everyone to signup using GitHub, set:
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
Once complete, run sudo service coder restart
to reboot Coder.
GitLab
Step 1: Configure the OAuth application in your GitLab instance
First, register a GitLab OAuth application. GitLab will ask you for the following parameter:
- Redirect URI: 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://gitlab.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --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://gitlab.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
CODER_OIDC_CLIENT_ID="533...des"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
Once complete, run sudo service coder restart
to reboot Coder.
Additional Notes
GitLab maintains configuration settings for OIDC applications at the following URL:
https://gitlab.com/.well-known/openid-configuration
If you are using a self-hosted GitLab instance, replace gitlab.com
in the above URL
with your internal domain. The same will apply for the OIDC_ISSUER_URL
variable.
OpenID Connect with Google
Step 1: Configure the OAuth application on Google Cloud
First, register a Google OAuth application. 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-1,your-domain-2" --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-1,your-domain-2"
CODER_OIDC_CLIENT_ID="533...ent.com"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
Once complete, run sudo service coder restart
to reboot Coder.
OIDC Claims
Coder requires all OIDC email addresses to be verified by default. If the email_verified
claim is present in the token response from the identity provider, Coder will validate that its value is true
.
If needed, you can disable this behavior with the following setting:
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
Note: This will cause Coder to implicitly treat all OIDC emails as "verified".
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
).
If you'd like to change the OpenID Connect button text and/or icon, you can configure them like so:
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
SCIM (enterprise)
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header authentication. Upon deactivation, users are suspended and are not deleted. Configure your SCIM application with an auth key and supply it the Coder server.
CODER_SCIM_API_KEY="your-api-key"
TLS
If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem