Управление ролями

API каталога позволяет использовать управление доступом на основе ролей (RBAC) для управления доступом к функциям в вашем домене Google Workspace. Вы можете создавать пользовательские роли с привилегиями , чтобы более точно ограничивать доступ администратора, чем это предусмотрено в готовых ролях Google Workspace. Вы можете назначать роли пользователям или группам безопасности . В этом руководстве объясняется, как выполнять некоторые основные задачи, связанные с ролями.

Ниже приведён список распространённых терминов, используемых API каталога в отношении управления доступом на основе ролей (RBAC) в Google Workspace:

Привилегия
Разрешение, необходимое для выполнения задачи или операции в домене Google Workspace. Представлено ресурсом Privilege . С этим ресурсом не связаны никакие постоянные данные.
Роль
Набор привилегий, предоставляющих сущностям с данной ролью возможность выполнять определенные задачи или операции. Представлен ресурсом Role .
Назначение ролей
Запись о конкретной роли, присвоенной пользователю или группе. Представлена ​​ресурсом RoleAssignment .
Группа безопасности
Тип группы облачной идентификации , используемый для управления доступом к ресурсам организации. Группы безопасности могут содержать как отдельных пользователей, так и группы.

Ограничения на роли и назначение ролей

Вы можете создать лишь ограниченное количество пользовательских ролей или назначений ролей, поэтому, если вы приближаетесь к лимиту, объедините или удалите их, чтобы остаться в пределах допустимого количества. Для ролей и назначений ролей действуют следующие ограничения:

  • Вы можете создать до 750 пользовательских ролей для всей вашей организации.
  • Вы можете создать до 1000 назначений ролей для каждой организационной единицы (OU), где корневая организация считается единицей. Например, вы можете назначить 600 ролей в корневой организации и 700 ролей в другой определенной вами организационной единице, например, в отделе компании. Все предварительно созданные роли администратора Google Workspace по умолчанию имеют область действия, охватывающую всю организацию. Узнайте больше об ограничениях на привилегии , которые можно назначить на уровне организационной единицы.

Для групп действуют следующие ограничения на роли и их назначение:

  • Вы можете назначить любую роль, кроме роли суперадминистратора.
  • В рамках всего организационного подразделения и в каждом отдельном подразделении можно назначить до 250 ролей группам.
  • Эта группа должна быть группой безопасности в вашей организации.
  • Мы рекомендуем ограничить членство в группах только пользователями вашей организации. Вы можете добавлять пользователей извне вашей организации, но они могут не получить соответствующие привилегии. Подробнее см. раздел «Ограничение членства в группах» . ### Назначение ролей группам

Если вам необходимо назначить более 1000 ролей в организационном подразделении, вы можете добавить несколько участников в группу безопасности и назначить группе роль. Назначение ролей группам имеет некоторые дополнительные ограничения — подробную информацию см. в справочном центре администратора .

Сопоставление ролей и привилегий в консоли администратора Google

Для назначения ролей пользователям, получающим доступ к своим привилегиям через консоль администратора, может потребоваться предоставление определенных дополнительных прав. Например, чтобы предоставить пользователю возможность создавать других пользователей через консоль администратора, требуется не только привилегия USERS_CREATE , но и привилегии USERS_UPDATE и ORGANIZATION_UNITS_RETRIEVE . В следующей таблице показано соответствие функциональности консоли администратора необходимым правам для управления пользователями и организационными подразделениями.

Функциональность административной консоли Необходимые привилегии
Организационные подразделения - Читать ORGANIZATION_UNITS_RETRIEVE
Организационные подразделения - Создание ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Организационные подразделения - Обновление ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Организационные подразделения - Удалить ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Организационные подразделения ORGANIZATION_UNITS_ALL
Пользователи - Читать USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Создать USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Обновление USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Переместить пользователей USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Переименовать пользователей USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Сброс пароля USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Принудительная смена пароля USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Добавление/удаление псевдонимов USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Пользователи - Приостановить действие учетных записей пользователей USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
ГРУППЫ GROUPS_ALL
Безопасность - Управление безопасностью пользователей USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Примеры использования

Прежде чем начать

Перед запуском примеров из этого руководства настройте аутентификацию и авторизацию .

  1. Настройте экран согласия OAuth .

  2. Создать учетные данные доступа .

Получить список привилегий домена

