-## CLI
+### CLI
Use the Coder CLI to show and adjust the settings.
@@ -359,15 +359,15 @@ settings, a user's memberships will update when they log out and log back in.
}
```
-Analyzing the JSON payload:
+ 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. |
+ | 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. |
-## Dashboard
+### Dashboard
1. Confirm that your OIDC provider is sending claims. Log in with OIDC and visit
the following URL with an `Owner` account:
From aefca02d8772afdd43b4490497e6943d84285eac Mon Sep 17 00:00:00 2001
From: EdwardAngert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Wed, 27 Nov 2024 18:16:17 +0000
Subject: [PATCH 5/7] md and steps cleanup
---
docs/admin/users/idp-sync.md | 312 ++++++++++++++++++++---------------
1 file changed, 176 insertions(+), 136 deletions(-)
diff --git a/docs/admin/users/idp-sync.md b/docs/admin/users/idp-sync.md
index ae4be162c2ec5..9ad90fc11fdc2 100644
--- a/docs/admin/users/idp-sync.md
+++ b/docs/admin/users/idp-sync.md
@@ -17,35 +17,40 @@ There are two ways you can configure group sync:
## Server Flags
-First, confirm that your OIDC provider is sending claims by logging in with OIDC
-and visiting the following URL with an `Owner` account:
+1. Confirm that your OIDC provider is sending claims.
-```text
-https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
-```
+ Log in with OIDC and visit the following URL with an `Owner` account:
-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.
+ ```text
+ https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
+ ```
-> Depending on the OIDC provider, this claim may be named differently. Common
-> ones include `groups`, `memberOf`, and `roles`.
+ 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.
-Next 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:
+ See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug
+ this.
-```sh
-# as an environment variable
-CODER_OIDC_GROUP_FIELD=groups
-```
+ Depending on the OIDC provider, this claim may be called something else.
+ Common names include `groups`, `memberOf`, and `roles`.
-```sh
-# as a flag
---oidc-group-field groups
-```
+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.
@@ -54,17 +59,19 @@ For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
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.
+flag:
-```sh
-# as an environment variable
-CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
-```
+- Environment variable:
-```sh
-# as a flag
---oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
-```
+ ```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:
@@ -84,49 +91,58 @@ OIDC provider will be added to the `myCoderGroupName` group in Coder.
## Runtime (Organizations)
-> Note: You must have a Premium license with Organizations enabled to use this.
-> [Contact your account team](https://coder.com/contact) for more details
+
+
+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.
-First 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. Next, confirm
-that your OIDC provider is sending a groups claim by logging in with OIDC and
-visiting the following URL:
+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.
-```text
-https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
-```
+1. Confirm that your OIDC provider is sending a groups claim.
-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.
+ Log in with OIDC and visit the following URL:
-> Depending on the OIDC provider, this claim may be named differently. Common
-> ones include `groups`, `memberOf`, and `roles`.
+ ```text
+ https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
+ ```
-To fetch the current group sync settings for an organization, run the following:
+ 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.
-```sh
-coder organizations settings show group-sync \
- --org
\
- > group-sync.json
-```
+ See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug
+ this.
-The default for an organization looks like this:
+ Depending on the OIDC provider, this claim may be called something else.
+ Common names include `groups`, `memberOf`, and `roles`.
-```json
-{
- "field": "",
- "mapping": null,
- "regex_filter": null,
- "auto_create_missing_groups": false
-}
-```
+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:
@@ -140,12 +156,17 @@ Below is an example that uses the `groups` claim and maps all groups prefixed by
}
```
-> Note: 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`.
+
+
+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
-2 groups in Coder and `coder-users` from the identity provider to another group:
+two groups in Coder and `coder-users` from the identity provider to another
+group:
```json
{
@@ -182,7 +203,7 @@ You can limit which groups from your identity provider can log in to Coder with
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
Users who are not in a matching group will see the following error:
-
+
## Role sync (enterprise) (premium)
@@ -192,87 +213,97 @@ to synchronize roles in your auth provider to roles within Coder.
There are 2 ways to do role sync. Server Flags assign site wide roles, and
runtime org role sync assigns organization roles
+
+
+You must have a Premium license with Organizations enabled to use this.
+[Contact your account team](https://coder.com/contact) for more details.
+
+
+
## Server Flags
-First, confirm that your OIDC provider is sending a roles claim by logging in
-with OIDC and visiting the following URL with an `Owner` account:
+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
-```
+ ```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.
+ 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.
-> Depending on the OIDC provider, this claim may be named differently.
+ See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug
+ this.
-Next 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:
+ Depending on the OIDC provider, this claim may be called something else.
-Set the following in your Coder server [configuration](../setup/index.md).
+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:
-```env
- # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
-CODER_OIDC_SCOPES=openid,profile,email,roles
+1. Set the following in your Coder server [configuration](../setup/index.md).
-# The following fields are required for role sync:
-CODER_OIDC_USER_ROLE_FIELD=roles
-CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
-```
+ ```env
+ # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
+ CODER_OIDC_SCOPES=openid,profile,email,roles
-> One role from your identity provider can be mapped to many roles in Coder
-> (e.g. the example above maps to 2 roles in Coder.)
+ # The following fields are required for role sync:
+ CODER_OIDC_USER_ROLE_FIELD=roles
+ CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
+ ```
-## Runtime (Organizations)
+One role from your identity provider can be mapped to many roles in Coder. The
+example above maps to two roles in Coder.
-> Note: You must have a Premium license with Organizations enabled to use this.
-> [Contact your account team](https://coder.com/contact) for more details
+## 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.
-First, confirm that your OIDC provider is sending a roles claim by logging in
-with OIDC and visiting the following URL with an `Owner` account:
+1. Confirm that your OIDC provider is sending a roles claim.
-```text
-https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
-```
+ 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.
+ 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.
-> Depending on the OIDC provider, this claim may be named differently.
+ See [Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug
+ this.
-To fetch the current group sync settings for an organization, run the following:
+ Depending on the OIDC provider, this claim may be called something else.
-```sh
-coder organizations settings show role-sync \
- --org
\
- > role-sync.json
-```
+1. To fetch the current group sync settings for an organization, run the
+ following:
-The default for an organization looks like this:
+ ```sh
+ coder organizations settings show role-sync \
+ --org \
+ > role-sync.json
+ ```
-```json
-{
- "field": "",
- "mapping": null
-}
-```
+ 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.
+role:
```json
{
@@ -284,9 +315,13 @@ role.
}
```
-> Note: 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.
+
+
+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:
@@ -424,18 +459,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).
-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. To reduce noise, you can filter for only logs related to group/role sync:
+
+ ```sh
+ CODER_VERBOSE=true
+ CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"
+ ```
+
+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):
@@ -459,9 +497,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
From b336e3bc95422f44ce4aaed69a1b07d6c8305de0 Mon Sep 17 00:00:00 2001
From: Edward Angert
Date: Tue, 10 Dec 2024 10:41:35 -0500
Subject: [PATCH 6/7] docs: add new steps for org sync through ui (#15768)
[preview](https://coder.com/docs/@15503-ui-org-sync/admin/users/idp-sync#organization-sync-premium)
---------
Co-authored-by: EdwardAngert <2408959-EdwardAngert@users.noreply.gitlab.com>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
---
docs/admin/users/idp-sync.md | 31 +++++++-----------
.../users/organizations/idp-org-sync.png | Bin 0 -> 81509 bytes
2 files changed, 11 insertions(+), 20 deletions(-)
create mode 100644 docs/images/admin/users/organizations/idp-org-sync.png
diff --git a/docs/admin/users/idp-sync.md b/docs/admin/users/idp-sync.md
index 9ad90fc11fdc2..c089f93e4206e 100644
--- a/docs/admin/users/idp-sync.md
+++ b/docs/admin/users/idp-sync.md
@@ -420,36 +420,27 @@ settings, a user's memberships will update when they log out and log back in.
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
- organization field server flag:
-
- ```sh
- # as an environment variable
- CODER_OIDC_ORGANIZATION_FIELD=groups
- ```
-
1. Fetch the corresponding organization IDs using the following endpoint:
```text
https://[coder.example.com]/api/v2/organizations
```
-1. Set the following in your Coder server [configuration](../setup/index.md).
+1. As a Coder organization user admin or site-wide user admin, go to
+ **Settings** > **IdP organization sync**.
- ```env
- CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
- ```
+1. In the **Organization sync field** text box, enter the organization claim,
+ then select **Save**.
- > One claim value from your identity provider can be mapped to many
- > organizations in Coder. The example above maps to two organizations in
- > Coder.
+ Users are automatically added to the default organization.
-1. By default, all users are assigned to the default (first) organization. You
- can disable that with:
+ Do not disable **Assign Default Organization**. If you disable the default
+ organization, the system will remove users who are already assigned to it.
- ```env
- CODER_OIDC_ORGANIZATION_ASSIGN_DEFAULT=false
- ```
+1. Enter an IdP organization name and Coder organization(s), then select **Add
+ IdP organization**:
+
+ 