User role (role)

Description

A role available for assignment in user role lists.
Allows binding permissions to access REST and WebSocket API (routes) and role web applications (webapps).
A user assigned the role gets access to the specified APIs and web applications.
In particular, user roles can be used to build role models based on dynamic classes and their corresponding role applications.
Supports inheritance.

The full set of roles with lists of groups and users to whom they are assigned is available via API roles_caches.

Fields

Entity structure
{
  "id": uuid,
  "name": str,
  "description": str,
  "parent_id": uuid,
  "routes": array<object>,
  "opts": {
    "title": str,
    "comment": str
  },
  "security": object,
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Fields
Specification Description

Field: id
Mode: inout
Type: uuid
Default: generated

Identifier. Can be specified at creation, otherwise generated by the system.

Field: name
Mode: in
Type: str
Default: required

Role name (lowercase Latin).

There are predefined roles for which allowed routes are already set in the build metadata. When a role with the same name is created, the permissions are merged.

The list of predefined roles may vary; the main ones are listed below:

  • admin - does not check route permissions and provides full access to any collections in the domain. Opens the 'Settings' application in the domain. Must be assigned directly to a user.

  • crud - provides access to all static collections of the domain center in the domain, both for reading and modification (Create, Read, Update, Delete). Does not open any predefined applications. Must be assigned directly to a user.

  • meet - provides API access to the VCS service. Opens the "VCS" application.

  • monitor - provides access to the system monitoring API. Does not open any predefined applications.

  • scripteditor - provides access to the script editor WebSocket API. Opens the 'Script editor' application.

  • user - provides access to static collections with user data. Opens the 'Softphone' application and the product layer 'Cabinet'.

For a user to be able to modify data in static collections of the domain center, the role 'admin', 'crud', or 'crud.*' (where * is an arbitrary string) must be assigned directly in the user’s account. In any other case the domain center will not allow the request, even if the routes allow it.
All other roles can be assigned both to a user and to a group the user belongs to.

Several approaches can be used to configure project-specific roles that have modification access to some static collections of the domain center (beyond those allowed by the 'user' role):

  • Set the role name to "crud.*", where * is an arbitrary text sequence. The user is allowed access to static collections of the domain center according to route settings. This is the only way the user can pass the domain center filter.

  • Create a product microservice that processes user requests, determines access by project logic, and proxies requests to the domain center on behalf of an admin.

  • Create a dynamic collection that the user works with according to the granted accesses; create a product microservice that, according to project logic, performs an ETL synchronization operation between the dynamic collection and the target static collection of the domain center.

  • Create a service script to process arbitrary API requests with verification of the initiating user’s rights, assign it to an integration channel, and execute requests via /exec or /api/token/v1 or /api/token/v1/:TOKEN.

Field: description
Mode: in
Type: str
Default: empty

Role description

Field: parent_id
Mode: in
Type: str
Default: empty

Identifier of the base group whose settings are fully copied.

Field: routes
Mode: in
Type: array<object>
Default: empty

List of allowed API endpoints.
Specified in a format similar to iam_all.json.

Each list element is an object:

{
  "url": ...,
  "method": [...]
}

The URL must specify a concrete endpoint. Supported:

  • "*" - any value of a folder or element name;

  • "**" - any remaining path (only at the end of the path);

  • "*" - any path from the endpoint, including the endpoint itself without a trailing slash.

Within each collection, the following endpoints are distinguished:

  • collection ("/rest/v1/model/my/test");

  • collection element ("/rest/v1/model/my/test/*");

  • attachment or list field ("/rest/v1/model/my/test/*/*" or "/rest/v1/model/my/test/*/propertyname");

  • attachment in a list field ("/rest/v1/model/my/test/*/*/*" or "/rest/v1/model/my/test/*/propertyname/*").

Or "/rest/v1/model/my/test/**" - all collection endpoints except the collection endpoint itself.

Methods: "GET", "POST", "PUT", "PATCH", "DELETE", "LOOKUP", "HEAD", "CLEAR", "*", "WEBSOCKET".

There are other non-standard methods for specific endpoints. For example, the "INVITEBYIVR" method is used to create a call on behalf of IVR. They are listed in the API description of specific endpoints. Such methods are included in "*" or must be specified separately.

The "WEBSOCKET" method is used to grant access to various WebSocket APIs. The specific API module is specified after the hash in "url" (see the example below).

Example:

[
  {
    "url": "/rest/v1/model/my/test",
    "methods": ["GET","CLEAR"]
  },
  {
    "url": "/rest/v1/model/my/test/*",
    "methods": ["GET","PUT","PATCH","DELETE"]
  },
  {
    "url": "/rest/v1/model/my/test/**",
    "methods": ["*"]
  },
  {
      "url": "/ws#subscr",
      "methods": ["WEBSOCKET"]
  }
]

Field: webapps
Mode: in
Type: array
Default: empty

Returns the list of web applications available to the role.

Field: opts
Mode: in
Type: object
Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Arbitrary title

Field: opts.comment
Mode: in
Type: empty
Default: "

Arbitrary comment

Field: security
Mode: inout
Type: object
Compound field

Allows extending the compound with arbitrary keys and values.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending the compound with arbitrary keys and values.

Field: ext.ct
Mode: out
Type: date
Default: generated

Object creation time

Field: ext.lwt
Mode: out
Type: date
Default: generated

Time of last modification of the object

See also