2022-08-01 04:05:35 +00:00
# Authentication
2023-02-23 18:07:21 +00:00
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.
2022-08-01 04:05:35 +00:00
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:
2023-02-01 20:05:45 +00:00
```console
2022-08-01 04:05:35 +00:00
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"
```
2022-08-09 01:49:51 +00:00
> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
2022-08-01 04:05:35 +00:00
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:
2023-02-01 20:05:45 +00:00
```console
2022-08-01 04:05:35 +00:00
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"
```
2022-11-25 18:03:07 +00:00
**Note:** To allow everyone to signup using GitHub, set:
2023-02-01 20:05:45 +00:00
```console
2022-11-25 18:03:07 +00:00
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
2022-08-01 04:05:35 +00:00
Once complete, run `sudo service coder restart` to reboot Coder.
2023-03-21 18:40:20 +00:00
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
value: true
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
value: "your-org"
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
value: "533...des"
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
value: "G0CSP...7qSM"
- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
value: true
```
To upgrade Coder, run:
```console
helm upgrade < release-name > coder-v2/coder -n < namespace > -f values.yaml
```
2023-02-23 18:07:21 +00:00
> 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.
2023-03-21 18:40:20 +00:00
## OpenID Connect
2023-01-30 21:14:18 +00:00
2023-03-21 18:40:20 +00:00
The following steps through how to integrate any OpenID Connect provider (Okta, Active Directory, etc.) to Coder.
2023-01-30 21:14:18 +00:00
2023-03-21 18:40:20 +00:00
### Step 1: Set Redirect URI with your OIDC provider
Your OIDC provider will ask you for the following parameter:
2023-01-30 21:14:18 +00:00
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
2023-03-21 18:40:20 +00:00
### Step 2: Configure Coder with the OpenID Connect credentials
2023-01-30 21:14:18 +00:00
Navigate to your Coder host and run the following command to start up the Coder
server:
2023-02-01 20:05:45 +00:00
```console
2023-03-21 18:40:20 +00:00
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
2023-01-30 21:14:18 +00:00
```
2023-03-21 18:40:20 +00:00
If you are running Coder as a system service, you can achieve the
2023-01-30 21:14:18 +00:00
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
2023-02-01 20:05:45 +00:00
```console
2023-03-21 18:40:20 +00:00
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
2023-01-30 21:14:18 +00:00
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.
2022-08-01 04:05:35 +00:00
2023-03-21 18:40:20 +00:00
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OIDC_ISSUER_URL
value: "https://issuer.corp.com"
- name: CODER_OIDC_EMAIL_DOMAIN
value: "your-domain-1,your-domain-2"
- name: CODER_OIDC_CLIENT_ID
value: "533...des"
- name: CODER_OIDC_CLIENT_SECRET
value: "G0CSP...7qSM"
2023-01-30 21:14:18 +00:00
```
2023-03-21 18:40:20 +00:00
To upgrade Coder, run:
2022-08-01 04:05:35 +00:00
2023-02-01 20:05:45 +00:00
```console
2023-03-21 18:40:20 +00:00
helm upgrade < release-name > coder-v2/coder -n < namespace > -f values.yaml
2022-08-01 04:05:35 +00:00
```
2023-01-30 21:14:18 +00:00
## OIDC Claims
2022-11-13 20:15:06 +00:00
2023-03-30 08:36:57 +00:00
When a user logs in for the first time via OIDC, Coder will merge both
the claims from the ID token and the claims obtained from hitting the
upstream provider's `userinfo` endpoint, and use the resulting data
as a basis for creating a new user or looking up an existing user.
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs
while signing in via OIDC as a new user. Coder will log the claim fields
returned by the upstream identity provider in a message containing the
string `got oidc claims` , as well as the user info returned.
2023-04-05 08:07:43 +00:00
> **Note:** If you need to ensure that Coder only uses information from
> the ID token and does not hit the UserInfo endpoint, you can set the
> configuration option `CODER_OIDC_IGNORE_USERINFO=true`.
2023-03-30 08:36:57 +00:00
### Email Addresses
By default, Coder will look for the OIDC claim named `email` and use that
value for the newly created user's email address.
If your upstream identity provider users a different claim, you can set
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
> **Note:** If this field is not present, Coder will attempt to use the
> claim field configured for `username` as an email address. If this field
> is not a valid email address, OIDC logins will fail.
### Email Address Verification
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
2023-02-07 19:22:02 +00:00
provider, Coder will validate that its value is `true` . If needed, you can
disable this behavior with the following setting:
2022-11-25 10:10:09 +00:00
2023-02-01 20:05:45 +00:00
```console
2022-11-25 10:10:09 +00:00
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
2023-02-07 19:22:02 +00:00
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
2023-03-30 08:36:57 +00:00
> "verified", regardless of what the upstream identity provider says.
### Usernames
2022-11-25 10:10:09 +00:00
2023-03-30 08:36:57 +00:00
When a new user logs in via OIDC, Coder will by default use the value
of the claim field named `preferred_username` as the the username.
2023-01-30 21:14:18 +00:00
2023-03-30 08:36:57 +00:00
If your upstream identity provider uses a different claim, you can
set `CODER_OIDC_USERNAME_FIELD` to the desired claim.
> **Note:** 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`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
## OIDC Login Customization
2023-02-07 19:22:02 +00:00
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
2023-01-31 18:33:25 +00:00
2023-02-01 20:05:45 +00:00
```console
2023-01-31 18:33:25 +00:00
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
2023-05-11 15:09:14 +00:00
## Disable Built-in Authentication
To remove email and password login, set the following environment variable on your
Coder deployment:
```console
CODER_DISABLE_PASSWORD_AUTH=true
```
2022-10-08 04:44:41 +00:00
## SCIM (enterprise)
2022-10-05 19:05:28 +00:00
2022-09-20 20:16:26 +00:00
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
2022-10-23 22:09:58 +00:00
authentication. Upon deactivation, users are [suspended ](./users.md#suspend-a-user )
2022-09-20 20:16:26 +00:00
and are not deleted. [Configure ](./configure.md ) your SCIM application with an
auth key and supply it the Coder server.
2023-02-01 20:05:45 +00:00
```console
2022-09-20 20:16:26 +00:00
CODER_SCIM_API_KEY="your-api-key"
```
2023-01-30 21:14:18 +00:00
## TLS
If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
2023-02-01 20:05:45 +00:00
```console
2023-01-30 21:14:18 +00:00
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
2023-02-07 19:22:02 +00:00
## 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.
2023-03-10 05:31:38 +00:00
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.
2023-02-07 19:22:02 +00:00
```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.
2023-03-21 19:25:45 +00:00
For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
or you want to have different group names in Coder than in your OIDC provider,
you can configure mapping between the two.
```console
# as an environment variable
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
# as a flag
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
```
2023-04-05 21:05:48 +00:00
Below is an example mapping in the Coder Helm chart:
```yaml
coder:
env:
- name: CODER_OIDC_GROUP_MAPPING
value: >
{"myOIDCGroupID": "myCoderGroupName"}
```
2023-03-21 19:25:45 +00:00
From the example above, users that belong to the `myOIDCGroupID` group in your
OIDC provider will be added to the `myCoderGroupName` group in Coder.
2023-02-07 19:22:02 +00:00
> **Note:** Groups are only updated on login.
2023-03-21 19:25:45 +00:00
[azure-gids]: https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
2023-03-30 08:36:57 +00:00
## Provider-Specific Guides
Below are some details specific to individual OIDC providers.
### Active Directory Federation Services (ADFS)
> **Note:** Tested on ADFS 4.0, Windows Server 2019
1. In your Federation Server, create a new application group for Coder. Follow the
steps as described [here. ](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs )
- **Server Application**: Note the Client ID.
- **Configure Application Credentials**: Note the Client Secret.
2023-04-05 08:07:43 +00:00
- **Configure Web API**: Set the Client ID as the relying party identifier.
- **Application Permissions**: Allow access to the claims `openid` , `email` , `profile` , and `allatclaims` .
2023-03-30 08:36:57 +00:00
1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note
the value for `issuer` .
> **Note:** This is usually of the form `https://adfs.corp/adfs/.well-known/openid-configuration`
1. In Coder's configuration file (or Helm values as appropriate), set the following
environment variables or their corresponding CLI arguments:
2023-04-05 08:07:43 +00:00
2023-03-30 08:36:57 +00:00
- `CODER_OIDC_ISSUER_URL` : the `issuer` value from the previous step.
- `CODER_OIDC_CLIENT_ID` : the Client ID from step 1.
- `CODER_OIDC_CLIENT_SECRET` : the Client Secret from step 1.
2023-04-05 08:07:43 +00:00
- `CODER_OIDC_AUTH_URL_PARAMS` : set to
```console
{"resource":"$CLIENT_ID"}
```
where `$CLIENT_ID` is the Client ID from step 1 ([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
This is required for the upstream OIDC provider to return the requested claims.
- `CODER_OIDC_IGNORE_USERINFO` : Set to `true` .
1. Configure [Issuance Transform Rules ](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims )
on your federation server to send the following claims:
- `preferred_username` : You can use e.g. "Display Name" as required.
- `email` : You can use e.g. the LDAP attribute "E-Mail-Addresses" as required.
- `email_verified` : Create a custom claim rule:
```console
=> issue(Type = "email_verified", Value = "true")
```
- (Optional) If using Group Sync, send the required groups in the configured groups claim field. See [here ](https://stackoverflow.com/a/55570286 ) for an example.