Update role sync documentation for clarity

Ensure users reference the correct fields when mapping roles from the IDP to internal roles. - Clarified the field to use for the role mapping. - Listed built-in role identifiers explicitly.
coder · stirby · Oct 1, 2024 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
commit 941d9c260077ef25abdb6a02d581ae4d5b74b691
diff --git a/docs/admin/auth.md b/docs/admin/auth.md
@@ -520,7 +520,7 @@ The default for an organization looks like this:
 
 Below is an example that uses the `roles` claim and maps `coder-admins` from the
 IDP as an `Organization Admin` and also maps to a custom `provisioner-admin`
-role:
+role.
 
 ```json
 {
@@ -532,6 +532,10 @@ role:
 }
 ```
 
+> Note: Be sure to use the `name` field for each role, not the display name. Use
+> `organization-admin`, `organization-user-admin`, `organization-auditor` for
+> the built in roles.
+
 To set these role sync settings, use the following command:
 
 ```sh