Diese Seite wurde von der Cloud Translation API übersetzt.

Rollen verwalten

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

Im Folgenden finden Sie eine Liste gängiger Begriffe, die in der Directory API im Zusammenhang mit der rollenbasierten Zugriffssteuerung 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 nichtflüchtigen Daten verknüpft.
Rolle: Eine Reihe 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 Eintrag einer bestimmten Rolle, die dem Nutzer oder der Gruppe zugewiesen wurde. Wird durch die RoleAssignment-Ressource dargestellt.
Sicherheitsgruppe: Eine Art von Cloud Identity-Gruppe, mit der der Zugriff auf organisatorische Ressourcen gesteuert wird. Sicherheitsgruppen können sowohl einzelne Nutzer als auch Gruppen enthalten.

Limits für Rollen und Rollenzuweisungen

Sie können nur eine begrenzte Anzahl von benutzerdefinierten Rollen oder Rollenzuweisungen erstellen. Wenn Sie das Limit erreichen, sollten Sie sie zusammenführen oder entfernen, um unter dem Limit zu bleiben. Für Rollen und Rollenzuweisungen gelten die folgenden Limits:

Sie können bis zu 750 benutzerdefinierte Rollen für die gesamte Organisation erstellen.
Sie können pro Organisationseinheit (OE) bis zu 1.000 Rollenzuweisungen erstellen. Die Stammorganisation gilt als OE. Sie können beispielsweise 600 Rollen in der übergeordneten Organisation und 700 Rollen in einer anderen von Ihnen definierten OU zuweisen, z. B. einer Abteilung eines Unternehmens. Alle vordefinierten Administratorrollen in Google Workspace haben standardmäßig den organisationsweiten Umfang. Weitere Informationen zu den Berechtigungen, die auf OU-Ebene zugewiesen werden können

Für Gruppen gelten die folgenden Einschränkungen für Rollen und Rollenzuweisungen:

Sie können eine beliebige Rolle außer Super Admin zuweisen.
Sie können Gruppen insgesamt auf OE-Ebene und innerhalb der einzelnen OEs 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 außerhalb Ihrer Organisation hinzufügen, diese erhalten jedoch möglicherweise nicht die Rollenberechtigungen. Weitere Informationen finden Sie unter Gruppenmitgliedschaft einschränken. ### Rollenzuweisung für Gruppen

Wenn Sie mehr als 1.000 Rollen in einer OU zuweisen möchten, können Sie einer Sicherheitsgruppe mehrere Mitglieder hinzufügen und der Gruppe eine Rolle zuweisen. Die Zuweisung von Gruppenrollen unterliegt einigen zusätzlichen Einschränkungen. Weitere Informationen finden Sie in der Admin-Hilfe.

Zuordnung von Rollen zu Berechtigungen in der Admin-Konsole

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

Funktionen in der Admin-Konsole	Erforderliche Berechtigungen
Organisationseinheiten – Lesen	`ORGANIZATION_UNITS_RETRIEVE`
Organisationseinheiten – Erstellen	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_CREATE`
Organisationseinheiten – Aktualisieren	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_UPDATE`
Organisationseinheiten – Löschen	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
Organisationseinheiten	`ORGANIZATION_UNITS_ALL`
Nutzer – Lesen	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Erstellen	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Nutzer – Aktualisieren	`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() erhalten Sie eine paginaierte Liste der unterstützten Berechtigungen in Ihrer Domain.

Wenn Sie als Administrator Berechtigungen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kunden-ID.
Wenn Sie als Reseller Berechtigungen für einen Ihrer Kunden erhalten, verwenden Sie die Kunden-ID, die von der Aktion Retrieve a user (Nutzer abrufen) zurückgegeben wird.

Anfrage

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

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 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 in Anfragen autorisieren beschriebene Autorisierung ein.

Wenn Sie als Administrator Rollen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kunden-ID.
Wenn Sie als Reseller Rollen für einen Kunden abrufen, verwenden Sie die Kunden-ID, die Sie mit der Aktion Retrieve a user (Nutzer abrufen) erhalten haben.

Anfrage

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 Rollen zurückgegeben, die in der Domain vorhanden sind:

{
  "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 paginaierte Liste aller direkten Rollenzuweisungen abrufen. Wenn der Parameter userKey festgelegt ist, gibt die API möglicherweise leere Ergebnisse mit einem Seitentoken zurück. Du solltest die Paginierung so lange fortsetzen, bis kein Seitentoken zurückgegeben wird.

Wenn Sie als Administrator 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 Kunden-ID, die von der Aktion Retrieve a user (Nutzer abrufen) zurückgegeben wird.

Anfrage

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 in der Domain zugewiesenen Rollen zurückgegeben:

{
  "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 paginaierte Liste aller Rollenzuweisungen abrufen, einschließlich derjenigen, die einem Nutzer aufgrund der Gruppen, denen er angehört, indirekt zugewiesen wurden.

Die API gibt möglicherweise leere Ergebnisse mit einem Seitentoken zurück. Sie sollten die Paginierung so lange fortsetzen, bis kein Seitentoken zurückgegeben wird.

Wenn Sie als Administrator 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 Kunden-ID, die von der Aktion Retrieve a user (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.

Anfrage

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 und ob assigneeType user oder group ist, zurückgegeben:

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

Eine Rolle erstellen

Wenn Sie eine neue Rolle erstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. 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 Antworteigenschaften finden Sie in der API-Referenz.

Anfrage

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 Eigenschaften 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

Wenn Sie eine Rolle zuweisen möchten, verwenden Sie die folgende POST-Methode und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein.

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

Anfrage

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 Eigenschaften 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 gewähren, um Aktionen auszuführen, die bestimmte Bedingungen erfüllen. Derzeit werden nur zwei Bedingungen unterstützt:

Nur für Sicherheitsgruppen
Nicht zutreffend für Sicherheitsgruppen

Wenn condition festgelegt ist, wird die Regel nur angewendet, wenn die Ressource, auf die zugegriffen wird, die Bedingung erfüllt. Wenn condition leer ist, wird die Rolle (roleId) dem Akteur (assignedTo) im Gültigkeitsbereich (scopeType) ohne Bedingungen angewendet.

Wenn Sie einem Nutzer eine Rolle zuweisen möchten, verwenden Sie die folgende POST-Methode und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein.

Fügen Sie einen JSON-Text mit der user_id des Nutzers hinzu, die Sie mit users.get() abrufen können, die roleId wie unter Vorhandene Rollen abrufen beschrieben und die condition. Die beiden Bedingungsstrings müssen genau wie unten gezeigt verwendet werden und funktionieren nur mit den vordefinierten Administratorrollen für den Gruppen-Editor und den Gruppenleser. Diese Bedingungen folgen der Syntax von Cloud IAM-Bedingungen.

Anfrage

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