Esta página foi traduzida pela API Cloud Translation.

Gerenciar funções

Com a API Directory, você pode usar controle de acesso baseado em função (RBAC) 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 dos administradores de maneira mais específica 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 realizar algumas tarefas básicas relacionadas à função.

Veja a seguir uma lista de termos comuns usados pela API Directory com sobre 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 Privilege. não há dados permanentes associados a este recurso.
Cargo: Uma coleção de privilégios que concede a entidades com esse papel o capacidade de realizar certas tarefas ou operações. Representado pelo Recurso Role.
Atribuição de função: O registro de um papel específico atribuído a um usuário ou grupo. Representado por RoleAssignment recurso.
Grupo de segurança: Um tipo de Grupo do Cloud Identity que é usado para controlar o acesso aos recursos do Google Cloud. Os grupos de segurança podem conter usuários individuais e grupos.

Limites de atribuição de papéis e funções

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

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

Os papéis e a atribuição de papéis têm os seguintes limites para grupos:

Você pode atribuir qualquer função, exceto superadministrador.
É possível fazer até 250 atribuições de função a grupos na UO como um todo e dentro de cada UO.
O grupo precisa ser um grupo de segurança na sua organização.
Recomendamos restringir a associação ao grupo apenas aos usuários da sua organização. Você podem adicionar usuários de fora da organização, pode não receber os privilégios da função. Para mais detalhes, consulte Restringir a associação ao grupo. ### Atribuição de papéis a grupos

Se você precisar atribuir mais de mil funções a uma UO, poderá adicionar vários membros a um grupo de segurança e atribuir uma função a ele. Função no grupo tarefas têm algumas limitações adicionais. Consulte o Central de Ajuda para admins para informações específicas.

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

Para atribuir funções a usuários que acessam os privilégios por meio do no Admin Console, pode ser necessário concedido. Por exemplo, para conceder a um usuário a capacidade de criar outros usuários por o Admin Console, além do privilégio USERS_CREATE obrigatório, mas também os parâmetros USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE para conceder privilégios de acesso. A tabela a seguir mapeia o Admin Console da organização às 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`
Usuários: criar	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Usuários: atualização	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Users – 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 autenticação e autorização para o Google Workspace.

Acessar uma lista de privilégios do domínio

Para obter uma lista paginada de privilégios compatíveis em seu domínio, use o privileges.list() .

Se você for um administrador e receber privilégios em seu próprio domínio, use my_customer como o ID de cliente.
Se você é um revendedor e está recebendo privilégios para um dos seus clientes, use o ID do cliente retornado pelo método Recuperar um user.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um status HTTP 200 ou código-fonte. Junto com o a resposta retornará 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 consultar uma lista dos papéis atuais, use a seguinte solicitação GET e inclua o autorização descrita em Autorizar solicitações.

Se você for um administrador recebendo funções em seu próprio domínio, use my_customer como o ID de cliente.
Se você for revendedor recebendo funções para um cliente, use o ID de cliente usando o recurso Recuperar um user.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um status HTTP 200 código. Junto 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 função direta, use o método roleAssignments.list() . A API poderá retornar resultados vazios com um token de página quando o evento userKey é definido. Continue a paginação até que nenhum token de página seja retornados.

Se você for um administrador e receber atribuições de função em seu próprio domínio, use my_customer como o ID de cliente.
Se você é um revendedor e está recebendo atribuições de função para um dos seus clientes, use o ID do cliente retornado pelo método Recuperar um user.

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um status HTTP 200 código. Junto com o código de status, a resposta retornará 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 receber uma lista paginada de todas as atribuições de papel, incluindo as indiretas atribuído a um usuário devido aos grupos aos quais ele pertence, use o roleAssignments.list() .

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

Se você for um administrador e receber atribuições de função em seu próprio domínio, use my_customer como o ID de cliente.
Se você é um revendedor e está recebendo atribuições de função para um dos seus clientes, use o ID do cliente retornado pelo método Recuperar um user.
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 status HTTP 200 código. Junto com o de status, a resposta retornará todos os papéis atribuídos 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 um novo papel, use a seguinte solicitação POST e inclua o autorização descrita em Autorizar solicitações. Adicione um privilegeName e um serviceId para cada privilégio que será concedido com esse papel. Para obter as propriedades de solicitação e resposta, consulte a API Referência.

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 status HTTP 200 código. Junto com o código de status, a resposta retornará as propriedades para o 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 descritos em Autorizar solicitações

Para atribuir o papel a um usuário, adicione um corpo JSON com o user_id do usuário. que você pode receber de users.get(), a roleId (conforme descrito em Buscar papéis 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 Identity and Access Management (IAM)), o roleId (conforme 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 que você pode acessar groups.get(), a roleId (conforme descrito em receber 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 status HTTP 200 código. Junto com o código de status, a resposta retornará as propriedades para a 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 papel 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 para grupos de segurança

Quando condition for definido, ele só terá efeito quando o recurso que estiver sendo acessados atendem à condição. Se condition estiver vazio, o papel (roleId) será aplicada ao ator (assignedTo) no escopo (scopeType) incondicionalmente.

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

Adicione um corpo JSON com o user_id do usuário, que você pode acessar users.get(), o roleId como descritos em Buscar papéis atuais e condition. O duas strings de condição precisam ser usadas literalmente, conforme mostrado abaixo, e elas só funcionam com o Editor de grupos e o Leitor de grupos funções de administrador predefinidas. Essas condições seguem 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 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'"
}

Resposta

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