Enhance user roles to limit camera access (#20024)

* update config for roles and add validator

* ensure admin and viewer are never overridden

* add class method to user to retrieve all allowed cameras

* enforce config roles in auth api endpoints

* add camera access api dependency functions

* protect review endpoints

* protect preview endpoints

* rename param name for better fastapi injection matching

* remove unneeded

* protect export endpoints

* protect event endpoints

* protect media endpoints

* update auth hook for allowed cameras

* update default app view

* ensure anonymous user always returns all cameras

* limit cameras in explore

* cameras is already a list

* limit cameras in review/history

* limit cameras in live view

* limit cameras in camera groups

* only show face library and classification in sidebar for admin

* remove check in delete reviews

since admin role is required, no need to check camera access. fixes failing test

* pass request with camera access for tests

* more async

* camera access tests

* fix proxy auth tests

* allowed cameras for review tests

* combine event tests and refactor for camera access

* fix post validation for roles

* don't limit roles in create user dialog

* fix triggers endpoints

no need to run require camera access dep since the required role is admin

* fix type

* create and edit role dialogs

* delete role dialog

* fix role change dialog

* update settings view for roles

* i18n changes

* minor spacing tweaks

* docs

* use badges and camera name label component

* clarify docs

* display all cameras badge for admin and viewer

* i18n fix

* use validator to prevent reserved and empty roles from being assigned

* split users and roles into separate tabs in settings

* tweak docs

* clarify docs

* change icon

* don't memoize roles

always recalculate on component render

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** → Read-only 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
+
+The viewer role provides read-only access to all cameras in the UI and API. Custom roles allow admins to limit read-only access to specific cameras. Each role specifies an array of allowed camera names. If a user is assigned a custom role, their account is like the **viewer** role - they can only view Live, Review/History, Explore, and Export for the designated 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` (preferred), or unauthenticated via port `5000`.
+2. Navigate to **Settings**.
+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