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, consulteusers.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.
Para atribuir o papel a um usuário, adicione um corpo JSON com o
user_id
do usuário, que pode ser recebido deusers.get()
,roleId
(como descrito em Acessar papéis atuais) escope_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 Identity and Access Management (IAM)), oroleId
(como descrito em Acessar papéis atuais) e oscope_type
.Para atribuir o papel a um grupo, adicione um corpo JSON com o
group_id
do grupo, que pode ser obtido emgroups.get()
,roleId
(como descrito em Acessar papéis atuais) escope_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
. 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'"
}