L'API Directory vous permet d'utiliser le contrôle des accès basé sur les rôles (RBAC) pour gérer l'accès aux fonctionnalités de votre domaine Google Workspace. Vous pouvez créer des rôles personnalisés dotés de droits pour limiter l'accès administrateur de façon plus spécifique que les rôles prédéfinis fournis avec Google Workspace. Vous pouvez attribuer des rôles aux utilisateurs ou aux groupes de sécurité. Ce guide explique comment effectuer certaines tâches de base liées aux rôles.
Vous trouverez ci-dessous une liste des termes couramment utilisés par l'API Directory en ce qui concerne le contrôle des accès basé sur les rôles (RBAC) dans Google Workspace:
- Droit
- Autorisation nécessaire pour effectuer une tâche ou une opération dans un domaine Google Workspace. Représenté par la ressource
Privilege
. Aucune donnée persistante n'est associée à cette ressource. - Rôle
- Ensemble de droits qui accorde aux entités dotées de ce rôle la possibilité d'effectuer certaines tâches ou opérations. Représenté par la ressource
Role
. - Attribution des rôles
- Enregistrement d'un rôle donné attribué à l'utilisateur ou au groupe. Représenté par la ressource
RoleAssignment
. - Groupe de sécurité
- Type de groupe Cloud Identity utilisé pour contrôler l'accès aux ressources de l'organisation. Les groupes de sécurité peuvent contenir à la fois des utilisateurs individuels et des groupes.
Limites d'attribution de rôles
Vous ne pouvez créer qu'un nombre limité de rôles personnalisés ou d'attributions de rôles. Par conséquent, si vous vous en approchez, regroupez-les ou supprimez-les pour respecter cette limite. Les limites suivantes s'appliquent aux rôles et aux attributions de rôles:
- Vous pouvez créer jusqu'à 750 rôles personnalisés pour l'ensemble de votre organisation.
- Vous pouvez créer jusqu'à 500 attributions de rôles par unité organisationnelle (UO), l'organisation racine étant considérée comme une unité. Par exemple, vous pouvez attribuer 350 rôles dans l'organisation racine et 400 rôles dans une autre UO que vous avez définie, comme un service d'une entreprise. Par défaut, tous les rôles d'administrateur Google Workspace prédéfinis sont définis au niveau de l'organisation. En savoir plus sur les limites des droits pouvant être attribués au niveau de l'UO.
Les limites suivantes s'appliquent aux rôles et à l'attribution de rôles pour les groupes:
- Vous pouvez attribuer n'importe quel rôle, à l'exception de Super-administrateur.
- Vous pouvez attribuer jusqu'à 250 rôles à des groupes au total dans l'unité organisationnelle globale et dans chaque unité organisationnelle.
- Le groupe doit être un groupe de sécurité de votre organisation.
- Nous vous recommandons de limiter l'appartenance aux groupes aux utilisateurs de votre organisation. Vous pouvez ajouter des utilisateurs externes à votre organisation, mais ils ne disposeront peut-être pas des droits associés au rôle. Pour en savoir plus, consultez Restreindre les adhésions à un groupe.
Attribution de rôles aux groupes
Si vous devez attribuer plus de 500 rôles dans une unité organisationnelle, vous pouvez ajouter plusieurs membres à un groupe de sécurité et attribuer un rôle à ce groupe. Les attributions de rôles au niveau d'un groupe présentent des limites supplémentaires. Pour en savoir plus, consultez le Centre d'aide Administrateur.
Mappage de rôles à droits dans la console d'administration Google
Pour attribuer des rôles à des utilisateurs ayant accès à leurs droits via la console d'administration, il peut être nécessaire d'accorder certains droits supplémentaires. Par exemple, pour autoriser un utilisateur à créer d'autres utilisateurs via la console d'administration, non seulement le droit USERS_CREATE
est requis, mais également les droits USERS_UPDATE
et ORGANIZATION_UNITS_RETRIEVE
. Le tableau suivant met en correspondance les fonctionnalités de la console d'administration avec les droits attribués pour gérer les utilisateurs et les unités organisationnelles.
Fonctionnalités de la console d'administration | Droits requis |
---|---|
Unités organisationnelles - Lire | ORGANIZATION_UNITS_RETRIEVE |
Unités organisationnelles - Créer | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE |
Unités organisationnelles – Mise à jour | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE |
Unités organisationnelles - Supprimer | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE |
Unités organisationnelles | ORGANIZATION_UNITS_ALL |
Utilisateurs – Lecture | USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs - Créer | USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Mise à jour | USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Déplacer des comptes utilisateur | USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Renommer des comptes utilisateur | USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Réinitialiser le mot de passe | USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Forcer le changement de mot de passe | USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Ajouter/Supprimer des alias | USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Utilisateurs – Suspendre des comptes utilisateur | USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
GROUPS | GROUPS_ALL |
Sécurité – Gestion de la sécurité utilisateur | USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Exemples de cas d'utilisation
Avant de commencer
Suivez les étapes d'authentification et d'autorisation pour Google Workspace.
Obtenir la liste des droits du domaine
Pour obtenir la liste paginée des droits compatibles dans votre domaine, utilisez la méthode privileges.list()
.
Si vous êtes un administrateur disposant de droits sur votre propre domaine, utilisez
my_customer
comme numéro client.Si vous êtes un revendeur obtenant des droits pour l'un de vos clients, utilisez le numéro client renvoyé par l'opération Récupérer un utilisateur.
Requête
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
Réponse
Les appels réussis renvoient un code d'état HTTP 200. Avec le code d'état, la réponse renvoie les droits compatibles avec le domaine:
{
"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
}
]
},
...
]
}
Obtenir les rôles existants
Pour obtenir la liste des rôles existants, utilisez la requête GET
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
Si vous êtes administrateur et que vous obtenez des rôles dans votre propre domaine, utilisez
my_customer
comme numéro client.Si vous êtes revendeur et que vous obtenez des rôles pour un client, utilisez le numéro client que vous avez obtenu à l'aide de l'opération Récupérer un utilisateur.
Requête
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie les rôles qui existent dans le domaine:
{
"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
},
...
]
}
Répertorier toutes les attributions de rôles
Pour obtenir la liste paginée de toutes les attributions de rôles directes, utilisez la méthode roleAssignments.list()
. L'API peut renvoyer des résultats vides avec un jeton de page lorsque le paramètre userKey
est défini. Continuez la pagination jusqu'à ce qu'aucun jeton de page ne soit renvoyé.
Si vous êtes administrateur et que vous recevez des attributions de rôles dans votre propre domaine, utilisez
my_customer
comme numéro client.Si, en tant que revendeur, vous obtenez des attributions de rôle pour l'un de vos clients, utilisez le numéro client renvoyé par l'opération Récupérer un utilisateur.
Requête
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie tous les rôles attribués dans le domaine:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"user",
"scopeType:"CUSTOMER",
}
Répertorier toutes les attributions de rôles indirectes
Pour obtenir la liste paginée de toutes les attributions de rôles, y compris celles attribuées indirectement à un utilisateur en raison des groupes auxquels il appartient, utilisez la méthode roleAssignments.list()
.
L'API peut renvoyer des résultats vides avec un jeton de page. Continuez la pagination jusqu'à ce qu'aucun jeton de page ne soit renvoyé.
Si vous êtes administrateur et que vous recevez des attributions de rôles dans votre propre domaine, utilisez
my_customer
comme numéro client.Si, en tant que revendeur, vous obtenez des attributions de rôle pour l'un de vos clients, utilisez le numéro client renvoyé par l'opération Récupérer un utilisateur.
Remplacez
USER_KEY
par une valeur qui identifie l'utilisateur dans la requête API. Pour en savoir plus, consultezusers.get
.
Requête
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie tous les rôles attribués dans le domaine et indique si assigneeType
est user
ou group
:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"group",
"scopeType:"CUSTOMER",
}
Créer un rôle
Pour créer un rôle, utilisez la requête POST
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
Ajoutez privilegeName
et serviceId
pour chaque droit à accorder avec ce rôle. Pour les propriétés de la requête et de la réponse, consultez la documentation de référence de l'API.
Requête
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" } ] }
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie les propriétés du nouveau rôle:
{
"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"
}
]
}
Créer une attribution de rôle
Pour attribuer un rôle, utilisez la méthode POST
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
Pour attribuer le rôle à un utilisateur, ajoutez un corps JSON avec le
user_id
de l'utilisateur, que vous pouvez obtenir à partir deusers.get()
, duroleId
(comme décrit dans Obtenir des rôles existants) et duscope_type
.Pour attribuer le rôle à un compte de service, ajoutez un corps JSON avec le
unique_id
du compte de service (tel que défini dans Identity and Access Management (IAM)), leroleId
(comme décrit dans la section Obtenir les rôles existants) et lescope_type
.Pour attribuer le rôle à un groupe, ajoutez un corps JSON avec le
group_id
du groupe, que vous pouvez obtenir à partir degroups.get()
, duroleId
(comme décrit dans Obtenir des rôles existants) et duscope_type
.
Requête
POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments { "roleId": "3894208461012995", "assignedTo": "100662996240850794412", "scopeType": "CUSTOMER" }
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie les propriétés de la nouvelle attribution de rôle:
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId": "3894208461013211",
"roleId": "3894208461012995",
"assignedTo": "100662996240850794412",
"scopeType": "CUSTOMER"
}
Créer une attribution de rôle avec des conditions
Vous pouvez attribuer des rôles pour effectuer des actions qui remplissent des conditions spécifiques. Actuellement, seules deux conditions sont prises en charge:
- Uniquement applicable aux groupes de sécurité
- Non applicable aux groupes de sécurité
Lorsque condition
est défini, la modification ne prend effet que lorsque la ressource consultée remplit la condition. Si condition
est vide, le rôle (roleId
) est appliqué à l'acteur (assignedTo
) au niveau du champ d'application (scopeType
) de manière inconditionnelle.
Pour attribuer un rôle à un utilisateur, utilisez la méthode POST suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
Ajoutez un corps JSON avec le user_id
de l'utilisateur, que vous pouvez obtenir à partir de users.get(), le roleId
comme décrit dans Obtenir les rôles existants et le condition
. Les deux chaînes de condition doivent être utilisées telles quelles, comme indiqué ci-dessous, et elles ne fonctionnent qu'avec les rôles d'administrateur prédéfinis "Éditeur de groupes" et "Lecteur de groupes".
Ces conditions suivent la syntaxe des conditions Cloud IAM.
Requête
Uniquement applicable aux groupes de sécurité
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'" }
Non applicable aux groupes de sécurité
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'" }
Réponse
Les appels réussis renvoient un code d'état HTTP 200
. Avec le code d'état, la réponse renvoie les propriétés de la nouvelle attribution de rôle:
{
"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'"
}