Call Recording Control Permissions to an Existing Realm

This guide walks you through adding Call Recording Pause/Resume permissions to an existing Keycloak (EF IAM) realm.

Use these steps when the tenant is already set up with agents, users, and groups such as agents_permission and senior_agents_permission, and you only need to add the call_recording_control group and its authorization configuration to the cim client.

What Gets Added

Agent Desk uses manage_call_recording_control to show Pause/Resume on live recorded calls. Users without this scope still see the REC indicator only.

JSON import (recommended)

Open the Keycloak Admin Console at https://<CIM-FQDN>/auth/ and select the target tenant realm (not master).

Step 1 — Import the group

Save this file as call-recording-control-group.json.

{
  "groups": [
    {
      "name": "call_recording_control",
      "path": "/call_recording_control",
      "subGroups": []
    }
  ]
}

1. In the target realm, open Realm settings.

2. Open the Action menu (top right) and select Partial import.

3. Upload call-recording-control-group.json.

4. If the group already exists, choose Skip.

5. Click Import.

6. Confirm Groups → call_recording_control with path /call_recording_control.

You do not need to add roles or sub-groups to this group. If Partial import is not available, create the group manually: Groups → Create group → name call_recording_control → Save.

Step 2 — Import authorization on client cim

Save this file as call-recording-control-authz.json. Import it only after Step 1 succeeds.

{
  "resources": [
    {
      "name": "call_recording_control",
      "ownerManagedAccess": false,
      "displayName": "Call Recording Control",
      "attributes": {},
      "scopes": [
        { "name": "view_call_recording_control" },
        { "name": "manage_call_recording_control" }
      ]
    }
  ],
  "policies": [
    {
      "name": "view_call_recording_control_policy",
      "description": "Allows view access to Call Recording Control",
      "type": "group",
      "logic": "POSITIVE",
      "decisionStrategy": "UNANIMOUS",
      "config": {
        "groups": "[{\"path\":\"/call_recording_control\",\"extendChildren\":false}]"
      }
    },
    {
      "name": "manage_call_recording_control_policy",
      "description": "Allows manage access to Call Recording Control",
      "type": "group",
      "logic": "POSITIVE",
      "decisionStrategy": "UNANIMOUS",
      "config": {
        "groups": "[{\"path\":\"/call_recording_control\",\"extendChildren\":false}]"
      }
    },
    {
      "name": "view_call_recording_control_permission",
      "description": "View permission for Call Recording Control",
      "type": "scope",
      "logic": "POSITIVE",
      "decisionStrategy": "UNANIMOUS",
      "config": {
        "resources": "[\"call_recording_control\"]",
        "scopes": "[\"view_call_recording_control\"]",
        "applyPolicies": "[\"view_call_recording_control_policy\"]"
      }
    },
    {
      "name": "manage_call_recording_control_permission",
      "description": "Manage permission for Call Recording Control",
      "type": "scope",
      "logic": "POSITIVE",
      "decisionStrategy": "UNANIMOUS",
      "config": {
        "resources": "[\"call_recording_control\"]",
        "scopes": "[\"manage_call_recording_control\"]",
        "applyPolicies": "[\"manage_call_recording_control_policy\"]"
      }
    }
  ],
  "scopes": [
    { "name": "view_call_recording_control" },
    { "name": "manage_call_recording_control" }
  ]
}

1. Confirm Step 1 succeeded (group path is /call_recording_control).

2. Go to Clients → cim → Authorization.

3. Make sure Authorization Enabled is on.

4. Open Settings and click Import.

5. Upload call-recording-control-authz.json.

6. Confirm the resource, both scopes, both group policies, and both scope permissions exist, and that both scopes are attached to the resource.

Then continue from Assign Users to the New Group below. The following hidden Page Properties block keeps the original manual UI steps as a fallback.

Assign Users to the New Group

Reminder: Do not import users from the source realm file.

For each agent who should pause or resume call recording:

1. Go to Users and select the user.

2. Open the Groups tab, then click Join Groups.

3. Select call_recording_control, then click Join.

4. Ask the user to log out and log back in to Agent Desk.

Having agent or supervisor roles alone is not enough. The user must be in the call_recording_control group.

Verify Permissions in Keycloak

1. Go to Clients → cim → Authorization → Evaluate.

2. Set:

   • Client: cim

   • User: a test user in call_recording_control

   • Resource: call_recording_control

   • Scope: manage_call_recording_control

3. Click Evaluate.

Repeat for scope view_call_recording_control if needed.

Verify Login Response

After the user logs in to Agent Desk, check the login API response. In keycloak_User.permittedResources.Resources, the entry for call_recording_control must include a scopes array:

{
  "rsname": "call_recording_control",
  "scopes": [
    "view_call_recording_control",
    "manage_call_recording_control"
  ]
}

If call_recording_control appears without a scopes array, Pause/Resume will not work. See Troubleshooting below.

Verify in Agent Desk

1. Log in as a user assigned to call_recording_control.

2. Place or accept a CX Voice call with recording enabled on the extension.

3. Confirm:

   • REC indicator appears when recording is active.

   • Pause/Resume controls appear for users with manage_call_recording_control.

4. Log in as a user not in the group. REC may show, but Pause/Resume must not be available.

Troubleshooting

Unknown error when importing the authorization JSON

Symptom: Clients → cim → Authorization → Import shows Unknown error.

Cause: The group /call_recording_control does not exist yet. Authorization import cannot create groups.

Fix: Complete Step 1 (group file / Partial import, or create the group manually), then import call-recording-control-authz.json again.

Unrecognized field "permissions"

Cause: The authorization JSON has a top-level permissions array. This Keycloak version rejects that field.

Fix: Use the authorization JSON from Step 2. Permissions must be type: "scope" entries inside policies.

Resource appears in login but scopes are empty

Symptom: Login response shows call_recording_control with rsname but no scopes array.

Fix:

1. Edit resource call_recording_control and attach both scopes (section 2.4).

2. Confirm both scope-based permissions exist, are Enabled, and have policies linked (section 2.6).

3. Confirm the user is in group call_recording_control.

4. Re-run Evaluate in Keycloak — must show PERMIT.

5. User must log out and log back in.

Pause/Resume not visible in Agent Desk