From 4456d0bfeaab787f0cb5d8bf34ceaca7f3cc6add Mon Sep 17 00:00:00 2001
From: Ben Potter <ben@coder.com>
Date: Tue, 1 Aug 2023 13:47:55 -0500
Subject: [PATCH] docs: sync roles (enterprise) (#8696)

* docs: role sync (enterprise)

* edits from code review

* fix typo
---
 docs/admin/auth.md   | 18 ++++++++++++++++++
 docs/admin/groups.md |  2 +-
 docs/admin/rbac.md   |  2 +-
 docs/enterprise.md   |  1 +
 4 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/docs/admin/auth.md b/docs/admin/auth.md
index 4c09ba7ab4..16807c159f 100644
--- a/docs/admin/auth.md
+++ b/docs/admin/auth.md
@@ -310,6 +310,24 @@ 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.
+
+Set the following in your Coder server [configuration](./configure.md).
+
+```console
+ # 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 required for role sync:
+CODER_OIDC_USER_ROLE_FIELD=roles
+CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
+```
+
+> 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
 
 Below are some details specific to individual OIDC providers.
diff --git a/docs/admin/groups.md b/docs/admin/groups.md
index c0b5dca594..47ecf9e11f 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 09808a3535..211f134443 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 c487b406dc..f2be0c7596 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)        |     ❌      |     ✅     |