### Dashboard 1. Fetch the corresponding group IDs using the following endpoint: ```text https://[coder.example.com]/api/v2/groups ``` 1. As an Owner or Organization Admin, go to **Admin settings**, select **Organizations**, then **IdP Sync**:  1. Enter the **Group sync field** and an optional **Regex filter**, then select **Save**. 1. Select **Auto create missing groups** to automatically create groups returned by the OIDC provider if they do not exist in Coder. 1. Enter the **IdP group name** and **Coder group**, then **Add IdP group**. ### CLI 1. Confirm you have the [Coder CLI](../../install/index.md) installed and are logged in with a user who is an Owner or has an Organization Admin role. 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 must 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

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

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 ``` 1. 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. 1. 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 this example, users that belong to the `myOIDCGroupID` group in your OIDC provider will be added to the `myCoderGroupName` group in Coder.

### Dashboard 1. As an Owner or Organization Admin, go to **Admin settings**, select **Organizations**, then **IdP Sync**. 1. Select the **Role sync settings** tab:  1. Enter the **Role sync field**, then select **Save**. 1. 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](./groups-roles.md) for more information. ### CLI 1. Confirm you have the [Coder CLI](../../install/index.md) installed and are logged in with a user who is an Owner or has an Organization Admin role. 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:  ### Server Flags

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

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.

### Dashboard 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 **Admin settings** > **Deployment** and select **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. |