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 unterusers.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 aususers.get()
,roleId
(wie unter Vorhandene Rollen abrufen) undscope_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), demroleId
(wie unter Vorhandene Rollen abrufen) und demscope_type
beschrieben hinzu.Wenn Sie die Rolle einer Gruppe zuweisen möchten, fügen Sie einen JSON-Text mit dem
group_id
der Gruppe ausgroups.get()
, demroleId
(wie unter Vorhandene Rollen abrufen) undscope_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'"
}