Роли через API

Через REST API можно создавать и изменять роли и их права, а также назначать роли пользователям и группам. Те же операции доступны в интерфейсе раздела Управление доступом → Роли; устройство раздела описано в статье Роли.

Запросы отправляйте на адрес сервера бэкенда, токен передавайте в заголовке Authorization:

POST /api/v1/roles
Authorization: Bearer <токен>
Content-Type: application/json

Методы

Роль

Назначение роли пользователям

Назначение роли группам

Идентификаторы roleId, userId и groupId — UUID из ответов системы.

Тело запроса роли

POST /api/v1/roles и PUT /api/v1/roles/{roleId} принимают один и тот же объект; у обоих методов обязательны name и permissions.

• name — название роли. Обязательное поле, от 1 до 255 символов, должно быть уникальным.
• description — описание роли. Необязательное поле.
• permissions — права роли. Обязательное поле; структура та же, что у персональных прав пользователя, состав и смысл прав описаны в разделе Управление правами пользователя.

Права состоят из двух блоков:

• balancer — права кластеров балансировки. Блок clusters[] содержит запись на каждый кластер:
  • id — имя кластера, то же значение, что clusterId в путях методов /api/v1/clusters/{clusterId};
  • full_access, add_services, edit — права кластера;
  • services[] — права по конфигурациям балансировки кластера: id — UUID конфигурации, read, edit, delete.
• gslb — права GSLB:
  • full_access — полный доступ ко всем GSLB-кластерам;
  • clusters[] — права по отдельным GSLB-кластерам: id и full_access. При включённом full_access массив clusters игнорируется.

Ответы

GET /api/v1/roles и GET /api/v1/roles/{roleId} возвращают роль с полями:

• id — UUID роли;
• name, description — название и описание;
• permissions — права в той же структуре, что в запросе;
• created_at, updated_at — дата и время создания и последнего изменения.

GET /api/v1/users/{userId}/roles возвращает роли пользователя — поля роли плюс:

• direct — true, если роль назначена пользователю персонально и её можно снять с него; false — роль получена только через группу;
• via_groups — названия групп, через которые пользователь получил роль.

GET /api/v1/roles/{roleId}/users возвращает по одной записи на каждого пользователя:

• id, username, first_name, last_name, email — идентификатор и учётные данные пользователя;
• direct, via_groups — назначение роли, как в списке ролей пользователя.

GET /api/v1/roles/{roleId}/groups возвращает по одной записи на группу:

• id, name, description — идентификатор, название и описание группы;
• source — происхождение группы: local — локальная, ldap — импортированная из LDAP;
• dn, ldap_config_id — distinguished name группы и идентификатор её конфигурации LDAP; заполняются только для групп с source: ldap.

Назначение и снятие

• POST /api/v1/users/{userId}/roles/{roleId} назначает роль персонально. Персональные права пользователя, если они заданы, имеют приоритет над правами роли.
• POST /api/v1/local-groups/{groupId}/roles/{roleId} назначает роль всем текущим участникам группы. DELETE снимает роль со всех участников, кроме тех, кто получает её через другую группу.
• POST /api/v1/ldap-groups/{groupId}/roles/{roleId} назначает роль LDAP-группе. Роль, назначенная группе, распространяется на всех её участников — см. Назначение роли группам.
• DELETE /api/v1/roles/{roleId} удаляет роль: назначения снимаются со всех пользователей и групп, которым роль была выдана.

Пример

Создание роли с правом редактирования кластера балансировки slb-1:

POST /api/v1/roles

{
  "name": "cluster-editor",
  "description": "Редактирование кластера slb-1",
  "permissions": {
    "balancer": {
      "clusters": [
        {
          "id": "slb-1",
          "full_access": false,
          "add_services": false,
          "edit": true,
          "services": []
        }
      ]
    },
    "gslb": { "full_access": false, "clusters": [] }
  }
}

Ответ 201 содержит id созданной роли. Назначьте роль пользователю:

POST /api/v1/users/<UUID пользователя>/roles/<UUID роли>

Ответ 200 без тела означает, что роль назначена.

Ошибки

Тело ошибки содержит три поля: