Zarządzaj rolami

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.

Uwaga: do tworzenia grup zabezpieczeń musisz użyć interfejsu Cloud Identity API. i nie można używać interfejsu Directory API. Więcej informacji znajdziesz w dokumentacji grupy zabezpieczeń.

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ć z users.get(), roleId (jak opisano w sekcji Uzyskiwanie istniejących ról) i scope_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) oraz scope_type.

• Aby przypisać rolę do grupy, dodaj treść JSON z obiektem group_id grupy, który można pobrać z groups.get(), roleId (jak opisano w sekcji Pobieranie istniejących ról) i scope_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

Uwaga: ta funkcja jest dostępna tylko w wersji v1.1beta1 interfejsu API i tylko dla klientów Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus i Cloud Identity Premium. Ta funkcja nie wymaga dodatkowej konfiguracji. Przypisywanie ról z warunkami nie jest jeszcze uwzględniane w konsoli administracyjnej.

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'"
}