## Server Flags 1. Confirm that your OIDC provider is sending claims. Log in with OIDC and visit the following URL with an `Owner` account: ```text 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](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by the OIDC provider. See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this. Depending on the OIDC provider, this claim may be called something else. Common names include `groups`, `memberOf`, and `roles`. 1. Configure the Coder server to read groups from the claim name with the [OIDC group field](../../reference/cli/server.md#--oidc-group-field) server flag: - Environment variable: ```sh CODER_OIDC_GROUP_FIELD=groups ``` - As a flag: ```sh --oidc-group-field groups ``` On login, users will automatically be assigned to groups that have matching names in Coder and removed from groups that the user no longer belongs to. For cases when an OIDC provider only returns group IDs or you want to have different group names in Coder than in your OIDC provider, you can configure mapping between the two with the [OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server flag: - Environment variable: ```sh CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}' ``` - As a flag: ```sh --oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}' ``` Below is an example mapping in the Coder Helm chart: ```yaml coder: env: - name: CODER_OIDC_GROUP_MAPPING value: > {"myOIDCGroupID": "myCoderGroupName"} ``` From the example above, users that belong to the `myOIDCGroupID` group in your OIDC provider will be added to the `myCoderGroupName` group in Coder. ## Runtime (Organizations)

You must have a Premium license with Organizations enabled to use this. [Contact your account team](https://coder.com/contact) for more details.

For deployments with multiple [organizations](./organizations.md), you must configure group sync at the organization level. In future Coder versions, you will be able to configure this in the UI. For now, you must use CLI commands. 1. Confirm you have the [Coder CLI](../../install/index.md) installed and are logged in with a user who is an Owner or Organization Admin role. 1. Confirm that your OIDC provider is sending a groups claim. Log in with OIDC and visit the following URL: ```text 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](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by the OIDC provider. See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this. Depending on the OIDC provider, this claim may be called something else. Common names include `groups`, `memberOf`, and `roles`. 1. To fetch the current group sync settings for an organization, run the following: ```sh coder organizations settings show group-sync \ --org \ > group-sync.json ``` The default for an organization looks like this: ```json { "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: ```json { "field": "groups", "mapping": null, "regex_filter": "^coder-.*$", "auto_create_missing_groups": true } ```

You much specify Coder group IDs instead of group names. The fastest way to find the ID for a corresponding group is 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: ```json { "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: ```sh coder organizations settings set group-sync \ --org \ < group-sync.json ``` Visit the Coder UI to confirm these changes: 

## Server Flags 1. Confirm that your OIDC provider is sending a roles claim by logging in with OIDC and visiting the following URL with an `Owner` account: ```text 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 roles in the response. This is the [claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by the OIDC provider. See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this. Depending on the OIDC provider, this claim may be called something else. 1. Configure the Coder server to read groups from the claim name with the [OIDC role field](../../reference/cli/server.md#--oidc-user-role-field) server flag: 1. Set the following in your Coder server [configuration](../setup/index.md). ```env # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope CODER_OIDC_SCOPES=openid,profile,email,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. ## Runtime (Organizations) For deployments with multiple [organizations](./organizations.md), you can configure role sync at the organization level. In future Coder versions, you will be able to configure this in the UI. For now, you must use CLI commands. 1. Confirm that your OIDC provider is sending a roles claim. Log in with OIDC and visit the following URL with an `Owner` account: ```text 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 roles in the response. This is the [claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by the OIDC provider. See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this. Depending on the OIDC provider, this claim may be called something else. 1. To fetch the current group sync settings for an organization, run the following: ```sh coder organizations settings show role-sync \ --org \ > role-sync.json ``` The default for an organization looks like this: ```json { "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: ```json { "field": "roles", "mapping": { "coder-admins": ["organization-admin"], "infra-admins": ["provisioner-admin"] } } ```

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

To set these role sync settings, use the following command: ```sh coder organizations settings set role-sync \ --org \ < role-sync.json ``` Visit the Coder UI to confirm these changes: 

## Dashboard 1. Confirm that your OIDC provider is sending claims. Log in with OIDC and visit the following URL with an `Owner` account: ```text 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](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by the OIDC provider. See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this. Depending on the OIDC provider, this claim may be called something else. Common names include `groups`, `memberOf`, and `roles`. 1. Fetch the corresponding organization IDs using the following endpoint: ```text https://[coder.example.com]/api/v2/organizations ``` 1. As a Coder organization user admin or site-wide user admin, go to **Settings** > **IdP organization sync**. 1. 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. 1. Enter an IdP organization name and Coder organization(s), then select **Add IdP organization**:  ## 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: ```console coder organization settings show org-sync { "field": "organizations", "mapping": { "product": ["868e9b76-dc6e-46ab-be74-a891e9bd784b", "cbdcf774-9412-4118-8cd9-b3f502c84dfb"] }, "organization_assign_default": true } ``` 1. Update with the JSON payload. In this example, `settings.json` contains the payload: ```console 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 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. |