Zarządzaj rolami

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 sekcji 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 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ń.

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