Administrar roles

La API de Directory te permite usar el control de acceso basado en funciones (RBAC) para administrar el acceso a las funciones en tu dominio de Google Workspace. Puedes crear funciones personalizadas con privilegios para limitar el acceso de administrador de manera más específica que las funciones predefinidas que se proporcionan con Google Workspace. Puedes asignar funciones a usuarios o grupos de seguridad. En esta guía, se explica cómo realizar algunas tareas básicas relacionadas con las funciones.

A continuación, se muestra una lista de términos comunes que usa la API de Directory con respecto al RBAC en Google Workspace:

Privilegio
Es el permiso necesario para realizar una tarea o una operación en un dominio de Google Workspace. Representado por el recurso Privilege. No hay datos persistentes asociados con este recurso.
Rol
Es un conjunto de privilegios que otorga a las entidades con esa función la capacidad de realizar determinadas operaciones o tareas. Representado por el recurso Role.
Asignación de roles
Es el registro de un rol específico que se le otorgó al usuario o grupo. Se representa mediante el recurso RoleAssignment.
Grupo de seguridad
Es un tipo de grupo de Cloud Identity que se usa para controlar el acceso a los recursos de la organización. Los grupos de seguridad pueden contener usuarios individuales y grupos.

Límites de roles y asignaciones de roles

Solo puedes crear una cantidad limitada de roles personalizados o asignaciones de roles, por lo que, si te estás acercando al límite, consolidalos o quítalos para no superarlo. Las funciones y las asignaciones de roles tienen los siguientes límites:

  • Puedes crear hasta 750 roles personalizados para toda tu organización.
  • Puedes crear hasta 500 asignaciones de funciones por unidad organizativa (UO), en las que la organización raíz se considera una unidad. Por ejemplo, puedes asignar 350 funciones en la organización raíz y 400 funciones dentro de otra UO que hayas definido, como un departamento de una empresa. Todas las funciones de administrador prediseñadas de Google Workspace tienen el permiso predeterminado de toda la organización. Obtén más información sobre los límites de los privilegios que se pueden asignar a nivel de la UO.

Las funciones y la asignación de roles tienen los siguientes límites para los grupos:

  • Puedes asignar cualquier rol, excepto Administrador avanzado.
  • Puedes tener hasta 250 asignaciones de funciones a grupos en total en la UO general y dentro de cada UO.
  • Debe ser un grupo de seguridad en tu organización.
  • Te recomendamos que restrinjas la pertenencia a un grupo a los usuarios de tu organización. Puedes agregar usuarios que no pertenezcan a tu organización, pero es posible que no obtengan los privilegios de función. Para obtener más información, consulta Cómo restringir la pertenencia a un grupo.

Asignación de roles a grupos

Si necesitas asignar más de 500 funciones en una UO, puedes agregar varios miembros a un grupo de seguridad y asignarle una función al grupo. Las asignaciones de funciones de grupo tienen algunas limitaciones adicionales. Consulta el Centro de ayuda para administradores a fin de obtener información específica.

Asignación de rol a privilegios de la Consola del administrador de Google

Para asignar funciones a los usuarios que acceden a sus privilegios a través de la Consola del administrador, es posible que se deban otorgar ciertos privilegios adicionales. Por ejemplo, para otorgar a un usuario la capacidad de crear otros usuarios a través de la Consola del administrador, no solo se requieren los privilegios USERS_CREATE, sino también los privilegios USERS_UPDATE y ORGANIZATION_UNITS_RETRIEVE. En la siguiente tabla, se asigna la funcionalidad de la Consola del administrador a los otorgamientos de privilegios necesarios para administrar usuarios y unidades organizativas.

Funcionalidad de la Consola del administrador Privilegios necesarios
Unidades organizativas: Lectura ORGANIZATION_UNITS_RETRIEVE
Unidades organizativas - Crear ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Unidades organizativas: Actualización ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Unidades organizativas: Borrar ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Unidades organizativas ORGANIZATION_UNITS_ALL
Usuarios - Lectura USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios - Crear USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Usuarios - Actualización USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: mover usuarios USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Cambio de nombre de los usuarios USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Restablecer contraseña USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Forzar el cambio de contraseña USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Agregar o quitar alias USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Suspender usuarios USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GRUPOS GROUPS_ALL
Seguridad: Administración de la seguridad del usuario USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Ejemplos de casos de uso

