Rollen verwalten

Mit der Directory API können Sie Role-Based Access Control (RBAC, rollenbasierte Zugriffssteuerung) , um den Zugriff auf Funktionen in Ihrer Google Workspace-Domain zu verwalten. Sie können Benutzerdefinierte Rollen mit Berechtigungen, um den Administratorzugriff spezifischer einzuschränken als die vordefinierten Rollen von Google Workspace. Sie können Rollen für Nutzer oder Sicherheitsgruppen. In diesem Leitfaden erfahren Sie, wie Sie grundlegende rollenbezogene Aufgaben.

Im Folgenden finden Sie eine Liste häufig auftretender Begriffe, die von der Directory API mit in Bezug auf RBAC in Google Workspace:

Berechtigung
Die Berechtigung zum Ausführen einer Aufgabe oder eines Vorgangs in einem Google Workspace-Domain. Vertreten durch die Privilege. Es sind keine persistenten Daten, die mit dieser Ressource verknüpft sind.
Rolle
Eine Sammlung von Berechtigungen, durch die Entitäten mit dieser Rolle die Berechtigung die Fähigkeit, bestimmte Aufgaben oder Vorgänge auszuführen. Vertreten durch die Role.
Rollenzuweisung
Der Datensatz einer bestimmten Rolle, die einem Nutzer oder einer Gruppe zugewiesen wurde. Vertreten durch RoleAssignment .
Sicherheitsgruppe
Eine Art von Cloud Identity-Gruppe mit dem der Zugriff auf Unternehmensprofile Ressourcen. Sicherheitsgruppen können sowohl einzelne Nutzer als auch Gruppen enthalten.

Beschränkungen für Rollen- und Rollenzuweisungen

Sie können nur eine begrenzte Anzahl von benutzerdefinierten Rollen oder Rollenzuweisungen erstellen. konsolidieren oder entfernen, um das Limit nicht zu überschreiten, Limit Für Rollen und Rollenzuweisungen gelten die folgenden Beschränkungen:

  • Sie können bis zu 750 benutzerdefinierte Rollen für Ihre gesamte Organisation erstellen.
  • Sie können bis zu 1.000 Rollenzuweisungen pro Organisationseinheit (OE), wobei die Stammorganisation als Einheit angesehen wird. Sie können beispielsweise 600 Rollen in der Stammorganisation und 700 Rollen zuweisen. innerhalb einer anderen von Ihnen definierten OE, z. B. einer Abteilung eines Unternehmens. Alle vordefinierten Administratorrollen in Google Workspace sind standardmäßig auf die organisationsweiten Geltungsbereichs. Weitere Informationen über Beschränkungen der Berechtigungen die auf OE-Ebene zugewiesen werden kann.

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

  • Sie können jede Rolle außer Super Admin zuweisen.
  • Sie können Gruppen insgesamt bis zu 250 Rollenzuweisungen in der Organisationseinheit zuweisen und zwar in jeder OE.
  • Die Gruppe muss eine Sicherheitsgruppe in Ihrer Organisation sein.
  • Wir empfehlen, die Gruppenmitgliedschaft auf Nutzer in Ihrer Organisation zu beschränken. Ich können Nutzer von außerhalb Ihrer Organisation hinzufügen, erhält möglicherweise keine 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 mehrere Mitglieder zu einer Sicherheitsgruppe und weisen der Gruppe eine Rolle zu. Gruppenrolle Zuweisungen haben einige zusätzliche Einschränkungen. Weitere Informationen finden Sie in der Weitere Informationen finden Sie in der Admin-Hilfe.

Zuordnung von Rollen zu Berechtigungen in der Admin-Konsole

So weisen Sie Nutzern, die über die Admin-Konsole müssen möglicherweise bestimmte zusätzliche Berechtigungen gewährt wird. Um einem Nutzer beispielsweise die Möglichkeit zu geben, über in der Admin-Konsole, nicht nur die Berechtigung USERS_CREATE erforderlich, aber auch USERS_UPDATE und ORGANIZATION_UNITS_RETRIEVE Berechtigungen. Die folgende Tabelle stellt die Admin-Konsole dar: Funktionalität über die erforderlichen Berechtigungen für die Nutzerverwaltung und Organisationseinheiten.

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 – Lesen 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

