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, die in Google Workspace enthalten sind. Sie können Nutzern oder Sicherheitsgruppen Rollen zuweisen. In dieser Anleitung wird beschrieben, wie Sie einige grundlegende rollenbezogene Aufgaben ausführen.

Im Folgenden finden Sie eine Liste mit häufig verwendeten Begriffen, die in 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 nichtflüchtigen Daten verknüpft.
Rolle: Eine Sammlung von Berechtigungen, die Entitäten mit dieser Rolle die Möglichkeit gibt, bestimmte Aufgaben oder Vorgänge auszuführen. Wird durch die Ressource Role dargestellt.
Rollenzuweisung: Der Datensatz einer bestimmten Rolle, die dem Nutzer oder der Gruppe zugewiesen wurde. Wird durch die RoleAssignment-Ressource dargestellt.
Sicherheitsgruppe: Eine Art von Cloud Identity-Gruppe, die zur Steuerung des Zugriffs auf Organisationsressourcen verwendet 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, sollten Sie sie zusammenfassen oder entfernen, um das Limit nicht zu überschreiten. 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 wird dabei als Einheit betrachtet. Sie können beispielsweise 600 Rollen in der Stammorganisation und 700 Rollen in einer anderen Organisationseinheit zuweisen, die Sie definiert haben, z. B. eine Abteilung eines Unternehmens. Für alle vordefinierten Administratorrollen in Google Workspace wird standardmäßig der organisationsweite Bereich verwendet. Weitere Informationen zu den Berechtigungen, die auf Organisationseinheitenebene zugewiesen werden können

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

Sie können eine beliebige Rolle außer „Super Admin“ zuweisen.
Sie können Gruppen insgesamt auf Organisationseinheitsebene und innerhalb der einzelnen Organisationseinheiten 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 an Gruppen

Wenn Sie mehr als 1.000 Rollen in einer Organisationseinheit zuweisen müssen, können Sie einer Sicherheitsgruppe mehrere Mitglieder hinzufügen und der Gruppe eine Rolle zuweisen. Für die Zuweisung von Gruppenrollen gelten einige zusätzliche Einschränkungen. Weitere Informationen finden Sie in der Admin-Hilfe.

Zuordnung von Rollen zu Berechtigungen in der Admin-Konsole

Wenn Sie Rollen für Nutzer zuweisen möchten, die über die Admin-Konsole auf ihre Berechtigungen zugreifen, müssen Sie möglicherweise bestimmte zusätzliche Berechtigungen gewähren. Wenn Sie einem Nutzer beispielsweise die Möglichkeit geben möchten, andere Nutzer über die Admin-Konsole zu erstellen, sind nicht nur die Berechtigung USERS_CREATE, sondern auch die Berechtigungen USERS_UPDATE und ORGANIZATION_UNITS_RETRIEVE erforderlich. In der folgenden Tabelle wird die Funktionalität der Admin-Konsole den erforderlichen Berechtigungen zum Verwalten 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 – 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

Bevor Sie die Beispiele in dieser Anleitung ausführen, müssen Sie die Authentifizierung und Autorisierung einrichten.

Liste der Domainberechtigungen abrufen

Eine paginierte Liste der unterstützten Berechtigungen in Ihrer Domain erhalten Sie mit der Methode privileges.list().

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 Operation 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 abrufen, 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 dem Vorgang 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

Verwenden Sie die Methode roleAssignments.list(), um eine paginierte Liste aller direkten Rollenzuweisungen abzurufen. Die API gibt möglicherweise leere Ergebnisse mit einem Seitentoken zurück, wenn der Parameter userKey festgelegt ist. Sie sollten die Paginierung fortsetzen, bis kein Seitentoken mehr zurückgegeben wird.

Wenn Sie als Administrator Rollenzuweisungen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kunden-ID.
Wenn Sie als Reseller Rollenzuweisungen für einen Ihrer Kunden abrufen, verwenden Sie die Kunden-ID, die vom Vorgang 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

Wenn Sie eine paginierte Liste aller Rollenzuweisungen abrufen möchten, einschließlich der Rollenzuweisungen, die einem Nutzer aufgrund der Gruppen, denen er angehört, indirekt zugewiesen wurden, verwenden Sie die Methode roleAssignments.list().

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

Wenn Sie als Administrator Rollenzuweisungen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kunden-ID.
Wenn Sie als Reseller Rollenzuweisungen für einen Ihrer Kunden abrufen, verwenden Sie die Kunden-ID, 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.

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 Rollen zurückgegeben, die in der Domain zugewiesen sind, und ob assigneeType user oder group ist:

{
  "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, ein privilegeName und ein serviceId hinzu. Informationen zu den Anfrage- und Antwortattributen 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 der neuen 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.

Um einem Nutzer die Rolle zuzuweisen, fügen Sie einen JSON-Text mit der user_id des Nutzers hinzu, die Sie über users.get() abrufen können, der roleId (wie unter Vorhandene Rollen abrufen beschrieben) und der scope_type.
Wenn Sie die Rolle einem Dienstkonto zuweisen möchten, fügen Sie einen JSON-Body mit der unique_id des Dienstkontos (wie in der Identitäts- und Zugriffsverwaltung (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, die Sie unter groups.get() abrufen können, der roleId (wie unter Vorhandene Rollen abrufen beschrieben) und der scope_type.

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

Gilt nur für Sicherheitsgruppen
Nicht auf Sicherheitsgruppen anwendbar

Wenn condition festgelegt ist, wird sie nur wirksam, wenn die Ressource, auf die zugegriffen wird, die Bedingung erfüllt. Wenn condition leer ist, wird die Rolle (roleId) bedingungslos auf den Akteur (assignedTo) im Bereich (scopeType) 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, der roleId, wie unter Vorhandene Rollen abrufen beschrieben, und der condition. Die beiden Bedingungsstrings müssen unverändert wie unten gezeigt verwendet werden und funktionieren nur mit den vordefinierten Administratorrollen „Groups Editor“ und „Groups Reader“. Diese Bedingungen folgen der Cloud IAM-Bedingungssyntax.

Anfrage

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 auf Sicherheitsgruppen anwendbar

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

Rollen verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Rollen- und Rollenzuweisungslimits

Zuordnung von Rollen zu Berechtigungen in der Admin-Konsole

Anwendungsbeispiele

Hinweis

Liste der Domainberechtigungen abrufen

Anfrage

Antwort

Vorhandene Rollen abrufen

Anfrage

Antwort

Alle Rollenzuweisungen auflisten

Anfrage

Antwort

Alle indirekten Rollenzuweisungen auflisten

Anfrage

Antwort

Eine Rolle erstellen

Anfrage

Antwort

Rollenzuweisung erstellen

Anfrage

Antwort

Rollenzuweisung mit Bedingungen erstellen

Anfrage

Gilt nur für Sicherheitsgruppen

Nicht auf Sicherheitsgruppen anwendbar

Antwort

Rollen verwalten