Interfejs Directory API umożliwia zarządzanie dostępem do funkcji w domenie Google Workspace za pomocą kontroli dostępu na podstawie ról (RBAC). Możesz tworzyć niestandardowe role z uprawnieniami, aby bardziej precyzyjnie ograniczać dostęp administratora niż role gotowe udostępniane w Google Workspace. Możesz przypisać role użytkownikom lub grupom zabezpieczeń. W tym przewodniku wyjaśniamy, jak wykonywać podstawowe zadania związane z rolami.
Poniżej znajdziesz listę typowych terminów używanych przez interfejs Directory API w odniesieniu do RBAC w Google Workspace:
- Uprawnienie
- Uprawnienia niezbędne do wykonania zadania lub operacji w domenie Google Workspace. Reprezentowane przez zasób
Privilege
. Z tym zasobem nie są powiązane żadne dane trwałe. - Role
- Zbiór uprawnień, które przyznaje podmiotom o tej roli możliwość wykonywania określonych zadań lub operacji. Reprezentowane przez zasób
Role
. - Przypisanie roli
- Dane o konkretnej roli nadanej użytkownikowi lub grupie. Reprezentowane przez zasób
RoleAssignment
. - Grupa zabezpieczeń
- Typ grupy Cloud Identity, który służy do kontrolowania dostępu do zasobów organizacyjnych. Grupy zabezpieczeń mogą zawierać zarówno poszczególnych użytkowników, jak i grupy.
Limity związane z rolami i rolami
Możesz utworzyć ograniczoną liczbę ról niestandardowych lub przypisań ról, więc jeśli zbliżasz się do limitu, skonsoliduj je lub usuń, aby nie przekraczać limitu. Role i przypisania ról podlegają tym ograniczeniom:
- Możesz utworzyć maksymalnie 750 ról niestandardowych dla całej organizacji.
- Możesz utworzyć do 500 przypisanych ról na jednostkę organizacyjną, w której organizacja główna jest uznawana za jednostkę. Na przykład możesz przypisać 350 ról w organizacji głównej i 400 ról w innej zdefiniowanej jednostce organizacyjnej, takiej jak dział firmy. Wszystkie gotowe role administratora Google Workspace mają domyślny zakres obowiązujący w całej organizacji. Dowiedz się więcej o limitach uprawnień, które można przypisywać na poziomie jednostki organizacyjnej.
Role i przypisywanie ról mają następujące limity w przypadku grup:
- Możesz przypisać dowolną rolę oprócz superadministratora.
- Łącznie możesz mieć maksymalnie 250 przypisanych ról do grup w ogólnej jednostce organizacyjnej i w każdej jednostce organizacyjnej.
- Grupa musi być grupą zabezpieczeń w organizacji.
- Zalecamy ograniczenie członkostwa w grupie do użytkowników w Twojej organizacji. Możesz dodawać użytkowników spoza organizacji, ale mogą oni nie uzyskać odpowiednich uprawnień. Więcej informacji znajdziesz w artykule Ograniczanie członkostwa w grupach.
Przypisywanie ról do grup
Jeśli chcesz przypisać więcej niż 500 ról w jednostce organizacyjnej, możesz dodać do grupy zabezpieczeń więcej użytkowników i przypisać do niej role. Przypisywanie ról w grupie podlega pewnym dodatkowym ograniczeniom. Więcej informacji 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, konieczne może być przyznanie Ci dodatkowych uprawnień. Aby na przykład przyznać użytkownikowi możliwość tworzenia innych kont użytkowników w konsoli administracyjnej, wymagane jest nie tylko uprawnienie USERS_CREATE
, ale też uprawnienia USERS_UPDATE
i ORGANIZATION_UNITS_RETRIEVE
. W tabeli poniżej mapujemy funkcje konsoli administracyjnej na wymagane uprawnienia 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 – przenieś użytkowników | USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – zmienianie nazw użytkowników | USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – resetowanie hasła | 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 użycia
Zanim zaczniesz
Wykonaj czynności dotyczące uwierzytelniania i autoryzacji w Google Workspace.
Pobieranie listy uprawnień domeny
Aby uzyskać podzieloną na strony listę obsługiwanych uprawnień w domenie, użyj metody privileges.list()
.
Jeśli jesteś administratorem i masz uprawnienia we własnej domenie, użyj
my_customer
jako identyfikatora klienta.Jeśli jesteś sprzedawcą i otrzymujesz uprawnienia dla jednego z klientów, użyj identyfikatora klienta zwróconego przez operację Pobierz konto użytkownika.
Prośba
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
Odpowiedź
Pomyślna odpowiedź zwraca kod stanu HTTP 200. Wraz z kodem stanu odpowiedź zwraca 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
}
]
},
...
]
}
Pobierz istniejące role
Aby pobrać listę istniejących ról, użyj poniższego żądania GET
i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.
Jeśli jesteś administratorem i otrzymujesz role we własnej domenie, użyj
my_customer
jako identyfikatora klienta.Jeśli sprzedawcy otrzymują role dla klienta, użyj identyfikatora klienta uzyskanego za pomocą operacji Pobierz konto użytkownika.
Prośba
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ź zwraca role istnieją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ć podzieloną na strony listę wszystkich przypisań ról bezpośrednich, użyj metody roleAssignments.list()
. Gdy ustawiony jest parametr userKey
, interfejs API może zwracać puste wyniki z tokenem strony. Należy kontynuować podział na strony, dopóki nie zostanie zwrócony żaden token strony.
Jeśli jesteś administratorem i otrzymujesz przypisania ról we własnej domenie, użyj
my_customer
jako identyfikatora klienta.Jeśli jesteś sprzedawcą i przypisujesz role jednemu z klientów, użyj identyfikatora klienta zwróconego przez operację Pobierz użytkownika.
Prośba
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ź zwraca wszystkie role przypisane w domenie:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"user",
"scopeType:"CUSTOMER",
}
Wyświetl wszystkie pośrednie przypisania ról
Aby uzyskać podzieloną na strony listę wszystkich przypisań ról, w tym tych przypisanych pośrednio 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. Należy kontynuować podział na strony, dopóki nie zostanie zwrócony token strony.
Jeśli jesteś administratorem i otrzymujesz przypisania ról we własnej domenie, użyj
my_customer
jako identyfikatora klienta.Jeśli jesteś sprzedawcą i przypisujesz role jednemu z 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 do interfejsu API. Więcej informacji:users.get
.
Prośba
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ź zwraca wszystkie role przypisane w domenie i określa, 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 privilegeName
i serviceId
dla każdego uprawnienia, które ma otrzymać tę rolę. Właściwości żądania i odpowiedzi znajdziesz w dokumentacji interfejsu API.
Prośba
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
. Wraz z kodem stanu odpowiedź zwraca 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 poniższej metody POST
i uwzględnij autoryzację opisaną w sekcji Autoryzowanie żądań.
Aby przypisać rolę użytkownikowi, dodaj treść JSON z wartością
user_id
użytkownika, którą można pobrać zusers.get()
,roleId
(jak opisano w sekcji Uzyskiwanie istniejących ról) iscope_type
.Aby przypisać tę rolę do konta usługi, dodaj treść JSON z
unique_id
konta usługi (zgodnie z definicją w sekcji Identity and Access Management (Uprawnienia)),roleId
(jak opisano w sekcji Pobieranie istniejących ról) orazscope_type
.Aby przypisać rolę do grupy, dodaj treść JSON z obiektem
group_id
grupy, który można pobrać zgroups.get()
,roleId
(jak opisano w sekcji Pobieranie istniejących ról) iscope_type
.
Prośba
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
. Wraz z kodem stanu odpowiedź zwraca 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 roli z warunkami
Możesz przypisać role umożliwiające wykonywanie działań spełniających określone warunki. Obecnie obsługiwane są tylko 2 warunki:
- Problem dotyczy tylko grup zabezpieczeń
- Nie ma zastosowania do grup zabezpieczeń
Jeśli zasada condition
jest skonfigurowana, będzie obowiązywać tylko wtedy, gdy dostęp do zasobu spełnia warunek. Jeśli zasada condition
jest pusta, rola (roleId
) jest bezwarunkowo stosowana do użytkownika (assignedTo
) w zakresie (scopeType
).
Aby przypisać rolę użytkownikowi, użyj opisanej poniżej metody POST i dołącz autoryzację opisaną w artykule Autoryzowanie żądań.
Dodaj treść JSON z elementem user_id
użytkownika (które można pobrać za pomocą users.get(), roleId
zgodnie z opisem w sekcji Pobieranie istniejących ról oraz z condition
). Dwa ciągi warunków muszą być użyte dosłownie w sposób pokazany poniżej oraz działają tylko z gotowymi rolami administratora w edytorze grup i Czytniku grup.
Warunki te są zgodne ze składnią warunków Cloud IAM.
Prośba
Problem 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 ma zastosowania do 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
. Wraz z kodem stanu odpowiedź zwraca 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'"
}