Administrar roles

La API de Directory te permite usar 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 administrador de manera más específica que los roles predefinidos de Google Workspace. Puedes asignar roles a los usuarios o grupos de seguridad. En esta guía, se explica cómo realizar algunas tareas básicas relacionadas con el rol.

La siguiente es una lista de términos comunes usados por la API de Directory con en cuanto al RBAC en Google Workspace:

Privilegio

El permiso necesario para realizar una tarea o una operación en una dominio de Google Workspace. Representado por el Recurso Privilege. Hay no hay datos persistentes asociados con este recurso.

Función

Es una colección de privilegios que otorga a las entidades con ese rol las capacidad para realizar ciertas tareas u operaciones. Representado por el Recurso Role.

Asignación de roles

El registro de un rol específico otorgado al usuario o grupo. Representado por el RoleAssignment recurso.

Grupo de seguridad

Un tipo de Grupo de Cloud Identity que se usa para controlar el acceso a los datos de Google Cloud. Los grupos de seguridad pueden contener tanto usuarios individuales como grupos.

Límites de asignación de roles

Solo puedes crear una cantidad limitada de roles personalizados o asignaciones de roles, así que te estás acercando al límite, consolide los recursos o quítalos para no superar el límite. Las funciones y las asignaciones de funciones tienen los siguientes límites:

• Puedes crear hasta 750 roles personalizados para toda la 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. De forma predeterminada, todos los roles de administrador predefinidos de Google Workspace en toda la organización. Obtén más información sobre y límites de 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 un máximo de 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 de tu organización.
• Te recomendamos que restrinjas la pertenencia a un grupo solo a los usuarios de tu organización. Tú pueden agregar usuarios ajenos a tu organización, pero podría no obtener los privilegios del rol. Para obtener más información, consulta Restringe la pertenencia a un grupo. ### Asignación de funciones a grupos

Si necesitas asignar más de 1,000 roles en una UO, puedes agregar varios miembros a un grupo de seguridad y asignarles un rol. Rol en el grupo asignaciones tienen algunas limitaciones adicionales; consulta el Centro de ayuda para administradores si desea 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 el grupo de seguridad documentación.

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

Para asignar roles a los usuarios que acceden a sus privilegios a través del Consola del administrador, tal vez se deban otorgar otorgada. Por ejemplo, para otorgar a un usuario la capacidad de crear otros usuarios a través de la Consola del administrador, y no solo el privilegio USERS_CREATE obligatorio, pero también los valores USERS_UPDATE y ORGANIZATION_UNITS_RETRIEVE privilegios. En la siguiente tabla, se muestra la información de la Consola del administrador a las concesiones de privilegios requeridas para administrar usuarios y unidades organizativas.

Funcionalidad de la Consola del administrador	Privilegios necesarios
Unidades organizativas: Lectura	ORGANIZATION_UNITS_RETRIEVE
Unidades organizativas: Creación	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: Cambiar los nombres 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: Cómo 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 de los usuarios	USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Ejemplos de casos de uso

Antes de comenzar

Completa el autenticación y autorización pasos para Google Workspace.

Obtener una lista de los privilegios del dominio

Para obtener una lista paginada de los privilegios admitidos en tu dominio, usa la privileges.list() .

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

• Si usted es un distribuidor y obtiene privilegios para uno de sus clientes, utiliza el ID de cliente devuelto por la opción Recuperar user.

Solicitud

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

Respuesta

Una respuesta correcta devuelve un estado HTTP 200 automático. Además del 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
        }
      ]
    },
    ...
  ]
}

Obtener roles existentes

Para obtener una lista de los roles existentes, usa la siguiente solicitud GET y agrega autorización descrita en Autorizar de estado de Google.

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

• Si es un distribuidor y obtiene roles para un cliente, use el ID de cliente que gracias a la función Recuperar user.

Solicitud

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

Respuesta

Una respuesta correcta devuelve un estado HTTP 200 correcto. Además del 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
    },
    ...
  ]
}

Enumera todas las asignaciones de roles

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

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

• Si usted es distribuidor y le asigna funciones a uno de sus clientes utiliza el ID de cliente devuelto por la opción Recuperar user.

Solicitud

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

Respuesta

Una respuesta correcta devuelve un estado HTTP 200 correcto. Además del código de estado, la respuesta devuelve todos los roles asignados en el dominio:

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

Enumera todas las asignaciones de funciones indirectas

Para obtener una lista paginada de todas las asignaciones de roles, incluidas aquellas indirectamente a un usuario por los grupos a los que pertenece, usa el roleAssignments.list() .

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

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

• Si usted es distribuidor y le asigna funciones a uno de sus clientes utiliza el ID de cliente devuelto por la opción Recuperar user.

• Reemplaza USER_KEY por un valor que identifique la 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 devuelve un estado HTTP 200 correcto. Además del código de estado, la respuesta devuelve todos los roles asignados en el dominio 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 agrega lo siguiente: autorización descrita en Autorizar de estado de Google. Agrega privilegeName y serviceId para cada privilegio que se debe otorgadas con este rol. Para conocer las propiedades de solicitud y respuesta, consulta la sección Referencia.

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 devuelve un estado HTTP 200 correcto. Además del 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 rol

Para asignar un rol, usa el siguiente método POST y, además, incluye la autorización descritos en Autoriza solicitudes.

• Para asignar el rol a un usuario, agrega un cuerpo JSON con el user_id del usuario. que puedes llegar desde users.get(), el roleId (como se describe en Obtener roles existentes) y el 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 Identity and Access Management (IAM)), el roleId (como se describe en Obtener roles existentes) y la scope_type.

• Para asignar el rol a un grupo, agrega un cuerpo JSON con el group_id de la que puedes obtener del groups.get(), el roleId (como se describe en Obtener roles existentes), y el 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 devuelve un estado HTTP 200 correcto. Además del estado, la respuesta devuelve las propiedades de la nueva asignación de rol:

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

Crea una asignación de rol con condiciones

Nota: Esta función solo está disponible en la versión v1.1beta1 de la API. solo a Enterprise Standard, Enterprise Plus y Google Workspace for Education Plus y Cloud Identity Premium. No se necesita configuración adicional para usar la función. La asignación de roles con condiciones 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 grupos de seguridad
• No aplicable a grupos de seguridad

Si estableces condition, solo tendrá efecto cuando el recurso se a las que se accede cumple la condición. Si condition está vacío, el rol (roleId) es se aplica al actor (assignedTo) en el alcance (scopeType) incondicionalmente.

Para asignar un rol a un usuario, usa el siguiente método POST e incluye autorización descrita en Autorizar solicitudes.

Agrega un cuerpo JSON con el user_id del usuario, que puedes obtener desde users.get(), roleId como descrita en Obtener roles existentes, y la condition. El dos cadenas de condición deben usarse literalmente, como se muestra a continuación, y estas Funcionan únicamente con el Editor de grupos y el Lector de grupos. funciones de administrador predefinidas. Estas condiciones siguen Sintaxis de 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 devuelve un estado HTTP 200 correcto. Además del estado, la respuesta devuelve las propiedades de la nueva asignación de rol:

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