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 access for agents in the same Keycloak /Departments/<name> group(s); can open the Operations Dashboard. Same realm role for both; see scope difference 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. 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: admin and supervisor can open the dashboard; agent cannot. Dashboard metrics are tenant-wide for the selected date range and skill filter — department groups do not limit OD aggregates. Details: Operations Dashboard.
Service account: the Keycloak service account still needs view-users for supervisor Media Recordings department scoping. If revoked, supervisor resolution fails safe to an empty allowed list (no elevated access). Ops Dashboard does not use view-users, but keep it for the overall supervisor feature.

Department groups apply to Media Recordings only. On the Operations Dashboard, a supervisor sees the same tenant-wide metrics as an admin for that tenant.

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. 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.
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.