Gérer les rôles

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 avec des droits pour limiter l'accès des administrateurs de manière plus spécifique que les rôles prédéfinis fournis avec Google Workspace. Vous pouvez attribuer des rôles à des utilisateurs ou à des 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 courants utilisés par l'API Directory concernant le 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 permettent aux entités disposant de ce rôle d'effectuer certaines tâches ou opérations. Représenté par la ressource Role.

Attribution de rôle

 Enregistrement d'un rôle spécifique 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 des utilisateurs individuels et des groupes.

Limites concernant les rôles et leur attribution

Vous ne pouvez créer qu'un nombre limité de rôles ou d'attributions de rôles personnalisés. Si vous approchez de cette limite, regroupez-les ou supprimez-les pour ne pas la dépasser. Les rôles et les attributions de rôle sont soumis aux limites suivantes :

• Vous pouvez créer jusqu'à 750 rôles personnalisés pour l'ensemble de votre organisation.
• Vous pouvez créer jusqu'à 1 000 attributions de rôle par unité organisationnelle (UO), l'organisation racine étant considérée comme une unité. Par exemple, vous pouvez attribuer 600 rôles dans l'organisation racine et 700 rôles dans une autre UO que vous avez définie, comme un service d'une entreprise. Tous les rôles d'administrateur prédéfinis Google Workspace sont définis par défaut sur le champ d'application à l'ensemble de l'organisation. En savoir plus sur les limites des droits pouvant être attribués au niveau de l'UO

Les rôles et l'attribution de rôles sont soumis aux limites suivantes pour les groupes :

• Vous pouvez attribuer n'importe quel rôle, à l'exception du rôle de super-administrateur.
• Vous pouvez attribuer des rôles à 250 groupes au total à l'échelle de l'UO globale et de chaque UO.
• Le groupe doit être un groupe de sécurité de votre organisation.
• Nous vous recommandons de limiter l'adhésion aux groupes aux utilisateurs de votre organisation. Vous pouvez ajouter des utilisateurs extérieurs à votre organisation, mais ils risquent de ne pas obtenir les droits associés au rôle. Pour en savoir plus, consultez Restreindre les adhésions à un groupe. ### Attribution de rôles à des groupes

Si vous devez attribuer plus de 1 000 rôles dans une UO, vous pouvez ajouter plusieurs membres à un groupe de sécurité et attribuer un rôle au groupe. L'attribution de rôles dans un groupe est soumise à des restrictions supplémentaires. Pour en savoir plus, consultez le Centre d'aide pour les administrateurs.

Remarque : Pour créer des groupes de sécurité, vous devez utiliser l'API Cloud Identity. Vous ne pouvez pas utiliser l'API Directory. Pour en savoir plus, consultez la documentation sur les groupes de sécurité.

Mappage des rôles et des droits dans la console d'administration Google

Pour attribuer des rôles aux utilisateurs qui accèdent à leurs droits via la console d'administration, il peut être nécessaire d'accorder certains droits supplémentaires. Par exemple, pour qu'un utilisateur puisse créer d'autres utilisateurs dans la console d'administration, il doit disposer des droits d'accès USERS_CREATE, USERS_UPDATE et ORGANIZATION_UNITS_RETRIEVE. Le tableau suivant met en correspondance les fonctionnalités de la console d'administration avec les droits d'accès requis pour gérer les utilisateurs et les unités organisationnelles.

Fonctionnalités de la console d'administration	Droits requis
Unités organisationnelles : lecture	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 > Mettre à jour	USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Utilisateurs : déplacer des utilisateurs	USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utilisateurs : renommer des utilisateurs	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 utilisateurs	USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GROUPES	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

Avant d'exécuter les exemples de ce guide, configurez l'authentification et l'autorisation.

1. Configurez l'écran de consentement OAuth.

2. Créez des identifiants d'accès.

Obtenir la liste des droits d'accès au domaine

Pour obtenir une liste paginée des droits d'accès acceptés dans votre domaine, utilisez la méthode privileges.list().

• Si vous êtes un administrateur qui obtient des droits dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes un revendeur et que vous obtenez des droits d'accès pour l'un de vos clients, utilisez l'ID 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

Une réponse ayant abouti renvoie un code d'état HTTP 200. En plus du code d'état, la réponse renvoie les droits d'accès acceptés dans 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 Autoriser les requêtes.

• Si vous êtes administrateur et que vous souhaitez obtenir des rôles dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes un revendeur et que vous obtenez des rôles pour un client, utilisez l'ID 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

Une réponse réussie renvoie un code d'état HTTP 200. Outre 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
    },
    ...
  ]
}

Lister toutes les attributions de rôle

Pour obtenir une 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. Vous devez continuer la pagination jusqu'à ce qu'aucun jeton de page ne soit renvoyé.

• Si vous êtes administrateur et que vous récupérez des attributions de rôle dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes un revendeur et que vous souhaitez obtenir des attributions de rôle pour l'un de vos clients, utilisez l'ID 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

Une réponse réussie renvoie un code d'état HTTP 200. En plus du 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",
}

Lister toutes les attributions de rôle indirectes

Pour obtenir une liste paginée de toutes les attributions de rôle, 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. Vous devez continuer la pagination jusqu'à ce qu'aucun jeton de page ne soit renvoyé.

• Si vous êtes administrateur et que vous récupérez des attributions de rôle dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes un revendeur et que vous souhaitez obtenir des attributions de rôle pour l'un de vos clients, utilisez l'ID 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, consultez users.get.

Requête

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Réponse

Une réponse réussie renvoie un code d'état HTTP 200. En plus du 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 Autoriser les requêtes. Ajoutez un privilegeName et un serviceId pour chaque droit à accorder avec ce rôle. Pour en savoir plus sur les propriétés de requête et de 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

Une réponse réussie renvoie un code d'état HTTP 200. Outre le code d'état, la réponse affiche 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 Autoriser les requêtes.

• Pour attribuer le rôle à un utilisateur, ajoutez un corps JSON avec l'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 scope_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)), le roleId (tel que décrit dans Obtenir les rôles existants) et le scope_type.

• Pour attribuer le rôle à un groupe, ajoutez un corps JSON avec le group_id du groupe, que vous pouvez obtenir à partir de groups.get(), le roleId (comme décrit dans Obtenir les rôles existants) et le scope_type.

Requête

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

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

Réponse

Une réponse réussie renvoie un code d'état HTTP 200. En plus du 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

Remarque : Cette fonctionnalité n'est disponible que dans la version v1.1beta1 de l'API, et uniquement pour les clients Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus et Cloud Identity Premium. Aucune configuration supplémentaire n'est requise pour utiliser cette fonctionnalité. L'attribution de rôles avec conditions n'est pas encore respectée dans la console d'administration.

Vous pouvez accorder des rôles pour effectuer des actions qui remplissent des conditions spécifiques. Actuellement, seules deux conditions sont acceptées :

• Uniquement applicable aux groupes de sécurité
• Non applicable aux groupes de sécurité

Lorsque condition est défini, il ne prend effet que lorsque la ressource à laquelle l'utilisateur tente d'accéder 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 Autoriser les requêtes.

Ajoutez un corps JSON avec l'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. Elles ne fonctionnent qu'avec les rôles d'administrateur prédéfinis de l'éditeur et du 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

Une réponse réussie renvoie un code d'état HTTP 200. En plus du 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'"
}