Gerenciar funções

A API Directory permite usar o controle de acesso baseado em funções (RBAC, na sigla em inglês) para gerenciar o acesso a recursos no seu domínio do Google Workspace. É possível criar funções personalizadas com privilégios para limitar o acesso de administrador de forma mais específica do que os papéis predefinidos do Google Workspace. É possível atribuir papéis a usuários ou grupos de segurança. Este guia explica como executar algumas tarefas básicas relacionadas ao papel.

Veja a seguir uma lista de termos comuns usados pela API Directory em relação ao RBAC no Google Workspace:

Privilégio
A permissão necessária para executar uma tarefa ou operação em um domínio do Google Workspace. Representado pelo recurso Privilege. Não há dados persistentes associados a esse recurso.
Papel
Uma coleção de privilégios que concede às entidades com esse papel a capacidade de executar determinadas tarefas ou operações. Representado pelo recurso Role.
Atribuição de papéis
O registro de um papel específico atribuído ao usuário ou grupo. Representado pelo recurso RoleAssignment.
Grupo de segurança
Um tipo de grupo do Cloud Identity usado para controlar o acesso a recursos organizacionais. Os grupos de segurança podem conter usuários individuais e grupos.

Limites de atribuição de funções

Só é possível criar uma quantidade limitada de papéis ou atribuições de papéis personalizados. Portanto, se você estiver se aproximando do limite, consolide ou remova-os para permanecer dentro do limite. Funções e atribuições de função têm os seguintes limites:

  • Você pode criar até 750 funções personalizadas para toda a organização.
  • É possível criar até 500 atribuições de função por unidade organizacional (UO), em que a organização raiz é considerada uma unidade. Por exemplo, é possível atribuir 350 funções na organização raiz e 400 funções em outra UO definida por você, como um departamento de uma empresa. Por padrão, todas as funções de administrador predefinidas do Google Workspace têm o escopo de toda a organização. Saiba mais sobre os limites dos privilégios que podem ser atribuídos no nível da unidade organizacional.

As funções e a atribuição de papéis têm os seguintes limites para grupos:

  • Você pode atribuir qualquer função, exceto superadministrador.
  • É possível ter até 250 atribuições de função para grupos no total na unidade organizacional geral e em cada unidade organizacional.
  • O grupo precisa ser de segurança na sua organização.
  • Recomendamos restringir a associação a grupos a usuários na sua organização. É possível adicionar usuários de fora da organização, mas eles talvez não recebam os privilégios do papel. Saiba mais em Restringir a associação ao grupo.

Atribuição de função a grupos

Se você precisar atribuir mais de 500 papéis em uma UO, poderá adicionar vários membros a um grupo de segurança e atribuir um papel a ele. As atribuições de papéis em grupo têm algumas limitações adicionais. Consulte a Central de Ajuda do administrador para informações específicas.

Mapeamento de função para privilégios no Google Admin Console

Para atribuir papéis a usuários que acessam privilégios por meio do Admin Console, pode ser necessário conceder determinados privilégios extras. Por exemplo, para conceder a um usuário a capacidade de criar outros usuários no Admin Console, não só o privilégio USERS_CREATE é obrigatório, mas também os privilégios USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE. A tabela a seguir faz a correlação da funcionalidade do Admin Console às concessões de privilégios necessários para gerenciar usuários e unidades organizacionais.

Funcionalidade do Admin Console Privilégios necessários
Unidades organizacionais – Leitura ORGANIZATION_UNITS_RETRIEVE
Unidades organizacionais: criar ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Unidades organizacionais: atualização ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Unidades organizacionais: excluir ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Unidades organizacionais ORGANIZATION_UNITS_ALL
Usuários - Ler USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Criar USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Atualização USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Mover usuários USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Renomear usuários USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Redefinir senha USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Forçar alteração de senha USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários: adicionar/remover aliases USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Usuários - Suspender usuários USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GRUPOS GROUPS_ALL
Segurança: gerenciamento de segurança do usuário USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Exemplos de casos de uso

Antes de começar

Conclua as etapas de autenticação e autorização do Google Workspace.

