# OpenID Connect

The following steps through how to integrate any OpenID Connect provider (Okta,
Active Directory, etc.) to Coder.

<div className="fd-steps">
  <div className="fd-step">
    ## Set Redirect URI with your OIDC provider [#set-redirect-uri-with-your-oidc-provider]

    Your OIDC provider will ask you for the following parameter:

    * **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
  </div>

  <div className="fd-step">
    ## Configure Coder with the OpenID Connect credentials [#configure-coder-with-the-openid-connect-credentials]

    Set the following environment variables on your Coder deployment and restart Coder:

    ```ini
    CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
    CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
    CODER_OIDC_CLIENT_ID="533...des"
    CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
    ```
  </div>
</div>

## OIDC Claims [#oidc-claims]

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_LOG_FILTER=".*got oidc claims.*"` 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.

<Callout type="info" title="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`.
</Callout>

### Email Addresses [#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.

<Callout type="info" title="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.
</Callout>

### Email Address Verification [#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
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:

```ini
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```

<Callout type="info" title="Note">
  This will cause Coder to implicitly treat all OIDC emails as
  "verified", regardless of what the upstream identity provider says.
</Callout>

### Usernames [#usernames]

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.

If your upstream identity provider uses a different claim, you can set
`CODER_OIDC_USERNAME_FIELD` to the desired claim.

<Callout type="info" title="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.
</Callout>

## OIDC Login Customization [#oidc-login-customization]

If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:

```ini
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```

To change the icon and text above the OpenID Connect button, see application
name and logo url in [appearance](/beta-docs/admin/setup/appearance/) settings.

## Configure Refresh Tokens [#configure-refresh-tokens]

By default, OIDC access tokens typically expire after a short period.
This is typically after one hour, but varies by provider.

Without refresh tokens, users will be automatically logged out when their access token expires.

Follow [Configure OIDC Refresh Tokens](/beta-docs/admin/users/oidc-auth/refresh-tokens/) for provider-specific steps.

The general steps to configure persistent user sessions are:

1. Configure your Coder OIDC settings:

   For most providers, add the `offline_access` scope:

   ```ini
   CODER_OIDC_SCOPES=openid,profile,email,offline_access
   ```

   For Google, add auth URL parameters (`CODER_OIDC_AUTH_URL_PARAMS`) too:

   ```ini
   CODER_OIDC_SCOPES=openid,profile,email
   CODER_OIDC_AUTH_URL_PARAMS='{"access_type": "offline", "prompt": "consent"}'
   ```

2. Configure your identity provider to issue refresh tokens.

3. After configuration, have users log out and back in once to obtain refresh tokens

<Callout type="idea" title="Important">
  Misconfigured refresh tokens can lead to frequent user authentication prompts.
</Callout>

## Disable Built-in Authentication [#disable-built-in-authentication]

To remove email and password login, set the following environment variable on
your Coder deployment:

```ini
CODER_DISABLE_PASSWORD_AUTH=true
```

## SCIM [#scim]

<Callout type="idea" title="Important">
  SCIM is a Premium feature
  ([learn more](https://coder.com/pricing#compare-plans)).

  Coder's SCIM 2.0 implementation is not a fully certified or guaranteed
  implementation of the [SCIM 2.0 specification](https://datatracker.ietf.org/doc/html/rfc7644).
  It is intended to cover common user provisioning and deprovisioning flows
  with the major identity providers (Okta, Microsoft Entra ID, etc.). Specific
  attributes, endpoints, or behaviors required by your IdP may not be
  supported, and compatibility may change between releases. If you depend on
  a specific SCIM behavior, [contact us](https://coder.com/contact) before
  rolling it out broadly. See
  [coder/coder#15830](https://github.com/coder/coder/issues/15830) for
  tracked gaps and ongoing work.
</Callout>

Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
authentication. Upon deactivation, users are
[suspended](/beta-docs/admin/users/#suspend-a-user) and are not deleted.
[Configure](/beta-docs/admin/setup/) your SCIM application with an auth key and supply
it the Coder server.

```ini
CODER_SCIM_AUTH_HEADER="your-api-key"
```

### SCIM 2.0 handler [#scim-20-handler]

Coder includes an opt-in SCIM 2.0 handler that follows [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) and has been verified against an external SCIM 2.0 compliance suite.
It supports the following:

* User provisioning and deprovisioning
* User listing

To opt in, set:

```ini
CODER_SCIM_USE_LEGACY=false
```

This is also available as the `--scim-use-legacy` server flag and the `scimUseLegacy` YAML option.
Changing it requires a restart of the Coder server.

Behavior notes:

* Coder never hard-deletes users. `DELETE /scim/v2/Users/{id}` and deactivation (`active: false`) both [suspend](/beta-docs/admin/users/#suspend-a-user) the user.
* Re-activating or re-creating a previously suspended user places them in the dormant state, and they become active again on their next login.
* Usernames are immutable. Attempts to change `userName` via `PUT` or `PATCH` return a `mutability` error.

The SCIM 2.0 handler will eventually become the default behavior.

## TLS [#tls]

If your OpenID Connect provider requires client TLS certificates for
authentication, you can configure them like so:

```ini
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```

## Next steps [#next-steps]

* [Group Sync](/beta-docs/admin/users/idp-sync/)
* [Groups & Roles](/beta-docs/admin/users/groups-roles/)
* [Configure OIDC Refresh Tokens](/beta-docs/admin/users/oidc-auth/refresh-tokens/)