docs: role sync (enterprise)

bpmct · bpmct · commit a4a8f3d1a992 · 2023-07-24T13:22:24.000Z
diff --git 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
@@ -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
@@ -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
@@ -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)        |     ❌      |     ✅     |
