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 plus précisément 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 de 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 permet 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 particulier 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 des rôles et de l'attribution de rôles

Vous ne pouvez créer qu'un nombre limité de rôles personnalisés ou d'attributions de rôles. Si vous approchez de la limite, consolidez-les ou supprimez-les pour rester en dessous. Les rôles et les attributions de rôles 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ôles 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 l'étendue au niveau de l'organisation. En savoir plus sur les limites des droits pouvant être attribués au niveau des 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. Les attributions de rôles de groupe sont soumises à certaines 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, vous devrez peut-être accorder certains droits supplémentaires. Par exemple, pour autoriser un utilisateur à créer d'autres utilisateurs via la console d'administration, il est nécessaire d'accorder non seulement le droit USERS_CREATE, mais aussi les droits USERS_UPDATE et ORGANIZATION_UNITS_RETRIEVE. Le tableau suivant met en correspondance les fonctionnalités de la console d'administration avec les autorisations requises 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 - Lire	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 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 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 la procédure d'authentification et d'autorisation pour Google Workspace.

Obtenir la liste des droits de 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 disposant de droits dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes un revendeur qui obtient des droits pour l'un de vos clients, utilisez l'ID client renvoyé par l'opération Retrieve a user (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 réussie 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 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 ID client.

• Si vous êtes 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 Retrieve a user (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. En plus du code d'état, la réponse renvoie les rôles existants 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 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 recevez des attributions de rôles dans votre propre domaine, utilisez my_customer comme ID client.

• Si vous êtes revendeur et que vous recevez des attributions de rôles pour l'un de vos clients, utilisez l'ID client renvoyé par l'opération Retrieve a user (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",
}

Répertorier toutes les attributions de rôles indirectes

Pour obtenir une 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. Vous devez continuer 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 ID client.

• Si vous êtes revendeur et que vous recevez des attributions de rôles pour l'un de vos clients, utilisez l'ID client renvoyé par l'opération Retrieve a user (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 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 qui doit être accordé 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. En plus du 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 de users.get(), du roleId (comme décrit dans la section Obtenir des rôles existants) et du scope_type.

• Pour attribuer le rôle à un compte de service, ajoutez un corps JSON avec le unique_id du compte de service (défini dans la section Gestion de l'identité et des accès (IAM)), le roleId (comme décrit dans la section Obtenir des 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(), du roleId (comme décrit dans la section Obtenir des rôles existants) et du 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 l'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 des conditions n'est pas encore respectée dans la console d'administration.

Vous pouvez accorder des rôles pour effectuer des actions qui remplissent certaines conditions. 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 on accède remplit la condition. Si condition est vide, le rôle (roleId) est appliqué à l'acteur (assignedTo) au niveau du champ d'application (scopeType) sans condition.

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 des rôles existants et le condition. Les deux chaînes de conditions 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 de groupes 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 l'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'"
}