Esta página foi traduzida pela API Cloud Translation.

Gerenciar funções

A API Directory permite usar o controle de acesso baseado em papéis (RBAC, na sigla em inglês) para gerenciar o acesso aos recursos no seu domínio do Google Workspace. É possível criar papéis personalizados com privilégios para limitar o acesso de administrador de maneira mais específica do que as funções predefinidas 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 a papéis.

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 a 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 uma função específica atribuída ao usuário ou grupo. Representado pelo recurso RoleAssignment.
Grupo de segurança: Um tipo de grupo do Cloud Identity que é 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

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

É possível 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, como um departamento de uma empresa. O padrão de todas as funções de administrador predefinidas do Google Workspace é 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:

Qualquer função pode ser atribuída, exceto superadministrador.
É possível ter até 250 atribuições de função para grupos na UO geral e em cada UO.
O grupo precisa ser um grupo de segurança na sua organização.
Recomendamos restringir a associação aos usuários da sua organização. É possível adicionar usuários de fora da organização, mas eles podem não receber os privilégios do papel. Veja mais detalhes em Restringir a associação ao grupo.

Atribuição de funções a grupos

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

Mapeamento de funções e privilégios do Google Admin Console

Para atribuir funções a usuários que acessam os próprios privilégios no Admin Console, talvez seja necessário conceder alguns privilégios extras. Por exemplo, para conceder a um usuário a capacidade de criar outros usuários no Admin Console, não apenas o privilégio USERS_CREATE é obrigatório, mas também os privilégios USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE. A tabela a seguir mapeia a funcionalidade do Admin Console para as 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 - Lida	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Usuários - Criar	`USERS_CREATE` + `USERS_UPDATE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Atualização	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Usuários - Mover usuários	`USERS_MOVE` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Renomear usuários	`USERS_ALIAS` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Redefinir senha	`USERS_RESET_PASSWORD` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Forçar alteração de senha	`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Adicionar/remover aliases	`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
Usuários - Suspender usuários	`USERS_SUSPEND` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas
GRUPOS	`GROUPS_ALL`
Segurança - Gerenciamento de segurança do usuário	`USER_SECURITY_ALL` + `USERS_RETRIEVE` e mais `ORGANIZATION_UNITS_RETRIEVE` pessoas

Exemplos de casos de uso

Antes de começar

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

Acessar uma lista de privilégios do domínio

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

Se você for um administrador que está recebendo privilégios no seu domínio, use my_customer como ID de cliente.
Se você for um revendedor e receber privilégios de 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 compatíveis com o 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 ver 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 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 ver 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 recebendo atribuições de função no seu próprio domínio, use my_customer como ID de cliente.
Se você for um revendedor recebendo 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ções indiretas

Para ver uma lista paginada de todas as atribuições de papéis, 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 recebendo atribuições de função no seu próprio domínio, use my_customer como ID de cliente.
Se você for um revendedor recebendo 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 ver 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 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. Junto 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 método POST a seguir e inclua a autorização descrita em Autorizar solicitações.

Para atribuir o papel a um usuário, adicione um corpo JSON com o user_id do usuário, que pode ser recebido em users.get(), roleId (conforme descrito em Acessar papéis atuais) e scope_type.
Para atribuir o papel a uma conta de serviço, adicione um corpo JSON com o unique_id da conta de serviço (conforme definido em Gerenciamento de identidade e acesso (IAM)), o roleId (como descrito em Acessar papéis atuais) e o scope_type.
Para atribuir o papel a um grupo, adicione um corpo JSON com o group_id do grupo, que pode ser recebido em groups.get(), roleId (conforme descrito em Acessar papéis atuais) e scope_type.

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. Junto com o código de status, a resposta retorna as propriedades da nova atribuição de 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 a grupos de segurança

Quando condition for definido, ele só terá efeito quando o recurso que está sendo acessado atender à 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 em users.get(), roleId, conforme descrito em Acessar papéis atuais, e condition. As duas strings de condição precisam ser usadas na íntegra, conforme mostrado abaixo, e funcionam apenas com os papéis de administrador predefinidos de editor de grupos e de leitor de grupos. Essas condições seguem a sintaxe de 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 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'"
}

Resposta

Uma resposta bem-sucedida retorna um código de status HTTP 200. Junto com o código de status, a resposta retorna as propriedades da nova atribuição de 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'"
}