Esta página foi traduzida pela API Cloud Translation.

Gerenciar funções

Com a API Directory, é possível usar o controle de acesso baseado em papéis (RBAC) para gerenciar o acesso aos 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 as funções predefinidas fornecidas com o Google Workspace. É possível atribuir papéis a usuários ou grupos de segurança. Este guia explica como realizar algumas tarefas básicas relacionadas a papéis.

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: Um conjunto de privilégios que concede às 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 atribuída 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 função e atribuição de função

Você só pode criar uma quantidade limitada de funções personalizadas ou atribuições de função. Se estiver se aproximando do limite, consolide ou remova algumas para ficar abaixo dele. As funções 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), considerando a organização raiz como uma unidade. Por exemplo, é possível atribuir 600 funções na organização raiz e 700 em outra OU definida, como um departamento de uma empresa. Todas as funções de administrador predefinidas do Google Workspace têm como padrão o escopo em toda a 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 um grupo de segurança na sua organização.
Recomendamos restringir a associação ao grupo a usuários da organização. Você pode adicionar usuários de fora da organização, mas eles talvez não recebam os privilégios da função. Para mais detalhes, consulte 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 no grupo têm algumas limitações adicionais. Consulte a Central de Ajuda para administradores para informações específicas.

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

Para atribuir funções a usuários que acessam privilégios pelo Admin Console, talvez seja necessário conceder outros privilégios. Por exemplo, para conceder a um usuário a capacidade de criar outros usuários pelo Admin Console, não é necessário apenas o privilégio USERS_CREATE, 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árias 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`
Users - Create	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Usuários: atualizar	`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

Antes de executar os exemplos neste guia, configure a autenticação e autorização.

Receber 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 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 compatíveis 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 receber uma lista de papéis atuais, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações.

Se você for um administrador que está recebendo papéis no seu próprio domínio, use my_customer como ID do cliente.
Se você for um revendedor que está recebendo 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 receber uma lista paginada de todas as atribuições diretas de função, 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 está recebendo atribuições de função no seu próprio domínio, use my_customer como ID do cliente.
Se você for um revendedor que está recebendo 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 indiretas de função

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

Para atribuir a função a um usuário, adicione um corpo JSON com o user_id do usuário, que pode ser obtido 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 no Gerenciamento de identidade e acesso (IAM)), o roleId (conforme descrito em Receber papéis atuais) 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 obtido em groups.get(), o roleId (conforme descrito em Receber funções atuais) e o 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, apenas duas condições são aceitas:

Válido apenas para grupos de segurança
Não aplicável a grupos de segurança

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

Para atribuir uma função 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(), o roleId conforme descrito em Receber papéis atuais e o condition. As duas strings de condição precisam ser usadas exatamente como mostrado abaixo e só funcionam com as funções de administrador predefinidas do Editor e do Leitor de grupos. Essas condições seguem a sintaxe de condição 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 aplicável 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'"
}

Gerenciar funções Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Limites de função e atribuição de função

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

Exemplos de casos de uso

Antes de começar

Receber uma lista de privilégios de domínio

Solicitação

Resposta

Acessar papéis atuais

Solicitação

Resposta

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

Solicitação

Resposta

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

Solicitação

Resposta

Criar um papel

Solicitação

Resposta

Criar uma atribuição de função

Solicitação

Resposta

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

Solicitação

Válido apenas para grupos de segurança

Não aplicável a grupos de segurança

Resposta

Gerenciar funções