Esta página foi traduzida pela API Cloud Translation.

Gerenciar funções

A API Directory permite usar o controle de acesso baseado em função (RBAC) 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 do administrador de forma mais específica do que as funções predefinidas fornecidas com o Google Workspace. É possível atribuir funções a usuários ou grupos de segurança. Este guia explica como realizar algumas tarefas básicas relacionadas a funções.

Confira 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 realizar uma tarefa ou operação em um domínio do Google Workspace. Representado pelo recurso Privilege. Não há dados permanentes associados a este recurso.
Cargo: Uma coleção de privilégios que concede a entidades com essa função a capacidade de realizar determinadas tarefas ou operações. Representado pelo recurso Role.
Atribuição de função: O registro de uma função específica concedida 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.

Funções e limites de atribuição de funções

Você só pode criar uma quantidade limitada de atribuições de função ou funções personalizadas. Se você estiver chegando perto do limite, consolide ou remova as atribuições para ficar abaixo do limite. Os papéis e as atribuições de função têm os seguintes limites:

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

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

É possível atribuir qualquer função, exceto Superadministrador.
É possível atribuir até 250 funções a grupos no total na UO geral e em cada UO.
O grupo precisa ser de segurança na sua organização.
Recomendamos restringir a associação a grupos aos usuários da sua organização. Você pode adicionar usuários de fora da sua organização, mas eles talvez não recebam os privilégios da função. Confira mais detalhes em Restringir a associação ao grupo. ### Atribuição de funções a grupos

Se você precisar atribuir mais de 1.000 funções em uma UO, adicione vários membros a um grupo de segurança e atribua uma função a ele. As atribuições de função do grupo têm algumas limitações adicionais. Consulte a Central de Ajuda para administradores para saber mais.

Mapeamento de função para privilégio do Google Admin Console

Para atribuir funções a usuários que acessam os privilégios pelo 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 pelo Admin Console, o privilégio USERS_CREATE é necessário, mas também os privilégios USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE são. A tabela a seguir associa a funcionalidade do Admin Console aos 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: leitura	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Usuários: criar	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Users - Update	`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`
Users - Force Password Change	`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.

Conferir uma lista de privilégios de domínio

Para receber 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 próprio domínio, use my_customer como o ID do cliente.
Se você for um revendedor que está recebendo privilégios para um dos seus clientes, use o ID do 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

Uma resposta bem-sucedida retorna um código de status HTTP 200. Além do código de status, a resposta retorna os privilégios aceitos 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
        }
      ]
    },
    ...
  ]
}

Conferir as funções atuais

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

Se você for um administrador que está recebendo funções no seu próprio domínio, use my_customer como o ID do cliente.
Se você for um revendedor que recebe papéis para um cliente, use o ID do cliente que você recebeu usando a 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. Além do código de status, a resposta retorna as funções 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 função diretas, use o método roleAssignments.list(). A API pode retornar resultados vazios com um token de página quando o parâmetro userKey é definido. Continue a paginação até que nenhum token de página seja retornado.

Se você for um administrador que recebe atribuições de função no seu próprio domínio, use my_customer como o ID do cliente.
Se você é um revendedor que recebe atribuições de função para um dos seus clientes, use o ID do 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. Além do código de status, a resposta retorna todas as funções atribuídas 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 função, incluindo aquelas atribuídas indiretamente a um usuário devido aos grupos aos quais 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 que recebe atribuições de função no seu próprio domínio, use my_customer como o ID do cliente.
Se você é um revendedor que recebe atribuições de função para um dos seus clientes, use o ID do cliente retornado pela operação Recuperar um usuário.
Substitua USER_KEY por um valor que identifique o usuário na solicitação da 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. Além do código de status, a resposta retorna todas as funções atribuídas no domínio e se o 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 uma nova função, use a solicitação POST abaixo e inclua a autorização descrita em Autorizar solicitações. Adicione um privilegeName e um serviceId para cada privilégio que precisa ser concedido com essa função. 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. Além do código de status, a resposta retorna as propriedades da nova função:

{
  "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 uma função, use o método POST abaixo 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 encontrado em users.get(), o roleId (conforme descrito em Receber funções atuais) e o 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 (conforme descrito em Recuperar papéis) e o scope_type.
Para atribuir a função a um grupo, adicione um corpo JSON com o group_id do grupo, que pode ser encontrado em groups.get(), roleId (conforme descrito em Recuperar funções 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. Além do código de status, a resposta retorna as propriedades da nova atribuição de função:

{
  "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 funções para realizar ações que atendam a condições específicas. No momento, somente duas condições são aceitas:

Válido apenas para grupos de segurança
Não se aplica a 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 uma função a um usuário, use o método POST abaixo e inclua a autorização descrita em Autorizar solicitações.

Adicione um corpo JSON com o user_id do usuário, que pode ser acessado em users.get(), o roleId conforme descrito em Receber funções atuais e o condition. As duas strings de condição precisam ser usadas literalmente, conforme mostrado abaixo, e funcionam apenas com as funções de administrador predefinidas do editor e do leitor de grupos. Essas condições seguem a sintaxe de condições do Cloud IAM.

Solicitação

Válido apenas para 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 se aplica 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. Além do código de status, a resposta retorna as propriedades da nova atribuição de função:

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