VRS Authorization & Permissions

This document details the roles a user can assume in VRS and the permissions associated with each role.

Roles & Permissions

A user in VRS can assume any role from the following list of supported roles.

admin — base role; access all recordings and admin features (Recording Rules, Audit Logs, Archival, Tag Management CRUD). Can open the Operations Dashboard.
agent — base role; access only their own recordings. Cannot open the Operations Dashboard.
supervisor — base role (from VRS 14.9.0); Media Recordings and Operations Dashboard access for agents in the same Keycloak /Departments/<name> group(s) (OD department scoping from 14.12.0). Same realm role for both; see scope details below.
download — add-on role; allows downloading recording media files (WAV / MP3). Button is hidden without this role.
export — add-on role; allows exporting recording data to CSV. Button is hidden without this role.
evaluatetag — add-on role; assign or unassign one or more tags on Media Recordings. Can be assigned to admin, agent, or supervisor users. Viewing tags and using the Tag filter does not require a role. Not used for Tag Management CRUD.

Create roles under Keycloak Realm roles and assign them on the user's Role mapping tab (keep default roles for authentication). Assign admin, agent, or supervisor as the base role, plus add-on roles as needed. Role and department setup: Setup Keycloak for VRS.

From VRS 14.11.0, the viewtag role is no longer needed. All users can view tags. Only evaluatetag is required to assign or unassign tags. If viewtag still exists from a 14.10.0 Keycloak setup, it can be left unused or removed.

How roles combine

Base role (admin, agent, or supervisor) sets which recordings a user sees and whether the Operations Dashboard is available; add-on roles grant extra actions (download, export, tag assign).

Supervisor role and department groups

Use the same existing Keycloak realm role supervisor for Media Recordings department scoping and for Operations Dashboard access. There is no separate dashboard role.

Media Recordings: a supervisor sees recordings for agents who are members of the same /Departments/<name> group(s). Place agent users and the supervisor user in those groups. Agent usernames in Keycloak must match the recording agentId values used by VRS.
Operations Dashboard (from 14.12.0): admin and supervisor can open the dashboard; agent cannot. Dashboard metrics use the same department scoping as Media Recordings — a supervisor sees aggregates only for agents in their /Departments/<name> group(s); an admin sees tenant-wide metrics. Details: Operations Dashboard.
Service account: the Keycloak service account needs view-users for supervisor department scoping on Media Recordings and on the Operations Dashboard. If revoked, supervisor resolution fails safe to an empty allowed list (no elevated access).

From VRS 14.12.0: Department groups apply to both Media Recordings and the Operations Dashboard. A supervisor no longer sees tenant-wide OD metrics.

How to create /Departments/<name> groups and assign membership: Setup Keycloak for VRS.

ENABLE_AGENT_DOWNLOAD

ENABLE_AGENT_DOWNLOAD in config.env still applies. When it is enabled, the download capability is turned on. The Keycloak download role then determines which individual users (agents or administrators) may download. Without the download role, the Download button is hidden.

Export is separate: it requires the Keycloak export role. Having only download does not allow export. Without export, the Export button is hidden.

After upgrading

Create the realm roles in Keycloak if they do not exist: download, export, evaluatetag, and supervisor (if you use supervisors).
Assign download and/or export to users who should download or export. Without these roles, those buttons stay hidden.
Assign evaluatetag to users who should assign or unassign tags on Media Recordings (including supervisors who need tag assign). Tag viewing and Tag filtering do not require a special role.
For supervisors: assign the supervisor role, place the supervisor and agents in the correct /Departments/<name> groups, and keep service-account view-users (required for Media Recordings and Operations Dashboard department scoping).
Existing admin and agent users keep their base access; add-on roles are extra and must be assigned explicitly.
From 14.11.0, you do not need to create or assign viewtag.