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 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, consultez users.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.

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