Diese Seite wurde von der Cloud Translation API übersetzt.

Rollen verwalten

Mit der Directory API können Sie den Zugriff auf Funktionen in Ihrer Google Workspace-Domain mithilfe der rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) verwalten. Sie können benutzerdefinierte Rollen mit Berechtigungen erstellen, um den Administratorzugriff spezifischer als die vordefinierten Rollen in Google Workspace einzuschränken. Sie können Nutzern oder Sicherheitsgruppen Rollen zuweisen. In dieser Anleitung wird erläutert, wie Sie einige grundlegende rollenbezogene Aufgaben ausführen.

Im Folgenden finden Sie eine Liste häufiger Begriffe, die von der Directory API in Bezug auf RBAC in Google Workspace verwendet werden:

Berechtigung: Die Berechtigung, die zum Ausführen einer Aufgabe oder eines Vorgangs in einer Google Workspace-Domain erforderlich ist. Wird durch die Ressource Privilege dargestellt. Mit dieser Ressource sind keine persistenten Daten verknüpft.
Rolle: Eine Sammlung von Berechtigungen, die Entitäten mit dieser Rolle die Möglichkeit geben, bestimmte Aufgaben oder Vorgänge auszuführen. Wird durch die Ressource Role dargestellt.
Rollenzuweisung: Der Datensatz einer bestimmten Rolle, der dem Nutzer oder der Gruppe zugewiesen wurde. Dargestellt durch die Ressource RoleAssignment.
Sicherheitsgruppe: Eine Art von Cloud Identity-Gruppe, mit der der Zugriff auf Organisationsressourcen gesteuert wird. Sicherheitsgruppen können sowohl einzelne Nutzer als auch Gruppen enthalten.

Rollen- und Rollenzuweisungslimits

Sie können nur eine begrenzte Anzahl von benutzerdefinierten Rollen oder Rollenzuweisungen erstellen. Wenn Sie sich dem Limit nähern, konsolidieren oder entfernen Sie sie also, damit das Limit nicht überschritten wird. Für Rollen und Rollenzuweisungen gelten folgende Einschränkungen:

Sie können bis zu 750 benutzerdefinierte Rollen für die gesamte Organisation erstellen.
Sie können bis zu 500 Rollenzuweisungen pro Organisationseinheit (OE) erstellen, wobei die Stammorganisation als Einheit betrachtet wird. Sie können beispielsweise 350 Rollen in der Stammorganisation und 400 Rollen in einer anderen von Ihnen definierten Organisationseinheit (z. B. einer Abteilung eines Unternehmens) zuweisen. Alle vordefinierten Administratorrollen in Google Workspace sind standardmäßig auf organisationsweite Ebene beschränkt. Weitere Informationen zu Beschränkungen der Berechtigungen, die auf OE-Ebene zugewiesen werden können

Auf Rollen und Rollenzuweisung gelten folgende Einschränkungen für Gruppen:

Außer dem Super Admin können Sie jede Rolle zuweisen.
Sie können Gruppen in der gesamten OE und innerhalb jeder OE bis zu 250 Rollenzuweisungen zuweisen.
Die Gruppe muss eine Sicherheitsgruppe in Ihrer Organisation sein.
Wir empfehlen, die Gruppenmitgliedschaft auf Nutzer in Ihrer Organisation zu beschränken. Sie können Nutzer von außerhalb Ihrer Organisation hinzufügen, diese erhalten jedoch möglicherweise nicht die Rollenberechtigungen. Weitere Informationen finden Sie unter Gruppenmitgliedschaft einschränken.

Rollenzuweisung zu Gruppen

Wenn Sie mehr als 500 Rollen in einer OE zuweisen müssen, können Sie einer Sicherheitsgruppe mehrere Mitglieder hinzufügen und der Gruppe eine Rolle zuweisen. Zuweisungen von Gruppenrollen unterliegen einigen zusätzlichen Einschränkungen. Weitere Informationen finden Sie in der Admin-Hilfe.

