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 unterusers.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.
Fügen Sie einen JSON-Text mit der
user_id
des Nutzers hinzu, um die Rolle einem Nutzer zuzuweisen. Das können Sie vomusers.get()
abrufen, dieroleId
(wie in Vorhandene Rollen abrufen) und diescope_type
.Um die Rolle einem Dienstkonto zuzuweisen, fügen Sie einen JSON-Text mit dem
unique_id
des Dienstkontos (wie in den Identity and Access Management (IAM)),roleId
(wie in Vorhandene Rollen abrufen) und denscope_type
.Um die Rolle einer Gruppe zuzuweisen, fügen Sie einen JSON-Text mit dem
group_id
des die Sie auf der Seitegroups.get()
,roleId
(wie in Vorhandene Rollen abrufen), undscope_type
.
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'"
}