fix(coderd)!: add CODER_OIDC_IGNORE_USERINFO configuration option (#6922)

* add CODER_OIDC_IGNORE_USERINFO option
* chore: update docs for CODER_OIDC_IGNORE_USERINFO w.r.t ADFS
* fix!: codersdk: fix incorrectly named OIDC_GROUP_MAPPING -> CODER_OIDC_GROUP_MAPPING

docs/admin/auth.md

@@ -144,6 +144,10 @@ 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.
 
+> **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`.
+
 ### Email Addresses
 
 By default, Coder will look for the OIDC claim named `email` and use that
@@ -262,17 +266,37 @@ Below are some details specific to individual OIDC providers.
    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`.
+   - **Configure Web API**: Set the Client ID as the relying party identifier.
+   - **Application Permissions**: Allow access to the claims `openid`, `email`, `profile`, and `allatclaims`.
 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).
+   - `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.

docs/api/general.md

@@ -251,6 +251,7 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \
         "user": {}
       },
       "ignore_email_verified": true,
+      "ignore_user_info": true,
       "issuer_url": "string",
       "scopes": ["string"],
       "sign_in_text": "string",

docs/api/schemas.md

@@ -1877,6 +1877,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
         "user": {}
       },
       "ignore_email_verified": true,
+      "ignore_user_info": true,
       "issuer_url": "string",
       "scopes": ["string"],
       "sign_in_text": "string",
@@ -2224,6 +2225,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
       "user": {}
     },
     "ignore_email_verified": true,
+    "ignore_user_info": true,
     "issuer_url": "string",
     "scopes": ["string"],
     "sign_in_text": "string",
@@ -2890,6 +2892,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
     "user": {}
   },
   "ignore_email_verified": true,
+  "ignore_user_info": true,
   "issuer_url": "string",
   "scopes": ["string"],
   "sign_in_text": "string",
@@ -2911,6 +2914,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `groups_field`          | string                     | false    |              |             |
 | `icon_url`              | [clibase.URL](#clibaseurl) | false    |              |             |
 | `ignore_email_verified` | boolean                    | false    |              |             |
+| `ignore_user_info`      | boolean                    | false    |              |             |
 | `issuer_url`            | string                     | false    |              |             |
 | `scopes`                | array of string            | false    |              |             |
 | `sign_in_text`          | string                     | false    |              |             |

docs/cli/server.md

@@ -361,7 +361,7 @@ Change the OIDC default 'groups' claim field. By default, will be 'groups' if pr
 |             |                                        |
 | ----------- | -------------------------------------- |
 | Type        | <code>struct[map[string]string]</code> |
-| Environment | <code>$OIDC_GROUP_MAPPING</code>       |
+| Environment | <code>$CODER_OIDC_GROUP_MAPPING</code> |
 | Default     | <code>{}</code>                        |
 
 A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs.
@@ -384,6 +384,16 @@ URL pointing to the icon to use on the OepnID Connect login button.
 
 Ignore the email_verified claim from the upstream provider.
 
+### --oidc-ignore-userinfo
+
+|             |                                          |
+| ----------- | ---------------------------------------- |
+| Type        | <code>bool</code>                        |
+| Environment | <code>$CODER_OIDC_IGNORE_USERINFO</code> |
+| Default     | <code>false</code>                       |
+
+Ignore the userinfo endpoint and only use the ID token for user information.
+
 ### --oidc-issuer-url
 
 |             |                                     |