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
и включите авторизацию, описанную в разделе «Авторизация запросов» .
Чтобы назначить роль пользователю, добавьте тело JSON с
user_id
пользователя, который вы можете получитьusers.get()
,roleId
(как описано в разделе Получение существующих ролей )scope_type
.Чтобы назначить роль учетной записи службы, добавьте тело JSON с
unique_id
учетной записи службы (как определено в разделе Управление идентификацией и доступом (IAM) ),roleId
(как описано в разделе Получение существующих ролей )scope_type
.Чтобы назначить роль группе, добавьте тело JSON с
group_id
группы, который вы можете получить изgroups.get()
,roleId
(как описано в разделе Получение существующих ролей )scope_type
.
Запрос
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'"
}