mirror of
https://github.com/coder/coder.git
synced 2025-07-09 11:45:56 +00:00
* feat: Allow changing the 'group' oidc claim field * Enable empty groups support * fix: Delete was wiping all groups, not just the single user's groups * Update docs * fix: Dbfake delete group member fixed
201 lines
7.3 KiB
Markdown
201 lines
7.3 KiB
Markdown
# Authentication
|
|
|
|
By default, Coder is accessible via password authentication. Coder does not
|
|
recommend using password authentication in production, and recommends using an
|
|
authentication provider with properly configured multi-factor authentication
|
|
(MFA). It is your responsibility to ensure the auth provider enforces MFA
|
|
correctly.
|
|
|
|
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](https://developer.github.com/apps/building-oauth-apps/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"
|
|
```
|
|
|
|
> 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:
|
|
|
|
```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"
|
|
```
|
|
|
|
**Note:** To allow everyone to signup using GitHub, set:
|
|
|
|
```console
|
|
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
|
|
```
|
|
|
|
Once complete, run `sudo service coder restart` to reboot Coder.
|
|
|
|
> We recommend requiring and auditing MFA usage for all users in your GitHub
|
|
> organizations. This can be enforced from the organization settings page in the
|
|
> "Authentication security" sidebar tab.
|
|
|
|
## GitLab
|
|
|
|
### Step 1: Configure the OAuth application in your GitLab instance
|
|
|
|
First, [register a GitLab OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html). 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 Gitlab OpenID Connect credentials
|
|
|
|
Navigate to your Coder host and run the following command to start up the Coder
|
|
server:
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
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.
|
|
|
|
> We recommend requiring and auditing MFA usage for all users in your GitLab
|
|
> organizations or deployment. This can be enforced for an organization from the
|
|
> organization settings page in the "Permissions and group features" section.
|
|
> For deployments, this can be enforced in the Admin area, under the "Settings >
|
|
> General" sidebar tab in the "Sign-in restrictions" section.
|
|
|
|
### Additional Notes
|
|
|
|
GitLab maintains configuration settings for OIDC applications at the following URL:
|
|
|
|
```console
|
|
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](https://support.google.com/cloud/answer/6158849?hl=en). 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 Google OpenID Connect credentials
|
|
|
|
Navigate to your Coder host and run the following command to start up the Coder
|
|
server:
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
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](./users.md#suspend-a-user)
|
|
and are not deleted. [Configure](./configure.md) your SCIM application with an
|
|
auth key and supply it the Coder server.
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
|
|
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
|
|
```
|
|
|
|
## Group Sync (enterprise)
|
|
|
|
If your OpenID Connect provider supports group claims, you can configure Coder
|
|
to synchronize groups in your auth provider to groups within Coder.
|
|
|
|
To enable group sync, ensure that the `groups` claim is set. If group sync is
|
|
enabled, the user's groups will be controlled by the OIDC provider. This means
|
|
manual group additions/removals will be overwritten on the next login.
|
|
|
|
```console
|
|
# as an environment variable
|
|
CODER_OIDC_SCOPES=openid,profile,email,groups
|
|
# as a flag
|
|
--oidc-scopes openid,profile,email,groups
|
|
```
|
|
|
|
On login, users will automatically be assigned to groups that have matching
|
|
names in Coder and removed from groups that the user no longer belongs to.
|
|
|
|
> **Note:** Groups are only updated on login.
|