From fe9368d2880275b72186c1859e7654d9632eb5ba Mon Sep 17 00:00:00 2001
From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>
Date: Thu, 11 Sep 2025 09:11:50 -0500
Subject: [PATCH] docs

---
 docs/docs/configuration/authentication.md | 45 +++++++++++++++++++++--
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/docs/docs/configuration/authentication.md b/docs/docs/configuration/authentication.md
index 7e77229b6..c6a8ef00d 100644
--- a/docs/docs/configuration/authentication.md
+++ b/docs/docs/configuration/authentication.md
@@ -124,7 +124,7 @@ proxy:
     role: x-forwarded-groups
 ```
 
-Frigate supports both `admin` and `viewer` roles (see below). When using port `8971`, Frigate validates these headers and subsequent requests use the headers `remote-user` and `remote-role` for authorization.
+Frigate supports `admin`, `viewer`, and custom roles (see below). When using port `8971`, Frigate validates these headers and subsequent requests use the headers `remote-user` and `remote-role` for authorization.
 
 A default role can be provided. Any value in the mapped `role` header will override the default.
 
@@ -136,7 +136,7 @@ proxy:
 
 ## Role mapping
 
-In some environments, upstream identity providers (OIDC, SAML, LDAP, etc.) do not pass a Frigate-compatible role directly, but instead pass one or more group claims. To handle this, Frigate supports a `role_map` that translates upstream group names into Frigate’s internal roles (`admin` or `viewer`).
+In some environments, upstream identity providers (OIDC, SAML, LDAP, etc.) do not pass a Frigate-compatible role directly, but instead pass one or more group claims. To handle this, Frigate supports a `role_map` that translates upstream group names into Frigate’s internal roles (`admin`, `viewer`, or custom).
 
 ```yaml
 proxy:
@@ -150,14 +150,17 @@ proxy:
         - access-level-security
       viewer:
         - camera-viewer
+      operator:  # Custom role mapping
+        - operators
 ```
 
 In this example:
 
 - If the proxy passes a role header containing `sysadmins` or `access-level-security`, the user is assigned the `admin` role.
 - If the proxy passes a role header containing `camera-viewer`, the user is assigned the `viewer` role.
+- If the proxy passes a role header containing `operators`, the user is assigned the `operator` custom role.
 - If no mapping matches, Frigate falls back to `default_role` if configured.
-- If `role_map` is not defined, Frigate assumes the role header directly contains `admin` or `viewer`.
+- If `role_map` is not defined, Frigate assumes the role header directly contains `admin`, `viewer`, or a custom role name.
 
 #### Port Considerations
 
@@ -167,6 +170,7 @@ In this example:
 - The `remote-role` header determines the user’s privileges:
   - **admin** → Full access (user management, configuration changes).
   - **viewer** → Read-only access.
+  - **Custom roles** → Access limited to the cameras defined in `auth.roles[role]`.
 - Ensure your **proxy sends both user and role headers** for proper role enforcement.
 
 **Unauthenticated Port (5000)**
@@ -212,6 +216,41 @@ Frigate supports user roles to control access to certain features in the UI and
 
 - **admin**: Full access to all features, including user management and configuration.
 - **viewer**: Read-only access to the UI and API, including viewing cameras, review items, and historical footage. Configuration editor and settings in the UI are inaccessible.
+- **Custom Roles**: Arbitrary role names (alphanumeric, dots/underscores) with specific camera permissions. These extend the system for granular access (e.g., "operator" for select cameras).
+
+### Custom Roles and Camera Access
+
+Custom roles allow fine-grained control over camera access. Each role specifies an array of allowed camera names. If a user is assigned a role, they are like the **viewer** role - they can only view Live, Review/History, Explore, and Export for those cameras. Backend API endpoints enforce this server-side (e.g., returning 403 for unauthorized cameras), and the frontend UI filters content accordingly (e.g., camera dropdowns show only permitted options).
+
+### Role Configuration Example
+
+```yaml
+cameras:
+  front_door:
+    # ... camera config
+  side_yard:
+    # ... camera config
+  garage:
+    # ... camera config
+
+auth:
+  enabled: true
+  roles:
+    operator: # Custom role
+      - front_door
+      - garage # Operator can access front and garage
+    neighbor:
+      - side_yard
+```
+
+If you want to provide access to all cameras to a specific user, just use the **viewer** role.
+
+### Managing User Roles
+
+1. Log in as an **admin** user via port `8971`.
+2. Navigate to **Settings > Users**.
+3. In the **Users** section, edit a user’s role by selecting from available roles (admin, viewer, or custom).
+4. In the **Roles** section, add/edit/delete custom roles (select cameras via switches). Deleting a role auto-reassigns users to "viewer".
 
 ### Role Enforcement