` to see roles for your
-> organization.
+
+
+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:
@@ -304,58 +339,110 @@ Visit the Coder UI to confirm these changes:
## Organization Sync (Premium)
-> Note: In a future Coder release, this can be managed via the Coder UI instead
-> of server flags.
-
If your OpenID Connect provider supports groups/role claims, you can configure
Coder to synchronize claims in your auth provider to organizations within Coder.
-First, confirm that your OIDC provider is sending clainms by logging in with
-OIDC and visiting the following URL with an `Owner` account:
+Viewing and editing the organization settings requires deployment admin
+permissions (UserAdmin or Owner).
-```text
-https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
-```
+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 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.
+You can initiate an organization sync through the CLI or through the Coder
+dashboard:
-> Depending on the OIDC provider, this claim may be named differently. Common
-> ones include `groups`, `memberOf`, and `roles`.
+
-Next configure the Coder server to read groups from the claim name with the OIDC
-organization field server flag:
+### Dashboard
-```sh
-# as an environment variable
-CODER_OIDC_ORGANIZATION_FIELD=groups
-```
+1. Confirm that your OIDC provider is sending claims. Log in with OIDC and visit
+ the following URL with an `Owner` account:
-Next, fetch the corresponding organization IDs using the following endpoint:
+ ```text
+ https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
+ ```
-```text
-https://[coder.example.com]/api/v2/organizations
-```
+ 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.
-Set the following in your Coder server [configuration](../setup/index.md).
+ Depending on the OIDC provider, this claim may be called something else.
+ Common names include `groups`, `memberOf`, and `roles`.
-```env
-CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
-```
+1. Fetch the corresponding organization IDs using the following endpoint:
-> One claim value from your identity provider can be mapped to many
-> organizations in Coder (e.g. the example above maps to 2 organizations in
-> Coder.)
+ ```text
+ https://[coder.example.com]/api/v2/organizations
+ ```
-By default, all users are assigned to the default (first) organization. You can
-disable that with:
+1. As a Coder organization user admin or site-wide user admin, go to
+ **Settings** > **IdP organization sync**.
-```env
-CODER_OIDC_ORGANIZATION_ASSIGN_DEFAULT=false
-```
+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. |
+
+
## Troubleshooting group/role/organization sync
@@ -363,18 +450,21 @@ Some common issues when enabling group/role sync.
### General guidelines
-If you are running into issues with group/role sync, is best to view your Coder
-server logs and enable
-[verbose mode](../../reference/cli/index.md#-v---verbose). To reduce noise, you
-can filter for only logs related to group/role sync:
+If you are running into issues with group/role sync:
-```sh
-CODER_VERBOSE=true
-CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"
-```
+1. View your Coder server logs and enable
+ [verbose mode](../../reference/cli/index.md#-v---verbose).
+
+1. To reduce noise, you can filter for only logs related to group/role sync:
+
+ ```sh
+ CODER_VERBOSE=true
+ CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"
+ ```
-Be sure to restart the server after changing these configuration values. Then,
-attempt to log in, preferably with a user who has the `Owner` role.
+1. Restart the server after changing these configuration values.
+
+1. Attempt to log in, preferably with a user who has the `Owner` role.
The logs for a successful group sync look like this (human-readable):
@@ -398,9 +488,11 @@ 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.
+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.
```env
# as an environment variable
diff --git a/docs/images/admin/users/organizations/idp-org-sync.png b/docs/images/admin/users/organizations/idp-org-sync.png
new file mode 100644
index 0000000000000..0b4a61f66c78f
Binary files /dev/null and b/docs/images/admin/users/organizations/idp-org-sync.png differ