Acessar uma lista de privilégios de domínio

Para conferir uma lista paginada de privilégios compatíveis no seu domínio, use o método privileges.list().

  • Se você for um administrador e tiver privilégios no seu próprio domínio, use my_customer como o ID de cliente.

  • Se você for um revendedor e tiver privilégios para um dos seus clientes, use o ID de cliente retornado pela operação Recuperar um usuário.

Solicitação

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

Resposta

Se a resposta for bem-sucedida, será retornado um código de status HTTP 200. Com o código de status, a resposta retorna os privilégios com suporte no domínio:

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

Acessar papéis atuais

Para conferir uma lista dos papéis atuais, use a solicitação GET a seguir e inclua a autorização descrita em Autorizar solicitações.

  • Se você for um administrador e estiver recebendo papéis no seu domínio, use my_customer como ID de cliente.

  • Se você estiver recebendo funções de um revendedor para um cliente, use o ID que você recebeu na operação Recuperar um usuário.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna os papéis que existem no domínio:

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

Listar todas as atribuições de função

Para conferir uma lista paginada de todas as atribuições de papéis diretos, use o método roleAssignments.list(). A API pode retornar resultados vazios com um token de página quando o parâmetro userKey estiver definido. Continue a paginação até que nenhum token de página seja retornado.

  • Se você for um administrador e receber atribuições de função no seu próprio domínio, use my_customer como o ID de cliente.

  • Se você for um revendedor e receber atribuições de função para um dos seus clientes, use o ID de cliente retornado pela operação Recuperar um usuário.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna todos os papéis atribuídos no domínio:

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

Listar todas as atribuições de função indiretas

Para conferir uma lista paginada de todas as atribuições de papel, incluindo aquelas atribuídas indiretamente a um usuário devido aos grupos a que ele pertence, use o método roleAssignments.list().

A API pode retornar resultados vazios com um token de página. Continue a paginação até que nenhum token de página seja retornado.

  • Se você for um administrador e receber atribuições de função no seu próprio domínio, use my_customer como o ID de cliente.

  • Se você for um revendedor e receber atribuições de função para um dos seus clientes, use o ID de cliente retornado pela operação Recuperar um usuário.

  • Substitua USER_KEY por um valor que identifique o usuário na solicitação de API. Para mais informações, consulte users.get.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna todos os papéis atribuídos no domínio e se assigneeType é user ou group:

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

criar um papel;

Para criar um novo papel, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações. Adicione um privilegeName e um serviceId para cada privilégio que será concedido com esse papel. Para as propriedades de solicitação e resposta, consulte a Referência da API.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna as propriedades do novo papel:

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

Criar uma atribuição de função

Para atribuir um papel, use o seguinte método POST e inclua a autorização descrita em Autorizar solicitações.

Solicitação

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

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

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna as propriedades da nova atribuição do papel:

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

Criar uma atribuição de função com condições

É possível conceder papéis para executar ações que atendam a condições específicas. Atualmente, apenas duas condições são aceitas:

  • Aplicável apenas a grupos de segurança
  • Não relevante aos grupos de segurança

Quando condition é definido, ele só entra em vigor quando o recurso acessado atende à condição. Se condition estiver vazio, o papel (roleId) será aplicado ao ator (assignedTo) no escopo (scopeType) incondicionalmente.

Para atribuir um papel a um usuário, use o método POST a seguir e inclua a autorização descrita em Autorizar solicitações.

Adicione um corpo JSON com o user_id do usuário, que pode ser obtido de users.get(), do roleId, conforme descrito em Usar papéis atuais, e do condition. As duas strings de condição precisam ser usadas literalmente, conforme mostrado abaixo, e só funcionam com as funções de administrador predefinidas de Editor de Grupos e Leitor de Grupos. Essas condições seguem a sintaxe da condição do Cloud IAM.

Solicitação

Aplicável apenas a grupos de segurança
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'"
}
Não relevante aos grupos de segurança
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'"
}

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Com o código de status, a resposta retorna as propriedades da nova atribuição do papel:

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