From e9fbfcc45b996e7e55f1f7a06cdedeb595b4f717 Mon Sep 17 00:00:00 2001
From: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Date: Wed, 30 Oct 2024 11:41:52 -0500
Subject: [PATCH] chore(docs): include custom roles examples and mention of
 password reset (#15294)

Added example custom roles for admin inspiration, mention of headless
authentication use case, and user-activated password reset.
---
 docs/admin/users/groups-roles.md | 19 +++++++++++++++++++
 docs/admin/users/index.md        |  7 ++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/admin/users/groups-roles.md b/docs/admin/users/groups-roles.md
index 17c0fc8b5b..e40efb0bd5 100644
--- a/docs/admin/users/groups-roles.md
+++ b/docs/admin/users/groups-roles.md
@@ -42,6 +42,25 @@ in the dashboard under **Organizations** -> **My Organization** -> **Roles**.
 
 ![Custom roles](../../images/admin/users/roles/custom-roles.PNG)
 
+### Example roles
+
+- The `Banking Compliance Auditor` custom role cannot create workspaces, but can
+  read template source code and view audit logs
+- The `Organization Lead` role can access user workspaces for troubleshooting
+  purposes, but cannot edit templates
+- The `Platform Member` role cannot edit or create workspaces as they are
+  created via a third-party system
+
+Custom roles can also be applied to
+[headless user accounts](./headless-auth.md):
+
+- A `Health Check` role can view deployment status but cannot create workspaces,
+  manage templates, or view users
+- A `CI` role can update manage templates but cannot create workspaces or view
+  users
+
+### Creating custom roles
+
 Clicking "Create custom role" opens a UI to select the desired permissions for a
 given persona.
 
diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md
index 6b500ea68a..a00030a514 100644
--- a/docs/admin/users/index.md
+++ b/docs/admin/users/index.md
@@ -143,7 +143,12 @@ Confirm the user activation by typing **yes** and pressing **enter**.
 
 ## Reset a password
 
-To reset a user's via the web UI:
+As of 2.17.0, users can reset their password independently on the login screen
+by clicking "Forgot Password." This feature requires
+[email notifications](../monitoring/notifications/index.md#smtp-email) to be
+configured on the deployment.
+
+To reset a user's password as an administrator via the web UI:
 
 1. Go to **Users**.
 2. Find the user whose password you want to reset, click the vertical ellipsis