# 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

    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

    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

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

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

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

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

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](/docs/@v2.33.6/admin/setup/appearance/) settings.

## 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](/docs/@v2.33.6/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

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

```ini
CODER_DISABLE_PASSWORD_AUTH=true
```

## SCIM

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

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

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

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

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