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

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

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

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

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

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

  • Вы можете создать до 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

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

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

Выполните шаги аутентификации и авторизации для Google Workspace.

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

Чтобы получить постраничный список поддерживаемых привилегий в вашем домене, используйте метод 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'"
}