Interfejs Directory API umożliwia korzystanie z kontroli dostępu opartej na rolach (RBAC) do zarządzania dostępem do funkcji w domenie Google Workspace. Możesz tworzyć role niestandardowe z uprawnieniami, aby ograniczyć dostęp administratora w bardziej szczegółowy sposób niż w przypadku wstępnie utworzonych ról dostępnych w Google Workspace. Role możesz przypisać użytkownikom lub grupom zabezpieczeń. Z tego przewodnika dowiesz się, jak wykonywać podstawowe czynności związane z rolą.
Poniżej znajdziesz listę najpopularniejszych terminów używanych przez interfejs Directory API w odniesieniu do RBAC w Google Workspace:
- Uprawnienie
- Uprawnienie wymagane do wykonania zadania lub operacji w domenie Google Workspace. Zasób
Privilege
. Z tym zasobem nie są powiązane żadne dane trwałe. - Role
- Zbiór uprawnień, który umożliwia podmiotom z tą rolą wykonywanie określonych zadań lub operacji. Zasób
Role
. - Przypisanie roli
- Wpis dotyczący konkretnej roli przypisanej użytkownikowi lub grupie. Reprezentowane przez zasób
RoleAssignment
. - Grupa zabezpieczeń
- Typ grupy Cloud Identity służący do kontrolowania dostępu do zasobów organizacji. Grupy zabezpieczeń mogą zawierać zarówno pojedynczych użytkowników, jak i grupy.
Limity dotyczące ról i przypisywania ról
Możesz utworzyć tylko ograniczoną liczbę ról niestandardowych lub przypisań ról, więc jeśli zbliżasz się do limitu, scal je lub usuń, aby nie przekroczyć limitu. Role i przypisania ról mają te limity:
- Możesz utworzyć do 750 ról niestandardowych dla całej organizacji.
- Możesz utworzyć maksymalnie 1000 przydziałów ról na jednostkę organizacyjną (OU), przy czym organizacja główna jest traktowana jako jednostka. Możesz na przykład przypisać 600 ról w głównej organizacji i 700 ról w innej zdefiniowanej przez Ciebie jednostce organizacyjnej, np. w dziale firmy. Wszystkie gotowe role administratora Google Workspace są domyślnie ustawione na zakres obejmujący całą organizację. Dowiedz się więcej o ograniczeniach uprawnień, które można przypisać na poziomie jednostki organizacyjnej.
Role i przypisywanie ról mają w przypadku grup te limity:
- Możesz przypisać dowolną rolę oprócz roli superadministratora.
- Możesz utworzyć maksymalnie 250 przypisań ról do grup (sumując przypisania na poziomie całej jednostki organizacyjnej i w poszczególnych jednostkach organizacyjnych).
- Grupa musi być grupą zabezpieczeń w Twojej organizacji.
- Zalecamy ograniczenie członkostwa w grupach do użytkowników w Twojej organizacji. Możesz dodawać użytkowników spoza organizacji, ale mogą oni nie dostać uprawnień. Szczegółowe informacje znajdziesz w artykule Ograniczanie członkostwa w grupie. ### Przypisywanie ról grupom
Jeśli chcesz przypisać więcej niż 1000 ról w jednostce organizacyjnej, możesz dodać do grupy zabezpieczeń wielu użytkowników i przypisać rolę całej tej grupie. Przypisanie ról grupowych wiąże się z kilkoma dodatkowymi ograniczeniami. Szczegółowe informacje znajdziesz w Centrum pomocy dla administratorów.
Mapowanie ról na uprawnienia w konsoli administracyjnej Google
Aby przypisać role użytkownikom, którzy uzyskują dostęp do swoich uprawnień w konsoli administracyjnej, może być konieczne przyznanie dodatkowych uprawnień. Aby na przykład umożliwić użytkownikowi tworzenie innych użytkowników w konsoli administracyjnej, wymagane są nie tylko uprawnienia USERS_CREATE
, ale też uprawnienia USERS_UPDATE
i ORGANIZATION_UNITS_RETRIEVE
. W tabeli poniżej funkcje konsoli administracyjnej są powiązane z wymaganymi uprawnieniami do zarządzania użytkownikami i jednostkami organizacyjnymi.
Funkcje konsoli administracyjnej | Wymagane uprawnienia |
---|---|
Jednostki organizacyjne – odczyt | ORGANIZATION_UNITS_RETRIEVE |
Jednostki organizacyjne – tworzenie | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE |
Jednostki organizacyjne – aktualizacja | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE |
Jednostki organizacyjne – usuwanie | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE |
Jednostki organizacyjne | ORGANIZATION_UNITS_ALL |
Użytkownicy – odczyt | USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – tworzenie | USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – aktualizacja | USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – przenoszenie użytkowników | USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – zmiana nazwy użytkownika | USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – zresetuj hasło | USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – wymuszanie zmiany hasła | USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – dodawanie i usuwanie aliasów | USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – zawieszanie użytkowników | USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
GRUPY | GROUPS_ALL |
Bezpieczeństwo – zarządzanie zabezpieczeniami użytkowników | USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Przykłady zastosowań
Zanim zaczniesz
Wykonaj czynności dotyczące uwierzytelniania i autoryzacji w Google Workspace.
Uzyskiwanie listy uprawnień domeny
Aby uzyskać posortowaną listę obsługiwanych uprawnień w domenie, użyj metody privileges.list()
.
Jeśli jesteś administratorem i chcesz uzyskać uprawnienia w swojej domenie, jako identyfikator klienta użyj wartości
my_customer
.Jeśli jesteś sprzedawcą i uzyskiwanie uprawnień dla jednego z Twoich klientów, użyj identyfikatora klienta zwróconego przez operację Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też uprawnienia obsługiwane w domenie:
{
"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
}
]
},
...
]
}
Pobieranie istniejących ról
Aby uzyskać listę istniejących ról, użyj tego żądania GET
i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.
Jeśli jesteś administratorem i przypisujesz role w swojej domenie, jako identyfikator klienta użyj wartości
my_customer
.Jeśli jesteś sprzedawcą i chcesz uzyskać role klienta, użyj identyfikatora klienta otrzymanego za pomocą operacji Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też role występujące w domenie:
{
"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
},
...
]
}
Wyświetlanie listy wszystkich przypisań ról
Aby uzyskać posortowaną listę wszystkich bezpośrednich przypisań ról, użyj metody roleAssignments.list()
. Gdy ustawiony jest parametr userKey
, interfejs API może zwracać puste wyniki z tokenem strony. Powinieneś kontynuować pobieranie stron do momentu, gdy nie zostanie zwrócony token strony.
Jeśli jesteś administratorem i przypisujesz role w swojej domenie, jako identyfikator klienta użyj wartości
my_customer
.Jeśli jesteś sprzedawcą i chcesz uzyskać przypisania ról dla jednego z Twoich klientów, użyj identyfikatora klienta zwróconego przez operację Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też wszystkie role przypisane w domenie:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"user",
"scopeType:"CUSTOMER",
}
Wyświetlanie listy wszystkich pośrednich przypisań ról
Aby uzyskać ponumerowane zestawienie wszystkich przypisań ról, w tym tych pośrednio przypisanych do użytkownika z powodu grup, do których należy, użyj metody roleAssignments.list()
.
Interfejs API może zwrócić puste wyniki z tokenem strony. Przewijanie należy kontynuować, dopóki nie zostanie zwrócony token strony.
Jeśli jesteś administratorem i przypisujesz role w swojej domenie, jako identyfikator klienta użyj wartości
my_customer
.Jeśli jesteś sprzedawcą i chcesz uzyskać przypisania ról dla jednego z Twoich klientów, użyj identyfikatora klienta zwróconego przez operację Pobierz użytkownika.
Zastąp
USER_KEY
wartością, która identyfikuje użytkownika w żądaniu interfejsu API. Więcej informacji znajdziesz w sekcjiusers.get
.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też wszystkie role przypisane w domenie oraz informacje o tym, czy assigneeType
ma wartość user
czy group
:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"group",
"scopeType:"CUSTOMER",
}
Tworzenie roli
Aby utworzyć nową rolę, użyj poniższego żądania POST
i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań.
Dodaj element privilegeName
i serviceId
dla każdego uprawnienia, które ma być przyznawane w ramach tej roli. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.
Żądanie
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" } ] }
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też właściwości nowej roli:
{
"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"
}
]
}
Tworzenie przypisania roli
Aby przypisać rolę, użyj tej metody POST
i dodaj autoryzację opisaną w artykule Autoryzowanie żądań.
Aby przypisać rolę użytkownikowi, dodaj treść JSON z
user_id
użytkownika, którą możesz uzyskać zusers.get()
,roleId
(jak opisano w Uzyskiwanie istniejących ról) orazscope_type
.Aby przypisać rolę do konta usługi, dodaj treść w formacie JSON z
unique_id
konta usługi (zdefiniowanym na stronie Identity and Access Management (IAM)),roleId
(zdefiniowanym na stronie Pobieranie istniejących ról) orazscope_type
.Aby przypisać rolę do grupy, dodaj treść JSON z
group_id
grupy, którą możesz uzyskać zgroups.get()
,roleId
(jak opisano w Uzyskiwanie istniejących ról) orazscope_type
.
Żądanie
POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments { "roleId": "3894208461012995", "assignedTo": "100662996240850794412", "scopeType": "CUSTOMER" }
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też właściwości nowego przypisania roli:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId": "3894208461013211",
"roleId": "3894208461012995",
"assignedTo": "100662996240850794412",
"scopeType": "CUSTOMER"
}
Tworzenie przypisania ról z warunkami
Możesz przyznać role, aby wykonywać działania, które spełniają określone warunki. Obecnie obsługiwane są tylko 2 warunki:
- Dotyczy tylko grup zabezpieczeń
- Nie dotyczy grup zabezpieczeń
Gdy parametr condition
jest ustawiony, ma on zastosowanie tylko wtedy, gdy zasobem, do którego uzyskujesz dostęp, jest zasób spełniający warunek. Jeśli condition
jest pusty, rola (roleId
) jest bezwarunkowo stosowana do podmiotu (assignedTo
) w zakresie (scopeType
).
Aby przypisać rolę użytkownikowi, użyj podanej niżej metody POST i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.
Dodaj treść JSON z user_id
użytkownika, który możesz pobrać z users.get(), roleId
zgodnie z opisem w artykule Pobieranie istniejących ról oraz condition
. Te 2 ciągi znaków warunków muszą być używane w takiej postaci, jak pokazano poniżej. Działają tylko z wstępnie utworzonymi rolami administratora Grup dyskusyjnych (czyli z rolami Grup dyskusyjnych Google dla edytujących i czytających).
Warunki te są zgodne ze składnią warunków Cloud IAM.
Żądanie
Dotyczy tylko grup zabezpieczeń
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'" }
Nie dotyczy grup zabezpieczeń
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'" }
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200
. Oprócz kodu stanu odpowiedź zawiera też właściwości nowego przypisania roli:
{
"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'"
}