Skip to content

Commit 710bd75

Browse files
stirbystirby
committed
Merge branch 'restructure-new' of https://github.com/coder/coder into restructure-new
2 parents bf9e16f + 139122a commit 710bd75

File tree

4 files changed

+362
-51
lines changed

4 files changed

+362
-51
lines changed

‎docs/admin/users/group-sync.md renamed to ‎docs/admin/users/idp-sync.md

Lines changed: 292 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,47 @@
1-
# Group Sync (enterprise) (premium)
1+
# IDP Sync (enterprise) (premium)
22

33
If your OpenID Connect provider supports group claims, you can configure Coder
4-
to synchronize groups in your auth provider to groups within Coder.
4+
to synchronize groups in your auth provider to groups within Coder. To enable
5+
group sync, ensure that the `groups` claim is being sent by your OpenID
6+
provider. You might need to request an additional
7+
[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
8+
the OpenID provider side.
59

6-
To enable group sync, ensure that the `groups` claim is set by adding the
7-
correct scope to request. If group sync is enabled, the user's groups will be
8-
controlled by the OIDC provider. This means manual group additions/removals will
9-
be overwritten on the next login.
10+
If group sync is enabled, the user's groups will be controlled by the OIDC
11+
provider. This means manual group additions/removals will be overwritten on the
12+
next user login.
1013

11-
```env
12-
# as an environment variable
13-
CODER_OIDC_SCOPES=openid,profile,email,groups
14-
```
14+
There are two ways you can configure group sync:
1515

16-
```shell
17-
# as a flag
18-
--oidc-scopes openid,profile,email,groups
16+
<div class="tabs">
17+
18+
## Server Flags
19+
20+
First, confirm that your OIDC provider is sending claims by logging in with OIDC
21+
and visiting the following URL with an `Owner` account:
22+
23+
```text
24+
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
1925
```
2026

21-
With the `groups` scope requested, we also need to map the `groups` claim name.
22-
Coder recommends using `groups` for the claim name. This step is necessary if
23-
your **scope's name** is something other than `groups`.
27+
You should see a field in either `id_token_claims`, `user_info_claims` or both
28+
followed by a list of the user's OIDC groups in the response. This is the
29+
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
30+
the OIDC provider. See
31+
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
2432

25-
```env
33+
> Depending on the OIDC provider, this claim may be named differently. Common
34+
> ones include `groups`, `memberOf`, and `roles`.
35+
36+
Next configure the Coder server to read groups from the claim name with the
37+
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server flag:
38+
39+
```sh
2640
# as an environment variable
2741
CODER_OIDC_GROUP_FIELD=groups
2842
```
2943

30-
```shell
44+
```sh
3145
# as a flag
3246
--oidc-group-field groups
3347
```
@@ -37,14 +51,16 @@ names in Coder and removed from groups that the user no longer belongs to.
3751

3852
For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
3953
or you want to have different group names in Coder than in your OIDC provider,
40-
you can configure mapping between the two.
54+
you can configure mapping between the two with the
55+
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
56+
flag.
4157

42-
```env
58+
```sh
4359
# as an environment variable
4460
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
4561
```
4662

47-
```shell
63+
```sh
4864
# as a flag
4965
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
5066
```
@@ -62,24 +78,141 @@ coder:
6278
From the example above, users that belong to the `myOIDCGroupID` group in your
6379
OIDC provider will be added to the `myCoderGroupName` group in Coder.
6480

65-
> **Note:** Groups are only updated on login.
66-
6781
[azure-gids]:
6882
https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
6983

84+
## Runtime (Organizations)
85+
86+
> Note: You must have a Premium license with Organizations enabled to use this.
87+
> [Contact your account team](https://coder.com/contact) for more details
88+
89+
For deployments with multiple [organizations](./organizations.md), you must
90+
configure group sync at the organization level. In future Coder versions, you
91+
will be able to configure this in the UI. For now, you must use CLI commands.
92+
93+
First confirm you have the [Coder CLI](../install/index.md) installed and are
94+
logged in with a user who is an Owner or Organization Admin role. Next, confirm
95+
that your OIDC provider is sending a groups claim by logging in with OIDC and
96+
visiting the following URL:
97+
98+
```text
99+
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
100+
```
101+
102+
You should see a field in either `id_token_claims`, `user_info_claims` or both
103+
followed by a list of the user's OIDC groups in the response. This is the
104+
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
105+
the OIDC provider. See
106+
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
107+
108+
> Depending on the OIDC provider, this claim may be named differently. Common
109+
> ones include `groups`, `memberOf`, and `roles`.
110+
111+
To fetch the current group sync settings for an organization, run the following:
112+
113+
```sh
114+
coder organizations settings show group-sync \
115+
--org <org-name> \
116+
> group-sync.json
117+
```
118+
119+
The default for an organization looks like this:
120+
121+
```json
122+
{
123+
"field": "",
124+
"mapping": null,
125+
"regex_filter": null,
126+
"auto_create_missing_groups": false
127+
}
128+
```
129+
130+
Below is an example that uses the `groups` claim and maps all groups prefixed by
131+
`coder-` into Coder:
132+
133+
```json
134+
{
135+
"field": "groups",
136+
"mapping": null,
137+
"regex_filter": "^coder-.*$",
138+
"auto_create_missing_groups": true
139+
}
140+
```
141+
142+
> Note: You much specify Coder group IDs instead of group names. The fastest way
143+
> to find the ID for a corresponding group is by visiting
144+
> `https://coder.example.com/api/v2/groups`.
145+
146+
Here is another example which maps `coder-admins` from the identity provider to
147+
2 groups in Coder and `coder-users` from the identity provider to another group:
148+
149+
```json
150+
{
151+
"field": "groups",
152+
"mapping": {
153+
"coder-admins": [
154+
"2ba2a4ff-ddfb-4493-b7cd-1aec2fa4c830",
155+
"93371154-150f-4b12-b5f0-261bb1326bb4"
156+
],
157+
"coder-users": ["2f4bde93-0179-4815-ba50-b757fb3d43dd"]
158+
},
159+
"regex_filter": null,
160+
"auto_create_missing_groups": false
161+
}
162+
```
163+
164+
To set these group sync settings, use the following command:
165+
166+
```sh
167+
coder organizations settings set group-sync \
168+
--org <org-name> \
169+
< group-sync.json
170+
```
171+
172+
Visit the Coder UI to confirm these changes:
173+
174+
![IDP Sync](../images/admin/organizations/group-sync.png)
175+
176+
</div>
177+
70178
### Group allowlist
71179

72180
You can limit which groups from your identity provider can log in to Coder with
73-
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/reference/cli/server#--oidc-allowed-groups).
181+
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
74182
Users who are not in a matching group will see the following error:
75183

76-
![Unauthorized group error](../../images/admin/group-allowlist.png)
184+
![Unauthorized group error](../images/admin/group-allowlist.png)
77185

78-
## Role sync
186+
## Role sync (enterprise) (premium)
79187

80188
If your OpenID Connect provider supports roles claims, you can configure Coder
81-
to synchronize roles in your auth provider to deployment-wide roles within
82-
Coder.
189+
to synchronize roles in your auth provider to roles within Coder.
190+
191+
There are 2 ways to do role sync. Server Flags assign site wide roles, and
192+
runtime org role sync assigns organization roles
193+
194+
<div class="tabs">
195+
196+
## Server Flags
197+
198+
First, confirm that your OIDC provider is sending a roles claim by logging in
199+
with OIDC and visiting the following URL with an `Owner` account:
200+
201+
```text
202+
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
203+
```
204+
205+
You should see a field in either `id_token_claims`, `user_info_claims` or both
206+
followed by a list of the user's OIDC roles in the response. This is the
207+
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
208+
the OIDC provider. See
209+
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
210+
211+
> Depending on the OIDC provider, this claim may be named differently.
212+
213+
Next configure the Coder server to read groups from the claim name with the
214+
[OIDC role field](../reference/cli/server.md#--oidc-user-role-field) server
215+
flag:
83216

84217
Set the following in your Coder server [configuration](./configure.md).
85218

@@ -95,15 +228,144 @@ CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}
95228
> One role from your identity provider can be mapped to many roles in Coder
96229
> (e.g. the example above maps to 2 roles in Coder.)
97230

98-
## Troubleshooting group/role sync
231+
## Runtime (Organizations)
232+
233+
> Note: You must have a Premium license with Organizations enabled to use this.
234+
> [Contact your account team](https://coder.com/contact) for more details
235+
236+
For deployments with multiple [organizations](./organizations.md), you can
237+
configure role sync at the organization level. In future Coder versions, you
238+
will be able to configure this in the UI. For now, you must use CLI commands.
239+
240+
First, confirm that your OIDC provider is sending a roles claim by logging in
241+
with OIDC and visiting the following URL with an `Owner` account:
242+
243+
```text
244+
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
245+
```
246+
247+
You should see a field in either `id_token_claims`, `user_info_claims` or both
248+
followed by a list of the user's OIDC roles in the response. This is the
249+
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
250+
the OIDC provider. See
251+
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
252+
253+
> Depending on the OIDC provider, this claim may be named differently.
254+
255+
To fetch the current group sync settings for an organization, run the following:
256+
257+
```sh
258+
coder organizations settings show role-sync \
259+
--org <org-name> \
260+
> role-sync.json
261+
```
262+
263+
The default for an organization looks like this:
264+
265+
```json
266+
{
267+
"field": "",
268+
"mapping": null
269+
}
270+
```
271+
272+
Below is an example that uses the `roles` claim and maps `coder-admins` from the
273+
IDP as an `Organization Admin` and also maps to a custom `provisioner-admin`
274+
role.
275+
276+
```json
277+
{
278+
"field": "roles",
279+
"mapping": {
280+
"coder-admins": ["organization-admin"],
281+
"infra-admins": ["provisioner-admin"]
282+
}
283+
}
284+
```
285+
286+
> Note: Be sure to use the `name` field for each role, not the display name. Use
287+
> `coder organization roles show --org=<your-org>` to see roles for your
288+
> organization.
289+
290+
To set these role sync settings, use the following command:
291+
292+
```sh
293+
coder organizations settings set role-sync \
294+
--org <org-name> \
295+
< role-sync.json
296+
```
297+
298+
Visit the Coder UI to confirm these changes:
299+
300+
![IDP Sync](../images/admin/organizations/role-sync.png)
301+
302+
</div>
303+
304+
## Organization Sync (Premium)
305+
306+
> Note: In a future Coder release, this can be managed via the Coder UI instead
307+
> of server flags.
308+
309+
If your OpenID Connect provider supports groups/role claims, you can configure
310+
Coder to synchronize claims in your auth provider to organizations within Coder.
311+
312+
First, confirm that your OIDC provider is sending clainms by logging in with
313+
OIDC and visiting the following URL with an `Owner` account:
314+
315+
```text
316+
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
317+
```
318+
319+
You should see a field in either `id_token_claims`, `user_info_claims` or both
320+
followed by a list of the user's OIDC groups in the response. This is the
321+
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
322+
the OIDC provider. See
323+
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
324+
325+
> Depending on the OIDC provider, this claim may be named differently. Common
326+
> ones include `groups`, `memberOf`, and `roles`.
327+
328+
Next configure the Coder server to read groups from the claim name with the
329+
[OIDC organization field](../reference/cli/server.md#--oidc-organization-field)
330+
server flag:
331+
332+
```sh
333+
# as an environment variable
334+
CODER_OIDC_ORGANIZATION_FIELD=groups
335+
```
336+
337+
Next, fetch the corresponding organization IDs using the following endpoint:
338+
339+
```text
340+
https://[coder.example.com]/api/v2/organizations
341+
```
342+
343+
Set the following in your Coder server [configuration](./configure.md).
344+
345+
```env
346+
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
347+
```
348+
349+
> One claim value from your identity provider can be mapped to many
350+
> organizations in Coder (e.g. the example above maps to 2 organizations in
351+
> Coder.)
352+
353+
By default, all users are assigned to the default (first) organization. You can
354+
disable that with:
355+
356+
```env
357+
CODER_OIDC_ORGANIZATION_ASSIGN_DEFAULT=false
358+
```
359+
360+
## Troubleshooting group/role/organization sync
99361

100362
Some common issues when enabling group/role sync.
101363

102364
### General guidelines
103365

104366
If you are running into issues with group/role sync, is best to view your Coder
105367
server logs and enable
106-
[verbose mode](https://coder.com/docs/v2/v2.5.1/cli#-v---verbose). To reduce
368+
[verbose mode](../../reference/cli/index.md#-v---verbose). To reduce
107369
noise, you can filter for only logs related to group/role sync:
108370

109371
```sh

0 commit comments

Comments
 (0)