From a4a8f3d1a9929c04ef36d6410af69b5cd7c1c9ce Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 24 Jul 2023 13:22:24 +0000 Subject: [PATCH 1/3] docs: role sync (enterprise) --- docs/admin/auth.md | 16 ++++++++++++++++ docs/admin/groups.md | 2 +- docs/admin/rbac.md | 2 +- docs/enterprise.md | 1 + 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/admin/auth.md b/docs/admin/auth.md index b80318b83fa13..37f070c4855c5 100644 --- a/docs/admin/auth.md +++ b/docs/admin/auth.md @@ -308,6 +308,22 @@ Steps to troubleshoot. - [Azure AD limit is 200, and omits groups if exceeded.](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#options-for-applications-to-consume-group-information) - [Okta limit is 100, and returns an error if exceeded.](https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned) +## Role sync (enterprise) + +If your OpenID Connect provider supports roles claims, you can configure Coder +to synchronize roles in your auth provider to deployment-wide roles within Coder. + +To enable group sync, ensure that the `roles` claim is set by adding the correct scope to request. If role sync is enabled, the user's roles will be controlled by the OIDC provider. This means manual group additions/removals will be overwritten on the next login. + +Set the following in your Coder server [configuration](./configure.md): + +```console +CODER_OIDC_USER_ROLE_FIELD=roles +CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthors":["template-admin","user-admin"]}' +``` + +> `CODER_OIDC_USER_ROLE_FIELD` can be used if a non-standard roles claim is used. + ## Provider-Specific Guides Below are some details specific to individual OIDC providers. diff --git a/docs/admin/groups.md b/docs/admin/groups.md index c0b5dca594dad..47ecf9e11ffe5 100644 --- a/docs/admin/groups.md +++ b/docs/admin/groups.md @@ -1,6 +1,6 @@ # Groups -Groups can be used with [template RBAC](./rbac.md) to give groups of users access to specific templates. +Groups can be used with [template RBAC](./rbac.md) to give groups of users access to specific templates. They can be defined in Coder or [synced from your identity provider](./auth.md#group-sync-enterprise). ![Groups](../images/groups.png) diff --git a/docs/admin/rbac.md b/docs/admin/rbac.md index 09808a353508b..211f134443889 100644 --- a/docs/admin/rbac.md +++ b/docs/admin/rbac.md @@ -1,6 +1,6 @@ # Role Based Access Control (RBAC) -Use RBAC to define which users and [groups](./groups.md) can use specific templates in Coder. +Use RBAC to define which users and [groups](./groups.md) can use specific templates in Coder. These can be defined in Coder or [synced from your identity provider](./auth.md) ![rbac](../images/template-rbac.png) diff --git a/docs/enterprise.md b/docs/enterprise.md index c487b406dc7b4..f2be0c759642f 100644 --- a/docs/enterprise.md +++ b/docs/enterprise.md @@ -7,6 +7,7 @@ trial](https://coder.com/trial). | Category | Feature | Open Source | Enterprise | | --------------- | ------------------------------------------------------------------------------------ | :---------: | :--------: | | User Management | [Groups](./admin/groups.md) | ❌ | ✅ | +| User Management | [Group & role sync](./admin/auth.md#group-sync-enterprise) | ❌ | ✅ | | User Management | [SCIM](./admin/auth.md#scim) | ❌ | ✅ | | Governance | [Audit Logging](./admin/audit-logs.md) | ❌ | ✅ | | Governance | [Browser Only Connections](./networking/#browser-only-connections-enterprise) | ❌ | ✅ | From b70f4f77d213ba7a18d7ac3abea7cde3a54fdfaa Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 27 Jul 2023 13:38:58 +0000 Subject: [PATCH 2/3] edits from code review --- docs/admin/auth.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/admin/auth.md b/docs/admin/auth.md index 37f070c4855c5..6c6626fe596cc 100644 --- a/docs/admin/auth.md +++ b/docs/admin/auth.md @@ -313,16 +313,18 @@ Steps to troubleshoot. If your OpenID Connect provider supports roles claims, you can configure Coder to synchronize roles in your auth provider to deployment-wide roles within Coder. -To enable group sync, ensure that the `roles` claim is set by adding the correct scope to request. If role sync is enabled, the user's roles will be controlled by the OIDC provider. This means manual group additions/removals will be overwritten on the next login. - -Set the following in your Coder server [configuration](./configure.md): +Set the following in your Coder server [configuration](./configure.md). ```console + # Depending on your identity provider configuration, you may need to explicitely request a "roles" scope +CODER_OIDC_SCOPES=openid,profile,email,roles + +# The following fields are requied for role sync: CODER_OIDC_USER_ROLE_FIELD=roles -CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthors":["template-admin","user-admin"]}' +CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}' ``` -> `CODER_OIDC_USER_ROLE_FIELD` can be used if a non-standard roles claim is used. +> 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.) ## Provider-Specific Guides From 1925fcf2a4971c7d25f768a507acf0c28f0c8a4d Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 1 Aug 2023 04:35:59 +0000 Subject: [PATCH 3/3] fix typo --- docs/admin/auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/auth.md b/docs/admin/auth.md index 6c6626fe596cc..ca16ce1eb08b0 100644 --- a/docs/admin/auth.md +++ b/docs/admin/auth.md @@ -316,10 +316,10 @@ to synchronize roles in your auth provider to deployment-wide roles within Coder Set the following in your Coder server [configuration](./configure.md). ```console - # Depending on your identity provider configuration, you may need to explicitely request a "roles" scope + # 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 requied for role sync: +# The following fields are required for role sync: CODER_OIDC_USER_ROLE_FIELD=roles CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}' ```