Чтобы получить постраничный список поддерживаемых привилегий в вашем домене, используйте метод privileges.list() .

  • Если вы являетесь администратором и получаете привилегии в собственном домене, используйте my_customer в качестве идентификатора клиента.

  • Если вы являетесь реселлером и получаете привилегии для одного из своих клиентов, используйте идентификатор клиента, возвращаемый операцией «Получить пользователя» .

Запрос 

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Ответ

В случае успешного ответа возвращается код состояния HTTP 200. Вместе с кодом состояния ответ содержит информацию о поддерживаемых в домене привилегиях:

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

Получить существующие роли

Чтобы получить список существующих ролей, используйте следующий GET запрос и укажите авторизацию, описанную в разделе «Авторизация запросов» .

  • Если вы являетесь администратором и получаете роли в собственном домене, используйте my_customer в качестве идентификатора клиента.

  • Если вы являетесь реселлером и получаете роли для клиента, используйте идентификатор клиента, полученный с помощью операции «Получить пользователя» .

Запрос 

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ содержит информацию о ролях, существующих в домене:

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

Перечислите все назначенные роли.

Для получения постраничного списка всех прямых назначений ролей используйте метод roleAssignments.list() . API может вернуть пустые результаты с токеном страницы, если задан параметр userKey . Вам следует продолжать постраничную навигацию до тех пор, пока не будет возвращен токен страницы.

  • Если вы являетесь администратором и назначаете роли в своем домене, используйте my_customer в качестве идентификатора клиента.

  • Если вы являетесь реселлером и получаете назначения ролей для одного из своих клиентов, используйте идентификатор клиента, возвращаемый операцией «Получить пользователя» .

Запрос 

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ возвращает все роли, назначенные в домене:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Перечислите все косвенные назначения ролей.

Чтобы получить постраничный список всех назначений ролей, включая те, которые были назначены пользователю косвенно в зависимости от групп, к которым он принадлежит, используйте метод roleAssignments.list() .

API может возвращать пустые результаты с токеном страницы. Вам следует продолжать пагинацию до тех пор, пока не будет возвращен ни один токен страницы.

  • Если вы являетесь администратором и назначаете роли в своем домене, используйте my_customer в качестве идентификатора клиента.

  • Если вы являетесь реселлером и получаете назначения ролей для одного из своих клиентов, используйте идентификатор клиента, возвращаемый операцией «Получить пользователя» .

  • Замените USER_KEY значением, идентифицирующим пользователя в API-запросе. Для получения дополнительной информации см. users.get .

Запрос 

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ возвращает все роли, назначенные в домене, и указывает, является ли assigneeType user или group :

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Создать роль

Для создания новой роли используйте следующий POST запрос и включите авторизацию, описанную в разделе «Авторизация запросов» . Добавьте privilegeName и serviceId для каждой привилегии, которая должна быть предоставлена ​​этой роли. Свойства запроса и ответа см. в справочнике API .

Запрос 

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ возвращает свойства для новой роли: 

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Создать назначение роли

Для назначения роли используйте следующий метод POST и укажите авторизацию, описанную в разделе «Авторизация запросов» .

Запрос 

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ возвращает свойства для нового назначения роли: 

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Создайте назначение роли с условиями.

Вы можете назначать ролям права на выполнение действий, отвечающих определенным условиям. В настоящее время поддерживаются только два условия:

  • Применимо только к группам безопасности
  • Не применимо к группам безопасности

Если condition задано, оно вступит в силу только тогда, когда доступный ресурс будет соответствовать этому условию. Если condition пустое, роль ( roleId ) применяется к актору ( assignedTo ) в области действия ( scopeType ) безусловно.

Для назначения роли пользователю используйте следующий метод POST и укажите авторизацию, описанную в разделе «Авторизация запросов» .

Добавьте JSON-тело, содержащее user_id пользователя, который можно получить с помощью users.get() , roleId , как описано в разделе «Получение существующих ролей» , и condition . Две строки условия необходимо использовать без изменений, как показано ниже, и они работают только с предварительно созданными ролями администратора «Редактор групп» и «Читатель групп». Эти условия соответствуют синтаксису условий Cloud IAM .

Запрос

Применимо только к группам безопасности 
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}
Не применимо к группам безопасности 
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

Ответ

В случае успешного ответа возвращается код состояния HTTP 200 Вместе с кодом состояния ответ возвращает свойства для нового назначения роли: 

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}