Administrar roles

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

La siguiente es una lista de términos comunes que usa la API de Directory con respecto a la RBAC en Google Workspace:

Privilegio

Es el permiso necesario para realizar una tarea o operación en un dominio de Google Workspace. Se representa con el recurso Privilege. No hay datos persistentes asociados con este recurso.

Función

Es un conjunto de privilegios que otorga a las entidades con ese rol la posibilidad de realizar ciertas tareas o operaciones. Se representa con el recurso Role.

Asignación de roles

Es el registro de un rol específico que se le asignó al usuario o grupo. Se representa con el recurso RoleAssignment.

Grupo de seguridad

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 acercas al límite, consúlalas o quítalas para no superarlo. Los roles y las asignaciones de roles tienen los siguientes límites:

• Puedes crear hasta 750 roles personalizados para toda tu organización.
• Puedes crear hasta 1,000 asignaciones de roles por unidad organizativa (UO), en la que la organización raíz se considera una unidad. Por ejemplo, puedes asignar 600 roles en la organización raíz y 700 roles dentro de otra UO que hayas definido, como un departamento de una empresa. Todos los roles de administrador predefinidos de Google Workspace tienen el permiso de acceso a toda la organización de forma predeterminada. Obtén más información sobre los límites de los privilegios que se pueden asignar a nivel de la UO.

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

• Puedes asignar cualquier rol, excepto el de administrador avanzado.
• Puedes tener hasta 250 asignaciones de roles a grupos en total en la UO general y dentro de cada UO.
• El grupo debe ser un grupo de seguridad en tu organización.
• Te recomendamos que restrinjas la pertenencia a un grupo de los usuarios de tu organización. Puedes agregar usuarios ajenos a tu organización, pero es posible que no obtengan los privilegios del rol. Para obtener más información, consulta Cómo restringir la membresía de un grupo. ### Asignación de roles a grupos

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

Nota: Para crear grupos de seguridad, debes usar la API de Cloud Identity. No puedes usar la API de Directory. Para obtener más información, consulta la documentación del grupo de seguridad.

Asignación de roles a privilegios en la Consola del administrador de Google

Para asignar roles a los usuarios que acceden a sus privilegios a través de la Consola del administrador, es posible que debas otorgar ciertos privilegios adicionales. Por ejemplo, para otorgarle a un usuario la capacidad de crear otros usuarios a través de la Consola del administrador, no solo se requiere el privilegio 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: Mueve los usuarios	USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Cambia el 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: Agrega o quita alias	USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuarios: Suspende 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 los privilegios del dominio

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

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

• Si eres un distribuidor que obtiene privilegios para uno de tus clientes, usa el ID de cliente que muestra la operación Recuperar 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 devuelve los privilegios admitidos en 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
        }
      ]
    },
    ...
  ]
}

Cómo obtener los roles existentes

Para obtener una lista de los roles existentes, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Cómo autorizar solicitudes.

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

• Si eres un distribuidor que obtiene roles para un cliente, usa el ID de cliente que obtuviste con la operación Retrieve a user.

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 devuelve los roles 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
    },
    ...
  ]
}

Muestra todas las asignaciones de roles

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

• Si eres administrador y recibes asignaciones de roles en tu propio dominio, usa my_customer como el ID de cliente.

• Si eres un distribuidor que recibe asignaciones de roles para uno de tus clientes, usa el ID de cliente que muestra la operación Retrieve a user.

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 todos los roles asignados en el dominio:

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

Cómo enumerar todas las asignaciones de roles indirectos

Para obtener una lista paginada de todas las asignaciones de roles, incluidas las que se asignan indirectamente a un usuario debido a los grupos a los que pertenece, 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 página.

• Si eres administrador y recibes asignaciones de roles en tu propio dominio, usa my_customer como el ID de cliente.

• Si eres un distribuidor que recibe asignaciones de roles para uno de tus clientes, usa el ID de cliente que muestra la operación Retrieve a user.

• 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 todos los roles asignados 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 un rol nuevo, usa la siguiente solicitud POST y, luego, incluye la autorización que se describe en Autorizar solicitudes. Agrega un privilegeName y un serviceId para cada privilegio que se deba otorgar con este rol. 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 devuelve las propiedades del nuevo rol:

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

Crea una asignación de roles

Para asignar un rol, usa el siguiente método POST y, luego, incluye la autorización que se describe en Cómo autorizar solicitudes.

• Para asignar el rol a un usuario, agrega un cuerpo JSON con el user_id del usuario, que puedes obtener de users.get(), roleId (como se describe en Obtén roles existentes) y scope_type.

• Para asignar el rol a una cuenta de servicio, agrega un cuerpo JSON con el unique_id de la cuenta de servicio (como se define en Administración de identidades y accesos (IAM)), el roleId (como se describe en Cómo obtener roles existentes) y el scope_type.

• Para asignar el rol a un grupo, agrega un cuerpo JSON con el group_id del grupo, que puedes obtener de groups.get(), roleId (como se describe en Cómo obtener roles existentes) y scope_type.

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 devuelve las propiedades de la nueva asignación de roles:

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

Crea una asignación de roles con condiciones

Nota: Esta función solo está disponible en la versión v1.1beta1 de la API y solo para los clientes de Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus y Cloud Identity Premium. No se necesita ninguna configuración adicional para usar la función. La asignación de roles con condiciones aún no se respeta en la Consola del administrador.

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

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

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

Para asignar un rol a un usuario, usa el siguiente método POST y, luego, incluye la autorización que se describe en Autorizar 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 roles existentes y el condition. Las dos cadenas de condiciones se deben usar textualmente como se muestra a continuación y solo funcionan con los roles de administrador precompilados de Editor de Grupos y Lector de Grupos. Estas condiciones siguen la sintaxis de las condiciones de Cloud IAM.

Solicitud

Solo se aplica a los 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 se aplica a los 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 devuelve las propiedades de la nueva asignación de roles:

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