Schließen Sie die Authentifizierung und Autorisierung für Google Workspace.

Liste der Domainberechtigungen abrufen

Eine paginierte Liste der unterstützten Berechtigungen für Ihre Domain erhalten Sie über den privileges.list() .

  • Wenn Sie ein Administrator sind, der Berechtigungen für Ihre eigene Domain hat, verwenden Sie my_customer als Kundennummer.

  • Wenn Sie Reseller sind und Berechtigungen für einen Ihrer Kunden erhalten, Verwenden Sie die Kundennummer, die vom Abruf eines user (Nutzervorgang)

Anfrage

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

Antwort

Eine erfolgreiche Antwort gibt den Status HTTP 200 zurück. Code hinzu. Zusammen mit den Statuscode zurückgegeben, werden 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

Verwenden Sie die folgende GET-Anfrage und fügen Sie den Parameter wie unter Autorisieren -Anfragen.

  • Wenn Sie Administrator sind und Rollen in Ihrer eigenen Domain erhalten, verwenden Sie my_customer als Kundennummer.

  • Wenn Sie als Reseller Rollen für einen Kunden erhalten, verwenden Sie die Kundennummer, die mithilfe der Methode Retrieve a user (Nutzervorgang)

Anfrage

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

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den Statuscode zurückgegeben, 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

Um eine paginierte Liste aller direkten Rollenzuweisungen zu erhalten, verwenden Sie die roleAssignments.list() . Die API gibt möglicherweise leere Ergebnisse mit einem Seitentoken zurück, wenn der userKey festgelegt ist. Fahren Sie mit der Paginierung fort, bis kein Seitentoken mehr zurückgegeben.

  • 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 Kundennummer, die vom Abruf eines user (Nutzervorgang)

Anfrage

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

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den Statuscode zurückgegeben, 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

So rufen Sie eine paginierte Liste aller Rollenzuweisungen ab, einschließlich der indirekten Rollenzuweisungen: die einem Nutzer aufgrund der Gruppen zugewiesen sind, zu denen er gehört, verwenden Sie roleAssignments.list() .

Die API gibt möglicherweise leere Ergebnisse mit einem Seitentoken zurück. Sie sollten fortfahren Paginierung, bis kein Seitentoken mehr 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 Kundennummer, die vom Abruf eines user (Nutzervorgang)

  • Ersetzen Sie USER_KEY durch einen Wert, der den in der API-Anfrage angeben. 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

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den Statuscode sind, gibt die Antwort alle Rollen zurück, die in der Domain zugewiesen wurden, und ob assigneeType ist user oder group:

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

Eine Rolle erstellen

Verwenden Sie zum Erstellen einer neuen Rolle die folgende POST-Anfrage und fügen Sie den wie unter Autorisieren -Anfragen. Fügen Sie für jede Berechtigung, die aktualisiert werden soll, eine privilegeName und eine serviceId hinzu. mit dieser Rolle gewährt wird. Die Anfrage- und Antwortattribute 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

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den gibt die Antwort die Attribute für die neue Rolle zurück:

{
  "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 Autorisierung ein beschrieben in Anfragen autorisieren.

Anfrage

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

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

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den Statuscode enthält die Antwort die Attribute für die neue Rollenzuweisung:

{
  "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 dies nur wirksam, wenn die Ressource auf die zugegriffen wird, die Bedingung erfüllt. Wenn condition leer ist, lautet die Rolle (roleId) auf den Akteur (assignedTo) im Umfang (scopeType) ohne Bedingungen angewendet.

Um einem Nutzer eine Rolle zuzuweisen, verwende die folgende POST-Methode und füge den Autorisierung gemäß den Autorisieren -Anfragen.

Fügen Sie einen JSON-Text mit dem user_id des Nutzers hinzu, den Sie über users.get(), der roleId als die unter Vorhandene Rollen abrufen und condition beschrieben sind. Die müssen zwei Bedingungsstrings wie unten gezeigt wörtlich verwendet werden funktionieren nur mit dem Google Groups-Editor und dem Google Groups-Leser Vordefinierte Administratorrollen. Diese Bedingungen gelten Syntax von Cloud IAM-Bedingungen:

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

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück. Code angeben. Zusammen mit den Statuscode enthält die Antwort die Attribute für die neue Rollenzuweisung:

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