Files
coder/docs/admin/users/idp-sync.md
Jaayden HalkoandJake Howell d1a58b9f5d feat: add script to check for title case (#21484)
Historically, much of the UI used title case. This PR adds a lint check
that reports title case UI text so it can be converted to sentence case,
and converts the existing text.

- `site/scripts/check-sentence-case.mjs` runs as `pnpm
lint:sentence-case` and is part of `pnpm lint`. It reads JSX text and
string/template literals from the TypeScript AST and skips literals that
are code rather than UI text (imports, types, property names, tagged
templates, values of JSX attributes that are not displayed such as
`className` or `style`, and operands of `===`/`case` comparisons). JSX
text across inline elements and conditional JSX is checked as one
phrase. `--fix` lowercases the reported words. The checker is a
heuristic: it is not meant to model every code shape, so use a
`sentence-case-expect` comment where it guesses wrong.
- Proper nouns (Coder products, role names, third-party products,
protocols, font names) live in `PROPER_NOUNS`. For other deliberate
exceptions, a `sentence-case-expect` comment on the line above
suppresses the report and fails when that line no longer needs it.
- Existing UI text is converted to sentence case, and tests that assert
on it are updated.
- Deployment option lookups (`useDeploymentOptions`) now use CLI flags
instead of display names, so they do not depend on UI wording.

## Performance

`pnpm lint:sentence-case` takes **1.6 s** and is 2% to 4.5% of `pnpm
lint`. Measured on 82317c925e in a dev workspace (Xeon Platinum 8375C,
16 vCPUs, Node 22.23.4, TypeScript 6.0.2, warm file cache). CI buffers
the output of the lint steps, so its log has no per-step times to
compare against.

| Measurement (20 runs) | Result |
|---|---|
| Wall time | 1.64 s mean, 0.03 s standard deviation, 1.62 s to 1.71 s |
| CPU time | 3.0 s |
| Peak memory (RSS) | 154 MB, of which 116 MB is Node with `typescript`
loaded |
| Input | 1,301 of the 2,199 `.ts` and `.tsx` files in `site/src` (the
rest are excluded), 210,684 lines, 6.1 MB |
| Throughput | About 130,000 lines per second |
| Time per file | 0.5 ms median, 3 ms at the 95th percentile, 76 ms
maximum (`src/api/api.ts`, 121 KB) |

Each step of `pnpm lint`, median wall time of 5 runs:

| Step | Wall time |
|---|---|
| `lint:check` (Biome) | 0.96 s |
| `lint:oxlint` | 0.32 s |
| `lint:types` (`tsc`) | 5.8 s with its incremental cache, 45 s without
|
| `lint:circular-deps` | 5.7 s |
| `lint:compiler` | 15.6 s |
| `lint:sentence-case` | 1.6 s |
| `knip` | 6.6 s |
| All of `pnpm lint` | 37 s with the `tsc` cache, 76 s without |

<details>
<summary>Where the time goes, scaling, and limits</summary>

Phases of one run, from in-process timers. The split between parsing and
checking is approximate.

| Phase | Time | Share |
|---|---|---|
| Node startup | 0.03 s | 2% |
| Load the `typescript` module | 0.32 s | 20% |
| Find and read the files | 0.04 s | 2% |
| Parse (`ts.createSourceFile`) | 0.83 s | 52% |
| Check logic | 0.38 s | 24% |

Scaling, from synthetic inputs passed to `checkSource` (median of 3 to 5
warm runs):

- Clean input is linear in size: 0.2 ms to 0.35 ms per KB for one file
from 54 KB to 7 MB. 100,000 string literals take 0.3 s, 100,000 sibling
JSX elements take 0.8 s, and JSX nested 800 levels deep takes 10 ms.
- Conditional JSX stays bounded by the 64-variant cap: 1 to 48
conditional children in one element take at most 3.4 ms.
- Reporting and fixing add no measurable time. On the merge base with
`main` (378 reports in 175 files), a check, `--fix`, and a second
`--fix` each take 1.6 s to 1.7 s.
- The 21 unit tests run in about 30 ms, 1.7 s including Vitest startup.

Two limits, neither reachable with the current source:

- Time is quadratic in the reports for one file, because the fixed text
is rebuilt once per report. A 3.5 MB file takes 0.7 s clean and 18.0 s
with 12,800 reports. The most reports in one file on the merge base is
16.
- One JSX element with more than about 120,000 text phrases fails with
`RangeError: Maximum call stack size exceeded`, because the phrases are
spread into `push`.

</details>

---------

Co-authored-by: Jake Howell <jake@hwll.me>
2026-11-18 13:36:16 +07:00

20 KiB

title
title
IdP sync

Note

IdP sync is a Premium feature. Learn more.

IdP (Identity provider) sync allows you to use OpenID Connect (OIDC) to synchronize Coder groups, roles, and organizations based on claims from your IdP.

Prerequisites

Confirm that OIDC provider sends claims

To confirm that your OIDC provider is sending claims, log in with OIDC and visit the following URL with an Owner account:

https://[coder.example.com]/api/v2/debug/[your-username]/debug-link

You should see a field in either id_token_claims, user_info_claims or both followed by a list of the user's OIDC groups in the response.

This is the claim sent by the OIDC provider.

Depending on the OIDC provider, this claim might be called something else. Common names include groups, memberOf, and roles.

See the troubleshooting section for help troubleshooting common issues.

Group Sync

If your OpenID Connect provider supports group claims, you can configure Coder to synchronize groups in your auth provider to groups within Coder. To enable group sync, make sure that the groups claim is being sent by your OpenID provider. You might need to request an additional scope or additional configuration on the OpenID provider side.

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 user login.

For deployments with multiple organizations, configure group sync for each organization.

Dashboard

  1. Fetch the corresponding group IDs using the following endpoint:

    https://[coder.example.com]/api/v2/groups
    
  2. As an Owner or Organization Admin, go to Admin settings, select Organizations, then IdP sync:

    IdP sync - Group sync

  3. Enter the Group sync field and an optional Regex filter, then select Save.

  4. Select Auto create missing groups to automatically create groups returned by the OIDC provider if they do not exist in Coder.

  5. Enter the IdP group name and Coder group, then Add IdP group.

CLI

  1. Confirm you have the Coder CLI installed and are logged in as an Owner or Organization Admin.

  2. To fetch the current group sync settings for an organization, run the following:

    coder organizations settings show group-sync \
      --org <org-name> \
      > group-sync.json
    

    The default for an organization looks like this:

    {
        "field": "",
        "mapping": null,
        "regex_filter": null,
        "auto_create_missing_groups": false
    }
    

Below is an example that uses the groups claim and maps all groups prefixed by coder- into Coder:

{
    "field": "groups",
    "mapping": null,
    "regex_filter": "^coder-.*$",
    "auto_create_missing_groups": true
}

You must specify Coder group IDs instead of group names. You can find the ID for a corresponding group by visiting https://coder.example.com/api/v2/groups.

Here is another example which maps coder-admins from the identity provider to two groups in Coder and coder-users from the identity provider to another group:

{
    "field": "groups",
    "mapping": {
        "coder-admins": [
            "2ba2a4ff-ddfb-4493-b7cd-1aec2fa4c830",
            "93371154-150f-4b12-b5f0-261bb1326bb4"
        ],
        "coder-users": ["2f4bde93-0179-4815-ba50-b757fb3d43dd"]
    },
    "regex_filter": null,
    "auto_create_missing_groups": false
}

To set these group sync settings, use the following command:

coder organizations settings set group-sync \
  --org <org-name> \
  < group-sync.json

Visit the Coder UI to confirm these changes:

IdP sync

Server Flags

Note

Use server flags only with Coder deployments with a single organization. You can use the dashboard to configure group sync instead.

  1. Configure the control plane to read groups from the claim name with the OIDC group field server flag:

    • Environment variable:

      CODER_OIDC_GROUP_FIELD=groups
      
    • As a flag:

      --oidc-group-field groups
      
  2. On login, Coder adds users to groups with matching names and removes them from groups they no longer belong to.

  3. Configure the mapping between OIDC and Coder groups.

    If an OIDC provider only returns group IDs or you want to have different group names in Coder than in your OIDC provider, map between the two with the OIDC group mapping server flag:

    • Environment variable:

      CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
      
    • As a flag:

      --oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
      

    Below is an example mapping in the Coder Helm chart:

    coder:
      env:
        - name: CODER_OIDC_GROUP_MAPPING
          value: >
            {"myOIDCGroupID": "myCoderGroupName"}
    

    From this example, users that belong to the myOIDCGroupID group in your OIDC provider will be added to the myCoderGroupName group in Coder.

Group allowlist

You can limit which groups from your identity provider can log in to Coder with CODER_OIDC_ALLOWED_GROUPS. Users who are not in a matching group will see the following error:

Unauthorized group error

Role Sync

If your OpenID Connect provider supports roles claims, you can configure Coder to synchronize roles in your auth provider to roles within Coder.

For deployments with multiple organizations, configure role sync at the organization level.

Dashboard

  1. As an Owner or Organization Admin, go to Admin settings, select Organizations, then IdP sync.

  2. Select the Role sync settings tab:

    IdP sync - Role sync settings

  3. Enter the Role sync field, then select Save.

  4. Enter the IdP role name and Coder role, then Add IdP role.

    To add a new custom role, select Roles from the sidebar, then Create custom role.

    Visit the groups and roles documentation for more information.

CLI

  1. Confirm you have the Coder CLI installed and are logged in as an Owner or Organization Admin.

  2. To fetch the current role sync settings for an organization, run the following:

    coder organizations settings show role-sync \
      --org <org-name> \
      > role-sync.json
    

    The default for an organization looks like this:

    {
        "field": "",
        "mapping": null
    }
    

Below is an example that uses the roles claim and maps coder-admins from the IdP as an Organization Admin and also maps to a custom provisioner-admin role:

{
    "field": "roles",
    "mapping": {
        "coder-admins": ["organization-admin"],
        "infra-admins": ["provisioner-admin"]
    }
}

Note

Be sure to use the name field for each role, not the display name. Use coder organization roles show --org=<your-org> to see roles for your organization.

To set these role sync settings, use the following command:

coder organizations settings set role-sync \
  --org <org-name> \
  < role-sync.json

Visit the Coder UI to confirm these changes:

IdP sync

Server Flags

Note

Use server flags only with Coder deployments with a single organization. You can use the dashboard to configure role sync instead.

  1. Configure the control plane to read groups from the claim name with the OIDC role field server flag:

  2. Set the following in your control plane configuration.

     # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
    CODER_OIDC_SCOPES=openid,profile,email,offline_access,roles
    
    # The following fields are required for role sync:
    CODER_OIDC_USER_ROLE_FIELD=roles
    CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
    

One role from your identity provider can be mapped to many roles in Coder. The example above maps to two roles in Coder.

Organization Sync

If your OpenID Connect provider supports groups/role claims, you can configure Coder to synchronize claims in your auth provider to organizations within Coder.

Viewing and editing the organization settings requires deployment admin permissions (UserAdmin or Owner).

Organization sync works across all organizations. On user login, the sync will add and remove the user from organizations based on their IdP claims. After the sync, the user's state should match that of the IdP.

You can initiate an organization sync through the Coder dashboard or CLI:

Dashboard

  1. Fetch the corresponding organization IDs using the following endpoint:

    https://[coder.example.com]/api/v2/organizations
    
  2. As an Owner or site-wide User Admin, go to Admin settings > Deployment and select IdP organization sync.

  3. In the Organization sync field text box, enter the organization claim, then select Save.

    Users are automatically added to the default organization.

    Do not disable Assign default organization. If you disable the default organization, the system will remove users who are already assigned to it.

  4. Enter an IdP organization name and Coder organization(s), then select Add IdP organization:

    IdP organization sync

CLI

Use the Coder CLI to show and adjust the settings.

These deployment-wide settings are stored in the database. After you change the settings, a user's memberships will update when they log out and log back in.

  1. Show the current settings:

    coder organization settings show org-sync
    {
       "field": "organizations",
       "mapping": {
          "product": ["868e9b76-dc6e-46ab-be74-a891e9bd784b", "cbdcf774-9412-4118-8cd9-b3f502c84dfb"]
       },
       "organization_assign_default": true
    }
    
  2. Update with the JSON payload. In this example, settings.json contains the payload:

    coder organization settings set org-sync < settings.json
    {
       "field": "organizations",
       "mapping": {
          "product": [
             "868e5b23-dc6e-46ab-be74-a891e9bd784b",
             "cbdcf774-4123-4118-8cd9-b3f502c84dfb"
          ],
          "sales": [
             "d79144d9-b30a-555a-9af8-7dac83b2q4ec"
          ]
       },
       "organization_assign_default": true
    }
    

    Analyzing the JSON payload:

    Field Explanation
    field If this field is the empty string "", then org-sync is disabled.
    Org memberships must be manually configured through the UI or API.
    mapping Mapping takes a claim from the IdP, and associates it with 1 or more organizations by universally unique identifier (UUID).
    No validation is done, so you can put UUID's of orgs that do not exist (a noop). The UI picker will allow selecting orgs from a drop down, and convert it to a UUID for you.
    organization_assign_default This setting exists for maintaining backwards compatibility with single org deployments, either through their upgrade, or in perpetuity.
    If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims.

Troubleshooting group/role/organization sync

Some common issues when enabling group, role, or organization sync.

General guidelines

If you are running into issues with a sync:

  1. View your coderd logs and enable verbose mode.

  2. To reduce noise, you can filter for only logs related to group/role sync:

    CODER_LOG_FILTER=".*userauth.*|.*idp-sync.*"
    
  3. Restart the control plane after changing these configuration values.

  4. Attempt to log in, preferably with a user who has the Owner role.

The following debug and warning messages show how Coder processed the OIDC claims and group sync for a login.

  • got oidc claims (debug): Logged when Coder reads claims from a source. The source field is id_token or userinfo, and claim_fields lists the claim names that were present.
  • failed to parse claims for groups (debug): Logged when Coder cannot parse the group claims.
  • user not assigned to expected number of groups and user not removed from expected number of groups (debug): Logged when the number of group changes differs from the expected number.
  • group sync settings name groups that were not synced (warning): Logged when group sync settings refer to groups that Coder did not sync. The CODER_LOG_FILTER setting applies only to debug messages, so this warning appears even when the filter is set.

To view your own claims, run coder users oidc-claims with the Coder CLI. To view the full claims for another user, an Owner can visit this endpoint on their Coder deployment after logging in:

https://[coder.example.com]/api/v2/debug/[username]/debug-link

User not being assigned / Group does not exist

If you want Coder to create groups that do not exist, you can set the following environment variable.

If you enable this, your OIDC provider might be sending over many unnecessary groups. Use filtering options on the OIDC provider to limit the groups sent over to prevent creating excess groups.

# as an environment variable
CODER_OIDC_GROUP_AUTO_CREATE=true
# as a flag
--oidc-group-auto-create=true

A basic regex filtering option on the Coder side is available. This is applied after the group mapping (CODER_OIDC_GROUP_MAPPING), meaning if the group is remapped, the remapped value is tested in the regex. This is useful if you want to filter out groups that do not match a certain pattern. For example, if you want to only allow groups that start with my-group- to be created, you can set the following environment variable.

# as an environment variable
CODER_OIDC_GROUP_REGEX_FILTER="^my-group-.*$"
# as a flag
--oidc-group-regex-filter="^my-group-.*$"

Invalid Scope

If you see an error like the following, you might have an invalid scope.

The application '<oidc_application>' asked for scope 'groups' that doesn't exist on the resource...

This can happen because the identity provider has a different name for the scope. For example, Azure Active Directory (AD) uses GroupMember.Read.All instead of groups. You can find the correct scope name in the IdP's documentation. Some IdPs allow configuring the name of this scope.

The solution is to update the value of CODER_OIDC_SCOPES to the correct value for the identity provider.

No group claim in the got oidc claims log

Steps to troubleshoot.

  1. Make sure the user is a part of a group in the IdP.

    If the user has 0 groups, no groups claim will be sent.

  2. Check if another claim appears to be the correct claim with a different name.

    A common name is memberOf instead of groups. If this is present, update CODER_OIDC_GROUP_FIELD=memberOf.

  3. Make sure the number of groups being sent is under the limit of the IdP.

    Some IdPs will return an error, while others will just omit the groups claim. A common solution is to create a filter on the identity provider that returns less than the limit for your IdP.

Provider-Specific Guides

Active Directory Federation Services (ADFS)

Note

Tested on Active Directory Federation Services (ADFS) 4.0, Windows Server 2019

  1. In your Federation Server, create a new application group for Coder.

    Follow the steps as described in the [Windows Server documentation] (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: Set the Client ID as the relying party identifier.
    • Application Permissions: Allow access to the claims openid, email, profile, and allatclaims.
  2. Visit your ADFS server's /.well-known/openid-configuration URL and note the value for issuer.

    This will look something like https://adfs.corp/adfs/.well-known/openid-configuration.

  3. In Coder's configuration file (or Helm values as appropriate), set the following environment variables or their corresponding CLI arguments:

  4. Configure Issuance Transform Rules on your Federation Server to send the following claims:

    • preferred_username: You can use, for example, "Display Name" as required.

    • email: You can use, for example, the Lightweight Directory Access Protocol (LDAP) attribute "E-Mail-Addresses" as required.

    • email_verified: Create a custom claim rule:

      => issue(Type = "email_verified", Value = "true")
      
    • (Optional) If using Group Sync, send the required groups in the configured groups claim field. Use this answer from Stack Overflow for an example.

Next Steps