Interfejs Directory API umożliwia kontrola dostępu oparta na rolach (RBAC) aby zarządzać dostępem do funkcji w domenie Google Workspace. Możesz utworzyć niestandardowe role z uprawnieniami do ograniczania dostępu administracyjnego bardziej szczegółowo niż gotowych ról dostępnych w Google Workspace. Możesz przypisywać role użytkownikom lub grupom zabezpieczeń. Z tego przewodnika dowiesz się, jak wykonać podstawowych zadań związanych z rolą.
Poniżej znajdziesz listę typowych terminów używanych w interfejsie Directory API z w odniesieniu do RBAC w Google Workspace:
- Uprawnienie
- Uprawnienia niezbędne do wykonania zadania lub operacji w aplikacji
domenę Google Workspace. Reprezentowane przez
Privilege
. OK nie są danymi trwałymi powiązanymi z tym zasobem. - Role
- Zbiór uprawnień, które zapewniają jednostkom z tą rolą
możliwość wykonywania określonych zadań. Reprezentowane przez
Role
. - Przypisywanie roli
- Rekord określonej roli nadanej użytkownikowi lub grupie. Reprezentowane przez
RoleAssignment
- Grupa zabezpieczeń
- Typ Grupa Cloud Identity która służy do kontrolowania dostępu do organizacji i zasobami Google Cloud. Grupy zabezpieczeń mogą zawierać zarówno pojedynczych użytkowników, jak i grupy.
Limity przypisywania ról i ról
Możesz utworzyć tylko 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ć . Role i przypisania ról podlegają tym ograniczeniom:
- Możesz utworzyć do 750 ról niestandardowych dla całej organizacji.
- Możesz utworzyć maksymalnie 1000 przypisanych ról na jednostka organizacyjna, w której organizacja główna jest uznawana za jednostkę. Możesz na przykład przypisać 600 ról w organizacji głównej i 700 ról w organizacji głównej w innej określonej przez Ciebie jednostce organizacyjnej, np. w dziale firmy. Wszystkie gotowe role administratora Google Workspace domyślnie w całej organizacji. Więcej informacji o ograniczenia uprawnień które można przypisać na poziomie jednostki organizacyjnej.
Role i przypisywanie ról mają te ograniczenia w przypadku grup:
- Możesz przypisać dowolną rolę z wyjątkiem superadministratora.
- Łącznie możesz przypisać maksymalnie 250 ról do grup w całej jednostce organizacyjnej i w każdej jednostce organizacyjnej.
- Grupa musi być grupą zabezpieczeń w organizacji.
- Zalecamy ograniczenie członkostwa w grupach tylko do użytkowników w organizacji. Ty mogą dodawać użytkowników spoza organizacji, ale może nie mieć uprawnień roli. Więcej informacji: Ogranicz członkostwo w grupie. ### Przypisanie ról do grup
Jeśli musisz przypisać więcej niż 1000 ról w jednostce organizacyjnej, możesz dodać kilka członków grupy zabezpieczeń i przypisanie do niej roli. Rola w grupie projekty mają dodatkowe ograniczenia. Zobacz Centrum pomocy dla administratorów.
Mapowanie ról do uprawnień w konsoli administracyjnej Google
Aby przypisać role użytkownikom z dostępem do ich uprawnień za pomocą
konsoli administracyjnej, możesz potrzebować pewnych dodatkowych uprawnień
przyznane. Aby na przykład zezwolić użytkownikowi na tworzenie innych użytkowników za pomocą
w konsoli administracyjnej to nie tylko uprawnienie USERS_CREATE
,
wymagane, ale także USERS_UPDATE
i ORGANIZATION_UNITS_RETRIEVE
uprawnień. Poniższa tabela mapuje konsolę administracyjną
funkcji do wymaganych uprawnień do zarządzania użytkownikami
jednostek organizacyjnych.
Funkcje konsoli administracyjnej | Wymagane uprawnienia |
---|---|
Jednostki organizacyjne – odczyt | ORGANIZATION_UNITS_RETRIEVE |
Jednostki organizacyjne – utwórz | 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 – przeczytane | 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 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/usuwanie aliasów | USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Użytkownicy – zawieszanie kont użytkowników | USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
GRUPY | GROUPS_ALL |
Zabezpieczenia – zarządzanie zabezpieczeniami użytkowników | USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Przykłady użycia
Zanim zaczniesz
Wypełnij uwierzytelnianie i autoryzacja dla Google Workspace.
Pobieranie listy uprawnień domeny
Aby wyświetlić podzieloną na strony listę obsługiwanych uprawnień w domenie, skorzystaj z
privileges.list()
.
Jeśli jesteś administratorem otrzymującym uprawnienia w swojej domenie, użyj
my_customer
jako identyfikator klienta.Jeśli jesteś sprzedawcą i otrzymujesz uprawnienia dla jednego z klientów, użyj identyfikatora klienta zwróconego przez funkcję Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
Odpowiedź
Pomyślna odpowiedź zwraca stan HTTP 200 w kodzie. Razem z kodu stanu, odpowiedź zwróci 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 uzyskać listę istniejących ról, użyj poniższego żądania GET
i dołącz
autoryzacja opisana w sekcji Autoryzacja
.
Jeśli jesteś administratorem i otrzymujesz role w swojej domenie, użyj funkcji
my_customer
jako identyfikator klienta.Jeśli jako sprzedawca otrzymujesz role dla klienta, użyj identyfikatora klienta za pomocą narzędzia Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles
Odpowiedź
Pomyślna odpowiedź zwraca stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci role, które istnieją 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 wyświetlić podzieloną na strony listę wszystkich bezpośrednich przypisań ról, użyj funkcji
roleAssignments.list()
. Interfejs API może zwrócić puste wyniki z tokenem strony, gdy userKey
. Kontynuuj dzielenie na strony, dopóki token strony nie zostanie
.
Jeśli jesteś administratorem i otrzymujesz role w swojej domenie, użyj funkcji
my_customer
jako identyfikator klienta.Jeśli jesteś sprzedawcą i otrzymujesz role dla jednego z klientów, użyj identyfikatora klienta zwróconego przez funkcję Pobierz użytkownika.
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments
Odpowiedź
Pomyślna odpowiedź zwraca stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci 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 pośrednio
przypisanego użytkownikowi ze względu na grupę, do której on należy, użyj funkcji
roleAssignments.list()
.
Interfejs API może zwracać puste wyniki z tokenem strony. Kontynuuj dzielą się na strony, dopóki nie nie zostanie zwrócony żaden token strony.
Jeśli jesteś administratorem i otrzymujesz role w swojej domenie, użyj funkcji
my_customer
jako identyfikator klienta.Jeśli jesteś sprzedawcą i otrzymujesz role dla jednego z klientów, użyj identyfikatora klienta zwróconego przez funkcję Pobierz użytkownika.
Zastąp
USER_KEY
wartością, która identyfikuje wartość w żądaniu do interfejsu API. Więcej informacji:users.get
Żądanie
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true
Odpowiedź
Pomyślna odpowiedź zwraca stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci wszystkie role przypisane w domenie oraz informację, czy
assigneeType
to user
lub group
:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"group",
"scopeType:"CUSTOMER",
}
Tworzenie roli
Aby utworzyć nową rolę, skorzystaj z prośby POST
i dołącz
autoryzacja opisana w sekcji Autoryzacja
.
Dodaj privilegeName
i serviceId
dla każdego uprawnienia, które powinno być
danej roli. Właściwości żądania i odpowiedzi znajdziesz w sekcji Interfejs API
Plik referencyjny.
Żą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 stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci 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 metody POST
i dołącz autoryzację
opisane w
Autoryzacja żądań.
Aby przypisać rolę użytkownikowi, dodaj treść JSON z identyfikatorem
user_id
użytkownika. które można zusers.get()
,roleId
(jak opisano w Pobierz istniejące role) iscope_type
.Aby przypisać rolę do konta usługi, dodaj treść JSON z
unique_id
konta usługi (zgodnie z definicją w Identity and Access Management (uprawnienia)),roleId
(jak opisano w Pobierz istniejące role) iscope_type
.Aby przypisać rolę do grupy, dodaj treść JSON z
group_id
do której można uzyskać dostępgroups.get()
,roleId
(jak opisano w Pobierz istniejące role), iscope_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 stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci 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 przypisywać role do wykonywania działań, które spełniają określone warunki. Obecnie obsługiwane są tylko dwa warunki:
- Problem dotyczy tylko grup zabezpieczeń
- Nie dotyczy grup zabezpieczeń
Jeśli zasada condition
jest skonfigurowana, będzie miała zastosowanie tylko wtedy, gdy zasób
spełnia warunek. Jeśli pole condition
jest puste, rola (roleId
) jest
zastosowane do użytkownika (assignedTo
) w zakresie (scopeType
) bezwarunkowo.
Aby przypisać rolę użytkownikowi, użyj metody POST opisanej poniżej i dołącz autoryzacja opisana w Autoryzuj .
Dodaj treść JSON z obiektem user_id
użytkownika, z którego można uzyskać dostęp
users.get(), a roleId
jako
opisane w sekcji Uzyskiwanie istniejących ról oraz condition
.
ciągi warunków muszą być użyte w sposób dosłowny, jak pokazano poniżej.
działają tylko z edytorem grup i czytnikiem grup
gotowych ról administratora.
Te warunki są spełnione
Składnia warunków Cloud IAM.
Żądanie
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 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 stan HTTP 200
Razem z
kodu stanu, odpowiedź zwróci 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'"
}