Skip to content

Commit 050b9ea

Browse files
EdwardAngertEdwardAngert
committed
update dashboard steps and screenshots
1 parent 7900135 commit 050b9ea

File tree

5 files changed

+131
-87
lines changed

5 files changed

+131
-87
lines changed

‎docs/admin/users/idp-sync.md

Lines changed: 131 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,12 @@ IdP sync is an Enterprise and Premium feature.
88

99
</blockquote>
1010

11-
## Confirm that OIDC provider sends claims
11+
IdP (Identity provider) sync allows you to use OpenID Connect (OIDC) to
12+
synchronize Coder groups, roles, and organizations based on claims from your IdP.
13+
14+
## Prerequisites
15+
16+
### Confirm that OIDC provider sends claims
1217

1318
To confirm that your OIDC provider is sending claims, log in with OIDC and visit
1419
the following URL with an `Owner` account:
@@ -23,7 +28,7 @@ both followed by a list of the user's OIDC groups in the response.
2328
This is the [claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims)
2429
sent by the OIDC provider.
2530

26-
Depending on the OIDC provider, this claim may be called something else.
31+
Depending on the OIDC provider, this claim might be called something else.
2732
Common names include `groups`, `memberOf`, and `roles`.
2833

2934
See the [troubleshooting section](#troubleshooting-grouproleorganization-sync)
@@ -42,77 +47,36 @@ If group sync is enabled, the user's groups will be controlled by the OIDC
4247
provider. This means manual group additions/removals will be overwritten on the
4348
next user login.
4449

45-
There are two ways you can configure group sync:
50+
For deployments with multiple [organizations](./organizations.md), configure
51+
group sync at the organization level.
4652

4753
<div class="tabs">
4854

49-
### Server Flags
50-
51-
<blockquote class="admonition note">
52-
53-
This method is deprecated.
54-
55-
You can use the dashboard to configure group sync instead.
56-
57-
</blockquote>
58-
59-
1. Configure the Coder server to read groups from the claim name with the
60-
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
61-
flag:
62-
63-
- Environment variable:
64-
65-
```sh
66-
CODER_OIDC_GROUP_FIELD=groups
67-
```
68-
69-
- As a flag:
70-
71-
```sh
72-
--oidc-group-field groups
73-
```
74-
75-
On login, users will automatically be assigned to groups that have matching
76-
names in Coder and removed from groups that the user no longer belongs to.
77-
78-
For cases when an OIDC provider only returns group IDs or you want to have
79-
different group names in Coder than in your OIDC provider, you can configure
80-
mapping between the two with the
81-
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
82-
flag:
55+
### Dashboard
8356

84-
- Environment variable:
57+
1. Fetch the corresponding group IDs using the following endpoint:
8558

86-
```sh
87-
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
88-
```
59+
```text
60+
https://[coder.example.com]/api/v2/groups
61+
```
8962

90-
- As a flag:
63+
1. As an Owner or Organization Admin, go to **Admin settings**, select
64+
**Organizations**, then **IdP Sync**:
9165

92-
```sh
93-
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
94-
```
66+
![IdP Sync - Group sync settings](../../images/admin/users/organizations/group-sync-empty.png)
9567

96-
Below is an example mapping in the Coder Helm chart:
68+
1. Enter the **Group sync field** and an optional **Regex filter**, then select
69+
**Save**.
9770

98-
```yaml
99-
coder:
100-
env:
101-
- name: CODER_OIDC_GROUP_MAPPING
102-
value: >
103-
{"myOIDCGroupID": "myCoderGroupName"}
104-
```
71+
1. Select **Auto create missing groups** to automatically create groups
72+
returned by the OIDC provider if they do not exist in Coder.
10573

106-
From the example above, users that belong to the `myOIDCGroupID` group in your
107-
OIDC provider will be added to the `myCoderGroupName` group in Coder.
74+
1. Enter the **IdP group name** and **Coder group**, then **Add IdP group**.
10875

109-
### Runtime (Organizations)
110-
111-
For deployments with multiple [organizations](./organizations.md), you must
112-
configure group sync at the organization level.
76+
### CLI
11377

11478
1. Confirm you have the [Coder CLI](../../install/index.md) installed and are
115-
logged in with a user who is an Owner or Organization Admin role.
79+
logged in with a user who is an Owner or has an Organization Admin role.
11680

11781
1. To fetch the current group sync settings for an organization, run the
11882
following:
@@ -148,7 +112,7 @@ Below is an example that uses the `groups` claim and maps all groups prefixed by
148112

149113
<blockquote class="admonition note">
150114

151-
You much specify Coder group IDs instead of group names. The fastest way to find
115+
You must specify Coder group IDs instead of group names. The fastest way to find
152116
the ID for a corresponding group is by visiting
153117
`https://coder.example.com/api/v2/groups`.
154118

@@ -185,6 +149,66 @@ Visit the Coder UI to confirm these changes:
185149

186150
![IdP Sync](../../images/admin/users/organizations/group-sync.png)
187151

152+
### Server Flags
153+
154+
<blockquote class="admonition note">
155+
156+
Use server flags only with Coder deployments with a single organization.
157+
158+
You can use the dashboard to configure group sync instead.
159+
160+
</blockquote>
161+
162+
1. Configure the Coder server to read groups from the claim name with the
163+
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
164+
flag:
165+
166+
- Environment variable:
167+
168+
```sh
169+
CODER_OIDC_GROUP_FIELD=groups
170+
```
171+
172+
- As a flag:
173+
174+
```sh
175+
--oidc-group-field groups
176+
```
177+
178+
1. On login, users will automatically be assigned to groups that have matching
179+
names in Coder and removed from groups that the user no longer belongs to.
180+
181+
1. For cases when an OIDC provider only returns group IDs or you want to have
182+
different group names in Coder than in your OIDC provider, you can configure
183+
mapping between the two with the
184+
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
185+
flag:
186+
187+
- Environment variable:
188+
189+
```sh
190+
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
191+
```
192+
193+
- As a flag:
194+
195+
```sh
196+
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
197+
```
198+
199+
Below is an example mapping in the Coder Helm chart:
200+
201+
```yaml
202+
coder:
203+
env:
204+
- name: CODER_OIDC_GROUP_MAPPING
205+
value: >
206+
{"myOIDCGroupID": "myCoderGroupName"}
207+
```
208+
209+
From this example, users that belong to the `myOIDCGroupID` group in your
210+
OIDC provider will be added to the `myCoderGroupName` group in Coder.
211+
188212
</div>
189213

190214
### Group allowlist
@@ -200,40 +224,33 @@ Users who are not in a matching group will see the following error:
200224
If your OpenID Connect provider supports roles claims, you can configure Coder
201225
to synchronize roles in your auth provider to roles within Coder.
202226

203-
<div class="tabs">
227+
For deployments with multiple [organizations](./organizations.md), configure
228+
role sync at the organization level.
204229

205-
### Server Flags
230+
<div class="tabs">
206231

207-
<blockquote class="admonition note">
232+
### Dashboard
208233

209-
This method is deprecated.
234+
1. As an Owner or Organization Admin, go to **Admin settings**, select
235+
**Organizations**, then **IdP Sync**.
210236

211-
You can use the dashboard to configure role sync instead.
237+
1. Select the **Role sync settings** tab:
212238

213-
</blockquote>
239+
![IdP Sync - Role sync settings](../../images/admin/users/organizations/role-sync-empty.png)
214240

215-
1. Configure the Coder server to read groups from the claim name with the
216-
[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field)
217-
server flag:
241+
1. Enter the **Role sync field**, then select **Save**.
218242

219-
1. Set the following in your Coder server [configuration](../setup/index.md).
243+
1. Enter the **IdP role name** and **Coder role**, then **Add IdP role**.
220244

221-
```env
222-
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
223-
CODER_OIDC_SCOPES=openid,profile,email,roles
245+
To add a new custom role, select **Roles** from the sidebar, then
246+
**Create custom role**.
224247

225-
# The following fields are required for role sync:
226-
CODER_OIDC_USER_ROLE_FIELD=roles
227-
CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
228-
```
248+
Visit the [groups and roles documentation](./groups-roles.md) for more information.
229249

230-
One role from your identity provider can be mapped to many roles in Coder. The
231-
example above maps to two roles in Coder.
232-
233-
### Runtime (Organizations)
250+
### CLI
234251

235-
For deployments with multiple [organizations](./organizations.md), you can
236-
configure role sync at the organization level.
252+
1. Confirm you have the [Coder CLI](../../install/index.md) installed and are
253+
logged in with a user who is an Owner or has an Organization Admin role.
237254

238255
1. To fetch the current group sync settings for an organization, run the
239256
following:
@@ -270,7 +287,7 @@ role:
270287
<blockquote class="admonition note">
271288

272289
Be sure to use the `name` field for each role, not the display name. Use
273-
`coder organization roles show --org=<your-org>` to see roles for your
290+
`coder organization roles show --org=<your-org>` to see roles for your
274291
organization.
275292

276293
</blockquote>
@@ -287,6 +304,34 @@ Visit the Coder UI to confirm these changes:
287304

288305
![IdP Sync](../../images/admin/users/organizations/role-sync.png)
289306

307+
### Server Flags
308+
309+
<blockquote class="admonition note">
310+
311+
Use server flags only with Coder deployments with a single organization.
312+
313+
You can use the dashboard to configure role sync instead.
314+
315+
</blockquote>
316+
317+
1. Configure the Coder server to read groups from the claim name with the
318+
[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field)
319+
server flag:
320+
321+
1. Set the following in your Coder server [configuration](../setup/index.md).
322+
323+
```env
324+
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
325+
CODER_OIDC_SCOPES=openid,profile,email,roles
326+
327+
# The following fields are required for role sync:
328+
CODER_OIDC_USER_ROLE_FIELD=roles
329+
CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
330+
```
331+
332+
One role from your identity provider can be mapped to many roles in Coder. The
333+
example above maps to two roles in Coder.
334+
290335
</div>
291336

292337
## Organization Sync
@@ -301,8 +346,7 @@ Organization sync works across all organizations. On user login, the sync will
301346
add and remove the user from organizations based on their IdP claims. After the
302347
sync, the user's state should match that of the IdP.
303348
304-
You can initiate an organization sync through the CLI or through the Coder
305-
dashboard:
349+
You can initiate an organization sync through the Coder dashboard or CLI:
306350
307351
<div class="tabs">
308352

‎docs/images/admin/users/organizations/group-sync-empty.png

54.1 KB
Loading

‎docs/images/admin/users/organizations/group-sync.png

-18.6 KB
Loading

‎docs/images/admin/users/organizations/role-sync-empty.png

42.1 KB
Loading

‎docs/images/admin/users/organizations/role-sync.png

-21.4 KB
Loading

0 commit comments

Comments
 (0)