Zuordnung von Rollen zu Berechtigungen in der Admin-Konsole

Um Nutzern Rollen zuzuweisen, die über die Admin-Konsole auf ihre Berechtigungen zugreifen, müssen möglicherweise bestimmte zusätzliche Berechtigungen gewährt werden. Wenn Sie beispielsweise einem Nutzer die Möglichkeit geben möchten, über die Admin-Konsole andere Nutzer zu erstellen, benötigen Sie nicht nur die Berechtigung USERS_CREATE, sondern auch die Berechtigungen USERS_UPDATE und ORGANIZATION_UNITS_RETRIEVE. In der folgenden Tabelle werden die Funktionen der Admin-Konsole den erforderlichen Berechtigungen für die Verwaltung von Nutzern und Organisationseinheiten zugeordnet.

Funktionen der Admin-Konsole	Erforderliche Berechtigungen
Organisationseinheiten – Lesen	`ORGANIZATION_UNITS_RETRIEVE`
Organisationseinheiten – Erstellen	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_CREATE`
Organisationseinheiten – Aktualisierung	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_UPDATE`
Organisationseinheiten – löschen	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
Organisationseinheiten	`ORGANIZATION_UNITS_ALL`
Nutzer – Gelesen	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Erstellen	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Aktualisierung	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Nutzer verschieben	`USERS_MOVE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Nutzer umbenennen	`USERS_ALIAS` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Passwort zurücksetzen	`USERS_RESET_PASSWORD` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Passwortänderung erzwingen	`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Aliasse hinzufügen/entfernen	`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Nutzer sperren	`USERS_SUSPEND` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
GRUPPEN	`GROUPS_ALL`
Sicherheit – Verwaltung der Nutzersicherheit	`USER_SECURITY_ALL` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`

Anwendungsbeispiele

Hinweis

Führen Sie die Schritte zur Authentifizierung und Autorisierung für Google Workspace aus.

Liste der Domainberechtigungen abrufen

Mit der Methode privileges.list() können Sie eine paginierte Liste der unterstützten Berechtigungen in Ihrer Domain abrufen.

Wenn Sie Administrator sind, der Berechtigungen in Ihrer eigenen Domain erhält, verwenden Sie my_customer als Kundennummer.
Wenn Sie als Reseller Berechtigungen für einen Ihrer Kunden erhalten, verwenden Sie die Kundennummer, die vom Vorgang Nutzer abrufen zurückgegeben wird.

Anfragen

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Antwort

Bei einer erfolgreichen Antwort wird der HTTP 200-Statuscode zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die in der Domain unterstützten Berechtigungen zurückgegeben:

{
  "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
        }
      ]
    },
    ...
  ]
}

Vorhandene Rollen abrufen

Wenn Sie eine Liste der vorhandenen Rollen abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein.

Wenn Sie als Administrator Rollen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kundennummer.
Wenn Sie als Reseller Rollen für einen Kunden abrufen, verwenden Sie die Kundennummer, die Sie mit dem Vorgang Nutzer abrufen erhalten haben.

Anfragen

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die in der Domain vorhandenen Rollen zurückgegeben:

{
  "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
    },
    ...
  ]
}

Alle Rollenzuweisungen auflisten

Mit der Methode roleAssignments.list() können Sie eine paginierte Liste aller direkten Rollenzuweisungen abrufen. Wenn der Parameter userKey festgelegt ist, gibt die API möglicherweise leere Ergebnisse mit einem Seitentoken zurück. Sie sollten mit dem Seitenumbruch fortfahren, bis kein Seitentoken mehr zurückgegeben wird.

Wenn Sie Administrator sind und Rollenzuweisungen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kundennummer.
Wenn Sie als Reseller Rollenzuweisungen für einen Ihrer Kunden erhalten, verwenden Sie die Kundennummer, die vom Vorgang Nutzer abrufen zurückgegeben wird.

Anfragen

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort alle Rollen zurückgegeben, die in der Domain zugewiesen sind:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Alle indirekten Rollenzuweisungen auflisten

