RBAC Resources

Roles

A role is a collection of access policies, containing a list of access permissions. You can assign only one role to a subject.

The example below describes the Partner Developer role, which is available to all partners by default. The example lists all the access policies included in this role. These access policies can be reused to define other roles. For example, the Analytics Viewer policy can be part of another role, where the user needs Analytics Viewer capabilities in the Conversation Platform Console.

When you define the role, you need to define the role "type", which can be "USER" or "SERVICE". This will help you filter your roles in user management and client credentials management.

Note: The "id" value below is just an example. When a role is created, the Conversation Platform will create a corresponding unique identifier for that role.

Example

{
  "id" : "99999999-9999-9999-9999-999999999999",
  "name": "Partner developer",
  "description": "This role enables partner developers to configure Conversation Platform resources for their organization. It also gives them access to the Conversation Platform Console and Analytics reports as a Viewer.",
  "type": "USER",
  "isCanned":  true,
  "access_policies": [
		"/access_policies/{{Partner Developer access policy ID}}",
		"/access_policies/{{Conversation Platform Console login access policy ID}}"
        "/access_policies/{{Analytics Viewer access policy ID}}"
	]
}

See the RBAC API documentation to understand the full schema of a role resource and its supported operations.

Access policies

Access policies represent a set of permissions and allow the reuse of common sets of permissions to simplify the assignment of roles to subjects.

Below is an example of a partner developer access policy definition, which allows access to all the operations on Skills, Virtual Agents, Tasks, the Visualizer, VAC configurations, and Channel Origins.

The scope "*" allows one Conversation Platform partner to entrust another Conversation Platform partner with its resources.

Note: The "id" value below is just an example. When an access policy is created, the Conversation Platform will create a corresponding unique identifier for that policy.

Example

{
  "id" : "88888888-8888-8888-8888-888888888888",
  "name": "Developer Access Policy",
  "description": "This Access Policy allows partner developer access to all resources needed to configure the Conversation Platform. e.g. Skills, VAC etc.",
  "isCanned":  true,
  "permissions": [
      {
          "effect": "ALLOW",
          "actions": [
              "skills:*",
              "virtualagents:*",
              "tasks:*",
              "visualizer:*",
              "vacconfigs:*",
              "channelorigins:*"
          ],
          "scopes": [
              "*"
          ]
      }
  ]
}        

See the RBAC API documentation for the full schema of an access policy and its supported operations.

Permissions

There are several different ways to write permissions within access policies.

Permissions allow or deny access to perform specific operations or actions on resource types. The list of operations includes: “read” (R), "list" (R), “create" (C), "update" (U), "protected" (U), “delete” (D), or “execute” (X).

An example of a "create" (C) operation is creating a conversation or creating a role. The "execute" (X) operation is a custom action on the resource type. An example of the "execute" operation is allowing the user to join a conversation.

Permissions can also have a specific scope, which restricts access to a subset of resources. For example, permissions can be applied to a specific Skill or to a Business Segment.

The following examples aim to give you an idea of what permission you can use to access different resources.

Examples

1. Using permissions to allow access to all operations on all resources under a default scope:

{
    "effect": "allow",
    "actions": [ "*:*" ],
    "scopes": [ ]
}

2. Using permissions to allow access to all operations on the Channel Origin under a specific Business Segment:

{
    "effect": "allow",
    "actions": [ "channelorigins:*" ],
    "scopes": ["/partners/{{partner-id}}/businesssegments/{{Business-Segment-Id}}"]
}

3. Using permissions to allow access to individual operations (read, join) on the Conversation resource under default scope:

{
    "effect": "allow",
    "actions": [ "conversations:read", "conversations:join" ],
    "scopes": [ ]
}

4. Using permissions to allow access to a custom individual operation (execute) with explicit scope for certain skills:

{
    "effect": "allow",
    "actions": [ "skills:execute" ],
    "scopes": ["/partners/{{partner-id}}/skills/{{air-cancel-skill-id}}", "/partners/{{partner-id}}/skills/{{air-change-skill-id}}"]
}

5. Using permissions that explicitly denies the create operation on all resources under the default scope:

{
    "effect": "deny",
    "actions": [ "*:create" ],
    "scopes": [ ]
}

An access policy can contain multiple permissions allowing or denying resource access based on scope. This example shows you how to allow access to all the operations on a skill, with the exception of deleting the skill.

Example

{
  "permissions": [
      {
          "effect": "ALLOW",
          "actions": [
              "skills:*",
              "virtualagents:*",
              "tasks:*",
              "visualizer:*",
              "vacconfigs:*",
              "channelorigins:*"
          ],
          "scopes": [
              "*"
          ]
      }
      {
          "effect": "DENY",
          "actions": [
              "skills:delete",
          ],
          "scopes": [
              "*"
          ]
      }
  ]     

Access and authorization patterns

Next, let's understand how these permissions are mapped to access requests, to give you an idea about what access will be allowed or denied at runtime based on the permissions defined.

Below is the mapping of the Conversation Platform run time access pattern and what permission is needed for authorization. This is a generic pattern that applies to all the resources in the Conversation Platform. See the API References for detailed documentation of individual Conversation Platform resource APIs.

Note: The resourcePath identifies the exact path of that resource in the resource hierarchy.

Examples

• GET /partners/{partner id}/conversations - get all resources of type "Conversation" created under Partner Id.
• GET /partners/{partner id}/businesslocations/{bussinessSegment id}- get specific businessSegment created under partner Id.
• GET /partners/{partner id}/businesslocations/{bussinessSegment id}/channelorigins - get all channelorigins created under specific Business Segment represented by {bussinessSegment Id}

Scope

Permissions allow or deny access to perform specific operations/actions on resource types.

Scope specifies the resources to which the Subject has access (i.e. the Cancel Skill or the View Booking Skill).

With the RBAC model, you can specify scope within permissions, or within the role assignment. If you do not define the scope, the platform will apply the default scope.

Here are the different scope values and their definitions:

Role assignment

A role assignment allows you to give a role to a subject. Access is granted by creating a role assignment, and access is revoked by deleting a role assignment. To create and remove role assignments, you must have the "roleassignments:create" and "roleassigments:delete" permissions. The Access Administrator built-in role provides this access.

A role assignment can also specify a scope, which limits access to a subset of resources.

Here is an example of how the built-in Partner Developer role can be assigned to a user with default scope. This will give the user access to all the partner resources defined in this role.

Note: The "id" value below is just an example. When a Role Assignment is created, the Conversation Platform will create a corresponding unique identifier for that Role Assignment.

Example

{
    "id": "44444444-4444-4444-4444-444444444444",
    "subject" : "/partners/{{partner-id}}/users/{{user-id}}",
    "role": "/roles/{{partner-developer-role-id}}"
    "scopes": []
}

See RBAC API documentation for the full schema of the Role Assignment resource, and all its supported operations.