Antes de comenzar

Completa los pasos de autenticación y autorización para Google Workspace.

Obtén una lista de privilegios de dominio

Para obtener una lista paginada de privilegios compatibles en tu dominio, usa el método privileges.list().

  • Si eres administrador y obtienes privilegios en tu propio dominio, usa my_customer como ID de cliente.

  • Si eres revendedor y obtienes privilegios para uno de tus clientes, usa el ID de cliente que muestra la operación Recupera un usuario.

Solicitud

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra los privilegios compatibles con el dominio:

{
  "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
        }
      ]
    },
    ...
  ]
}

Obtén roles existentes

Para obtener una lista de los roles existentes, usa la siguiente solicitud GET e incluye la autorización que se describe en Autorizar solicitudes.

  • Si eres administrador y obtienes funciones en tu propio dominio, usa my_customer como ID de cliente.

  • Si eres revendedor que obtiene funciones para un cliente, usa el ID de cliente que obtuviste con la operación Recupera un usuario.

Solicitud

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra las funciones que existen en el dominio:

{
  "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
    },
    ...
  ]
}

Enumera todas las asignaciones de roles

Para obtener una lista paginada de todas las asignaciones de roles directas, usa el método roleAssignments.list(). La API puede mostrar resultados vacíos con un token de página cuando se establece el parámetro userKey. Debes continuar con la paginación hasta que no se muestre ningún token de la página.

  • Si eres administrador que recibe asignaciones de funciones en tu propio dominio, usa my_customer como ID de cliente.

  • Si eres revendedor que recibe asignaciones de funciones para uno de tus clientes, usa el ID de cliente que muestra la operación Recupera un usuario.

Solicitud

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

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra todas las funciones asignadas en el dominio:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Detalla todas las asignaciones de roles indirectas

Para obtener una lista paginada de todas las asignaciones de roles, incluidas las asignadas indirectamente a un usuario debido a los grupos a los que pertenecen, usa el método roleAssignments.list().

Es posible que la API muestre resultados vacíos con un token de página. Debes continuar con la paginación hasta que no se muestre ningún token de la página.

  • Si eres administrador que recibe asignaciones de funciones en tu propio dominio, usa my_customer como ID de cliente.

  • Si eres revendedor que recibe asignaciones de funciones para uno de tus clientes, usa el ID de cliente que muestra la operación Recupera un usuario.

  • Reemplaza USER_KEY por un valor que identifique al usuario en la solicitud a la API. Para obtener más información, consulta users.get.

Solicitud

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

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra todas las funciones asignadas en el dominio y si assigneeType es user o group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Crear una función

Para crear una función nueva, usa la siguiente solicitud POST y, además, incluye la autorización que se describe en Autoriza solicitudes. Agrega privilegeName y serviceId para cada privilegio que se le deba otorgar con esta función. Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de la API.

Solicitud

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

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra las propiedades de la función nueva:

{
  "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"
    }
  ]
}

Cómo crear una asignación de rol

Para asignar una función, usa el siguiente método POST y, además, incluye la autorización que se describe en Autoriza solicitudes.

Solicitud

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

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

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra las propiedades de la nueva asignación de la función:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Cómo crear una asignación de rol con condiciones

Puedes otorgar roles para realizar acciones que cumplan con condiciones específicas. Actualmente, solo se admiten dos condiciones:

  • Solo se aplica a grupos de seguridad
  • No aplicable a grupos de seguridad

Cuando se establece condition, solo tendrá efecto cuando el recurso al que se accede cumple la condición. Si condition está vacío, la función (roleId) se aplica al actor (assignedTo) en el permiso (scopeType) de forma incondicional.

Para asignar una función a un usuario, usa el siguiente método POST y, además, incluye la autorización que se describe en Autoriza solicitudes.

Agrega un cuerpo JSON con el user_id del usuario, que puedes obtener de users.get(), el roleId como se describe en Cómo obtener funciones existentes y el condition. Las dos cadenas de condición se deben usar tal como se muestra a continuación y solo funcionan con las funciones de administrador prediseñadas de Editor y Lector de grupos. Estas condiciones siguen la sintaxis de la condición de Cloud IAM.

Solicitud

Solo se aplica a grupos de seguridad
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'"
}
No aplicable a grupos de seguridad
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'"
}

Respuesta

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra las propiedades de la nueva asignación de la función:

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