Mit der Methode roleAssignments.list() können Sie eine paginierte Liste aller Rollenzuweisungen abrufen, einschließlich der Rollen, die einem Nutzer aufgrund der Gruppen, denen er angehört, indirekt zugewiesen werden.

Die API gibt möglicherweise leere Ergebnisse mit einem Seitentoken zurück. Sie sollten mit dem Seitenumbruch fortfahren, bis kein Seitentoken zurückgegeben wird.

Wenn Sie Administrator sind und Rollenzuweisungen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kundennummer.
Wenn Sie als Reseller Rollenzuweisungen für einen Ihrer Kunden erhalten, verwenden Sie die Kundennummer, die vom Vorgang Nutzer abrufen zurückgegeben wird.
Ersetzen Sie USER_KEY durch einen Wert, der den Nutzer in der API-Anfrage identifiziert. Weitere Informationen finden Sie unter users.get.

Anfragen

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort alle in der Domain zugewiesenen Rollen zurückgegeben und es wird angegeben, ob assigneeType den Wert user oder group hat:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Rolle erstellen

Verwenden Sie die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um eine neue Rolle zu erstellen. Fügen Sie für jede Berechtigung, die mit dieser Rolle gewährt werden soll, eine privilegeName und eine serviceId hinzu. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

Anfragen

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

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Attribute für die neue Rolle zurückgegeben:

{
  "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"
    }
  ]
}

Rollenzuweisung erstellen

Verwenden Sie zum Zuweisen einer Rolle die folgende POST-Methode und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein.

Wenn Sie einem Nutzer die Rolle zuweisen möchten, fügen Sie einen JSON-Text mit dem user_id des Nutzers hinzu, den Sie aus users.get(), roleId (wie unter Vorhandene Rollen abrufen) und scope_type beschrieben erhalten.
Wenn Sie die Rolle einem Dienstkonto zuweisen möchten, fügen Sie einen JSON-Text mit der unique_id des Dienstkontos (wie in Identity and Access Management (IAM) definiert), dem roleId (wie unter Vorhandene Rollen abrufen) und dem scope_type beschrieben hinzu.
Wenn Sie die Rolle einer Gruppe zuweisen möchten, fügen Sie einen JSON-Text mit dem group_id der Gruppe aus groups.get(), dem roleId (wie unter Vorhandene Rollen abrufen) und scope_type beschrieben hinzu.

Anfragen

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Attribute für die neue Rollenzuweisung zurückgegeben:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Rollenzuweisung mit Bedingungen erstellen

Sie können Rollen zuweisen, um Aktionen auszuführen, die bestimmte Bedingungen erfüllen. Derzeit werden nur zwei Bedingungen unterstützt:

Gilt nur für Sicherheitsgruppen
Nicht zutreffend für Sicherheitsgruppen

Wenn condition festgelegt ist, wird sie nur wirksam, wenn die Bedingung auf die Ressource erfüllt ist. Wenn condition leer ist, wird die Rolle (roleId) bedingungslos auf den Akteur (assignedTo) im Bereich (scopeType) angewendet.

Wenn du einem Nutzer eine Rolle zuweisen möchtest, verwende die folgende POST-Methode und füge die unter Anfragen autorisieren beschriebene Autorisierung ein.

Fügen Sie einen JSON-Text mit dem user_id des Nutzers hinzu, den Sie über users.get(), dem roleId wie unter Vorhandene Rollen abrufen und dem condition abrufen können. Die beiden Bedingungsstrings müssen wie unten gezeigt verwendet werden und funktionieren nur mit den vordefinierten Administratorrollen „Gruppenbearbeiter“ und „Gruppenleser“. Diese Bedingungen entsprechen der Syntax von Cloud IAM-Bedingungen.

Anfragen

Gilt nur für Sicherheitsgruppen

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

Nicht zutreffend für Sicherheitsgruppen

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

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Attribute für die neue Rollenzuweisung zurückgegeben:

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