Setup Keycloak for VRS

Follow the steps below for setting up Keycloak for VRS

1. Go to FQDN:8088/auth and click on the Administration console

2. Log in to the administration console using the password set in environment variables (KEYCLOAK_USER and KEYCLOAK_PASSWORD). The default username is admin, and the password is admin

3. Bring the cursor to the Master (below the Keycloak logo) and click on the Create realm button

4. Enter the Realm name and click on the Create button

5. Once the Realm is created, click on clients under the created realm, and then click the create client button

6. Enter Client ID vrs and click on Next.

7. Toggle the Client authentication and Authorization to ON, click Next, and click Save

8. Once the client is saved, go to the Credentials tab and copy the client secret. The Client ID (vrs) and Secret will be used in environment variables (KEYCLOAK_CLIENT_ID and KEYCLOAK_CLIENT_SECRET)

9. Click on Realm Roles in the left panel and create the desired roles: admin, agent, supervisor, download, evaluatetag, and export. From 14.11.0, viewtag is not required (all users can view tags).

10. Go to Users and create user by entering Username and click Create.

11. Go to the Credentials tab of the created user and set a password, toggle the Temporary button to OFF, and click Save.

12. Open the created user, go to the Role mapping tab, click on Assign Role, select the desired roles (for example admin, agent, supervisor, download, evaluatetag, and/or export), and click on Assign.

Example — agent user: assign the realm role agent (keep default-roles-vrs). Add-on roles such as download are optional.

13. For Admin user only,

    1. Assign the admin role other than the default roles assigned previously.

    2. Now, click on the Assign Role button again, and then select the Filter by clients option in the dropdown.

       

    3. Open the items per page drop-down and select 50 items per page.

       

    4. Now type realm in the search box and press Enter or click the Next button.

       

    5. Upon searching, all the realm-management roles will appear; assign all the realm roles to the Admin user.

    6. When finished, the admin user's Role mapping tab should show the realm role admin (plus any add-ons such as download / export / evaluatetag) and the realm-management client roles.

       

Creation of Keycloak Agent Group for VRS Finesse Gadget

For deployments using the VRS Finesse gadget, the following steps are required as well:

1. Open the target realm, i.e., VRS.

2. Navigate to the Groups section in Keycloak.

3. Click the Create group button.

4. Create a group named AGENT_GROUP.

5. Open AGENT_GROUP and navigate to the Role mapping tab.

6. Assign the realm role agent to this group.

7. If the agent role does not exist, first create it under Realm roles, then return to AGENT_GROUP and assign it.

Supervisor role and department groups

For supervisors (Media Recordings department scoping and Operations Dashboard access), use the same realm role supervisor. Create it under Realm roles if it does not exist (step 9). No separate dashboard role is required.

Screenshots below match the walkthrough in VRS User Guide section 2.1 Supervisor departments.

1. Open the VRS realm → Groups → create a parent group named Departments.

   

2. Under Departments, create a child group for each team (for example sale) so the path is /Departments/sale.

   

3. On the child group → Members, add agent users and the supervisor user to the same child group. Agent usernames in Keycloak must match the Cisco agentId values used by VRS.

   
   

4. On the vrs client → Client scopes → dedicated scope → Mappers, open the groups (Group Membership) mapper and set Full group path to On so the token shows /Departments/sale, not only sale.

   
   

5. Assign the realm role supervisor to the supervisor user (keep default roles).

   

6. Keep the Keycloak service account permission view-users (and typically query-users / query-groups) on the vrs client → Service accounts roles. It is required for supervisor department scoping on Media Recordings and the Operations Dashboard. If revoked, supervisor resolution fails safe (empty allowed list).