feat: allow configuring OIDC email claim and OIDC auth url parameters (#6867)

This commit: - Allows configuring the OIDC claim Coder uses for email addresses (by default, this is still email) - Allows customising the parameters sent to the upstream identity provider when requesting a token. This is still access_type=offline by default. - Updates documentation related to the above.
2026-09-24 15:04:27 +08:00 · 2023-03-30 09:36:57 +01:00
parent 6981f89cd8
commit 563c3ade06
17 changed files with 379 additions and 22 deletions
@@ -134,8 +134,32 @@ helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml

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

@@ -144,12 +168,25 @@ CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
 ```

 > **Note:** This will cause Coder to implicitly treat all OIDC emails as
-> "verified".
+> "verified", regardless of what the upstream identity provider says.

-When a new user is created, the `preferred_username` claim becomes the username.
+### 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 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 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
+
 If you'd like to change the OpenID Connect button text and/or icon, you can
 configure them like so:

@@ -214,3 +251,30 @@ OIDC provider will be added to the `myCoderGroupName` group in Coder.
 > **Note:** Groups are only updated on login.

 [azure-gids]: https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
+
+## 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.
+   - **Configure Web API**: Ensure the Client ID is set as the relying party identifier.
+   - **Application Permissions**: Allow access to the claims `openid`, `email`, and `profile`.
+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:
+   - `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.
+   - `CODER_OIDC_AUTH_URL_PARAMS`: set to `{"resource":"urn:microsoft:userinfo"}` ([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)). OIDC logins will fail if this is not set.
+1. Ensure that Coder has the required OIDC claims by performing either of the below:
+   - Configure your federation server to reuturn both the `email` and `preferred_username` fields by [creating a custom claim rule](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims), or
+   - Set `CODER_OIDC_EMAIL_FIELD="upn"`. This will use the User Principal Name as the user email, which is [guaranteed to be unique in an Active Directory Forest](https://learn.microsoft.com/en-us/windows/win32/ad/naming-properties#upn-format).
@@ -231,9 +231,11 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \
    },
    "oidc": {
      "allow_signups": true,
+      "auth_url_params": {},
      "client_id": "string",
      "client_secret": "string",
      "email_domain": ["string"],
+      "email_field": "string",
      "group_mapping": {},
      "groups_field": "string",
      "icon_url": {
@@ -1798,9 +1798,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a
    },
    "oidc": {
      "allow_signups": true,
+      "auth_url_params": {},
      "client_id": "string",
      "client_secret": "string",
      "email_domain": ["string"],
+      "email_field": "string",
      "group_mapping": {},
      "groups_field": "string",
      "icon_url": {
@@ -2144,9 +2146,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a
  },
  "oidc": {
    "allow_signups": true,
+    "auth_url_params": {},
    "client_id": "string",
    "client_secret": "string",
    "email_domain": ["string"],
+    "email_field": "string",
    "group_mapping": {},
    "groups_field": "string",
    "icon_url": {
@@ -2808,9 +2812,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 ```json
 {
  "allow_signups": true,
+  "auth_url_params": {},
  "client_id": "string",
  "client_secret": "string",
  "email_domain": ["string"],
+  "email_field": "string",
  "group_mapping": {},
  "groups_field": "string",
  "icon_url": {
@@ -2839,9 +2845,11 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | Name                    | Type                       | Required | Restrictions | Description |
 | ----------------------- | -------------------------- | -------- | ------------ | ----------- |
 | `allow_signups`         | boolean                    | false    |              |             |
+| `auth_url_params`       | object                     | false    |              |             |
 | `client_id`             | string                     | false    |              |             |
 | `client_secret`         | string                     | false    |              |             |
 | `email_domain`          | array of string            | false    |              |             |
+| `email_field`           | string                     | false    |              |             |
 | `group_mapping`         | object                     | false    |              |             |
 | `groups_field`          | string                     | false    |              |             |
 | `icon_url`              | [clibase.URL](#clibaseurl) | false    |              |             |
@@ -310,6 +310,16 @@ Base URL of a GitHub Enterprise deployment to use for Login with GitHub.

 Whether new users can sign up with OIDC.

+### --oidc-auth-url-params
+
+|             |                                          |
+| ----------- | ---------------------------------------- |
+| Type        | <code>struct[map[string]string]</code>   |
+| Environment | <code>$CODER_OIDC_AUTH_URL_PARAMS</code> |
+| Default     | <code>{"access_type": "offline"}</code>  |
+
+OIDC auth URL parameters to pass to the upstream provider.
+
 ### --oidc-client-id

 |             |                                    |
@@ -337,6 +347,16 @@ Client secret to use for Login with OIDC.

 Email domains that clients logging in with OIDC must match.

+### --oidc-email-field
+
+|             |                                      |
+| ----------- | ------------------------------------ |
+| Type        | <code>string</code>                  |
+| Environment | <code>$CODER_OIDC_EMAIL_FIELD</code> |
+| Default     | <code>email</code>                   |
+
+OIDC claim field to use as the email.
+
 ### --oidc-group-field

 |             |                                      |