Como criar e gerenciar papéis personalizados

Esta é uma versão de Papéis personalizados do IAM. de maneiras incompatíveis com versões anteriores é não está(ão) sujeito(s) a nenhum SLA ou política de suspensão de uso.

Nesta página, você encontra informações de como criar e gerenciar um papel personalizado.

Antes de começar

• Leia Como entender papéis personalizados IAM e confira informações sobre permissões necessárias para criar papéis personalizados e práticas recomendadas.

Como ver as permissões disponíveis para um recurso

Antes de criar um papel personalizado, é recomendável saber quais permissões podem ser aplicadas a um recurso. Com o Cloud Console ou a IAM API, você consulta todas as permissões aplicáveis a um recurso e os recursos subordinados a ele na hierarquia. Por exemplo, isso pode ser feito para uma organização e para os projetos dela.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Na parte superior da página, selecione o projeto na lista suspensa.
3. Marque a caixa de seleção do papel de administrador do recurso. Assim, você poderá ver todas as permissões aplicáveis a esse recurso. Por exemplo, quando você seleciona o papel Administrador da instância do Compute, o painel à direita exibe todas as permissões aplicáveis a uma instância do Compute Engine.

API

Com QueryTestablePermissions, todas as permissões aplicáveis a um recurso são retornadas. Com elas, você cria um papel personalizado nesse recurso e em qualquer outro subordinado a ele na hierarquia. A única entrada obrigatória para essa solicitação é o nome completo do recurso, por exemplo, //cloudresourcemanager.googleapis.com/projects/my-project.

Se preferir, pode haver compatibilidade com a paginação no autor da chamada caso a lista de permissões do recurso seja longa.

Exemplo

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project/buckets/bucket1'`

Códigos de erro

Código de erro	Mensagem de status
INVALID_ARGUMENT	O valor precisa ser entre 0 e 100
INVALID_ARGUMENT	Codificação de token de paginação inválida
INVALID_ARGUMENT	Token de paginação inválido
INVALID_ARGUMENT	Token de paginação incorreto para o contêiner especificado
INVALID_ARGUMENT	Ponto de partida inválido no token de paginação
INVALID_ARGUMENT	Cookie do token de paginação inválido
INVALID_ARGUMENT	Token de paginação expirado
INVALID_ARGUMENT	{full_resource_name} precisa ser especificado
INVALID_ARGUMENT	{full_resource_name} não atende aos critérios: //[a-z0-9.-]/.a-z0-9.-]/

Como consultar os metadados do papel

Antes de criar um papel personalizado, consulte os metadados dos papéis predefinidos e personalizados. Esses metadados incluem o código e as permissões do papel. Visualize os metadados usando o Console do Google Cloud Platform ou a IAM API.

Para visualizar os metadados do papel, use um dos métodos abaixo:

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Na parte superior da página, selecione a organização ou o projeto na lista suspensa.
3. Marque a caixa de seleção de um ou mais papéis para visualizar as permissões. O painel do lado direito exibe as permissões deles, se houver.

Os ícones ao lado do papel indicam se ele é personalizado (ícone de "fábrica") ou predefinido (ícone de hexágono).

Para procurar todos os papéis com uma permissão específica, na parte superior da lista "Papéis", digite o nome da permissão na caixa Filtro.

API

Se você sabe o nome do papel que deseja ver, use o método roles.get para consultar um papel personalizado. Caso contrário, use o método roles.list para listar todos os papéis personalizados de uma organização ou um projeto.

Para chamar o GetRole(), defina o seguinte campo no GetRoleRequest:

• nome do papel, por exemplo, roles/{ROLE_NAME} ou organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}.

Para chamar o ListRoles(), defina o seguinte campo no ListRolesRequest:

• recurso pai dos papéis personalizados que você deseja consultar, por exemplo, organizations/{ORGANIZATION_ID} ou projects/{PROJECT_ID}.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para chamar o papel em {path}
NOT_FOUND	O papel {role} não foi encontrado.
INVALID_ARGUMENT	O nome do papel precisa estar no formato roles/{role} ou organizations/{organization_id}/roles/{role}.
PERMISSION_DENIED	Você não tem permissão para listar papéis em {path}.
INVALID_ARGUMENT	Pai {path} inválido. O pai precisa estar no formato organizations/{organization_id} ou vazio.
INVALID_ARGUMENT	Visualização de papel inválida.

Como criar um papel personalizado

Para criar um papel personalizado, o autor da chamada precisa ter a permissão iam.roles.create. Por padrão, o proprietário do projeto ou da organização tem essa permissão e pode criar e gerenciar papéis personalizados.

Usuários não proprietários, incluindo administradores da organização, precisam receber o papel de administrador de papéis da organização ou de papéis de IAM.

Console

Para criar um papel personalizado do zero, siga estas etapas:

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione a sua organização na lista suspensa Organização.
3. Clique em Criar papel.
4. Insira um Nome, um Título e uma Descrição para o papel.
5. Clique em Adicionar permissões.
6. Selecione as permissões que deseja incluir no papel e clique em Adicionar permissões. Use as listas suspensas Todos os serviços e Todos os tipos para filtrar e selecionar permissões por serviço e tipo.

Para criar um papel personalizado com base em um papel existente, siga estas etapas:

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione a sua organização na lista suspensa Organização.
3. Selecione os papéis que deseja usar como base para criar o papel personalizado.
4. Clique em Criar papel a partir da seleção.
5. Insira um Nome, um Título e uma Descrição para o papel.
6. Desmarque as permissões que deseja excluir do papel.
7. Clique em Adicionar permissões para incluir permissões.
8. Clique em Criar.

API

Use o método create para criar um novo papel personalizado.

Configure os seguintes parâmetros obrigatórios na solicitação:

• o role_id do novo papel personalizado, por exemplo, appengine.myCustomStorageAuditor
• a descrição do papel personalizado, por exemplo, "Com este papel, você lista os recursos de armazenamento, a capacidade deles e as políticas de acesso"
• uma lista das permissões que você deseja associar ao papel
• Observe que a configuração do campo do name no papel resultará em um erro.

Configure também os seguintes parâmetros opcionais:

• título do papel personalizado, por exemplo, "Editor de papéis personalizados".
• um valor para stage, por exemplo, GA

Em stage, os seguintes valores são aceitos: ALPHA, BETA, GA, DEPRECATED e DISABLED.

Alguns papéis predefinidos têm permissões com uso suspenso ou não permitidas em papéis personalizados. Uma falha ocorre quando você tenta criar um papel personalizado com base em um predefinido com essas características.

Exemplo

parent: '[PARENT_NAME]'
role_id: '[ROLE_ID]'
role {
    name: ''
    title: '[ROLE_TITLE]'
    description: '[ROLE_DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

em que:

• [PARENT_NAME] é o nome da organização, por exemplo, organizations/0000000000000001, ou o código do projeto, por exemplo, projects/my-project, no qual você deseja criar o papel personalizado;
• [ROLE_ID] é o código do papel personalizado. Por exemplo, appengine.myCustomStorageAuditor.
• [ROLE_TITLE] é o título do papel. Por exemplo, Storage Auditor;
• [ROLE_DESCRIPTION] é a descrição desse papel;
• [PERMISSION] é a permissão que você quer incluir no papel personalizado.

Observação: quando você chamar create, o campo do nome do papel na solicitação não será configurado. Esse nome, assim que for criado, será configurado com organizations/{ORGANIZATION_ID}/roles/{ROLE_ID} ou projects/{PROJECT_ID}/roles/{ROLE_ID}.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para criar um papel em {parent}.
ALREADY_EXISTS	Já existe um papel chamado {role_id} em {parent}.
INVALID_ARGUMENT	Pai {parent} inválido. O pai precisa estar no formato organizations/{organization_id}.
INVALID_ARGUMENT	ID de papel {role_id} inválido. Ele não corresponde ao padrão {pattern}.
INVALID_ARGUMENT	O número de permissões no papel é maior que o máximo {max}.
INVALID_ARGUMENT	Cenário de papel {stage} inválido.

Como editar um papel personalizado

Leitura-modificação-gravação

Um padrão comum na atualização dos metadados de um recurso, por exemplo, um papel personalizado, é ler o estado atual, atualizar os dados localmente e enviá-los para gravação. Com esse padrão, um conflito pode ocorrer se dois ou mais processos independentes tentarem executar a sequência simultaneamente. Por exemplo, quando dois proprietários de um projeto fazem alterações conflitantes em um papel ao mesmo tempo, pode haver uma falha. Esse problema é solucionado no Cloud IAM com a propriedade etag dos papéis personalizados. Com essa propriedade, você verifica se o papel personalizado foi alterado desde a última solicitação. Quando a solicitação é enviada ao Cloud IAM com um valor de etag, ele é comparado com o valor de etag associado ao papel. A alteração é gravada somente se esses valores forem correspondentes.

Para atualizar um papel, leia-o com roles.get(), atualize-o e grave-o com roles.patch(). Somente use o valor da etag quando configurar o papel caso o papel correspondente no roles.get() também contenha um valor de etag.

Observação: quando você modifica um papel personalizado adicionando ou removendo qualquer uma das seguintes permissões: resourcemanager.organizations.get, resourcemanager.folders.get e resourcemanager.projects.get, é necessário aguardar até 24 horas para que a alteração do papel personalizado entre em vigor nas Cloud Resource Manager APIs organizations.search e folders.search. A API projects.list também está sujeita a esse atraso em chamadas de API que não fornecem um filtro com detalhes de tipo pai e código. Esse atraso ocorre porque essas permissões envolvem funcionalidade de pesquisa e levam até 24 horas entre as recompilações do índice de pesquisa.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione a sua organização na lista suspensa Organização.
3. Clique em um papel personalizado.
4. Clique em Editar papel.
5. Clique em Adicionar permissões para adicionar novas permissões ao papel.
6. Desmarque as permissões para removê-las do papel.
7. Clique em Atualizar para salvar o papel editado.

API

Use o método Role UpdateRole(UpdateRoleRequest) para editar um papel personalizado.

Caso saiba o código do papel personalizado que você deseja editar, leia o papel usando o método roles.get() e atualize-o com roles.patch().

Caso contrário, liste todos os papéis com ListRoles() para identificá-lo. O roles.list() retorna uma lista dos papéis que fazem referência ao recurso. Em seguida, atualize-o com roles.patch().

Configure o seguinte parâmetro obrigatório no roles.patch():

• nome do papel, por exemplo, organizations/{ORGANIZATION_ID}/roles/{ROLE_ID}.

Opcionalmente, configure o update_mask para especificar os campos que podem ser atualizados no futuro.

Exemplo

name: '[ROLE_NAME]'
role {
  name: '[ROLE_NAME]'
  title: '[ROLE_TITLE]'`
  description: '[ROLE_DESCRIPTION]'
  included_permissions: '[PERMISSION]'
  included_permissions: '[PERMISSION]'
})"

em que:

• [ROLE_NAME] é o nome do papel. Por exemplo, organizations/123456/roles/appengine.customRoleEditor. Formatos possíveis: roles/{ROLE_NAME}, organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME} ou projects/{PROJECT_ID}/roles/{ROLE_NAME}

Observação: é recomendável deixar o [ROLE_NAME] do papel vazio. Um erro é retornado no método quando os dois nomes não são idênticos e o nome no papel não está vazio.

• [ROLE_TITLE] é o título do papel. Por exemplo, New custom editor.
• [ROLE_DESCRIPTION] é uma descrição do papel. Por exemplo, "Minha nova descrição longa do editor".
• [PERMISSION] é a permissão que você deseja incluir no papel. Por exemplo, storage.objects.update.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para atualizar o papel.
INVALID_ARGUMENT	Não é possível atualizar papéis predefinidos.
INVALID_ARGUMENT	O nome na solicitação ([ROLE_NAME]) precisa ser igual ao nome do papel ([ROLE_NAME]).
INVALID_ARGUMENT	Permissão [PERMISSION] inválida.
ABORTED	Houve alterações simultâneas na política porque os valores de etag não coincidem. Tente refazer a sequência de leitura-modificação-gravação com retirada exponencial.

Alguns papéis predefinidos têm permissões com uso suspenso ou não permitidas em papéis personalizados. Uma falha ocorre quando você tenta criar um papel personalizado com base em um predefinido com essas características.

Como desativar um papel personalizado

É possível desativar um papel personalizado. Quando isso é feito, as vinculações de política relacionadas a ele ficam inativas, o que significa que as permissões desse papel não são válidas, mesmo quando ele é concedido a um usuário.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Clique na lista suspensa "Selecionar um projeto" na parte superior da página.
3. Selecione a sua organização ou projeto.
4. Selecione um papel personalizado e clique em Desativar.

API

Use o método roles.patch() para desativar um papel personalizado.

Se você sabe o código do papel personalizado que deseja desativar, leia-o com o método roles.get(). Altere a propriedade stage dele para DISABLED e chame o método roles.patch() para atualizar esse papel.

Se você não sabe o código do papel personalizado que quer desativar, liste todas as funções usando roles.list() para identificá-lo. O método roles.list() retorna uma lista de todos os papéis que fazem referência ao recurso. Para atualizar o papel, identifique-o, altere a propriedade rolelaunchstage para DISABLED, e chame o método roles.patch().

Para desativar o papel, configure os seguintes campos:

• Defina o nome do papel com a forma completa, organizations/{organization-id}/roles/{role}.
• Em Role, defina stage como DISABLED.
• Defina update_mask como "paths: stage".

Para reativar o papel, siga o mesmo processo descrito acima para desativá-lo. Entretanto, defina a propriedade stage como ALPHA, BETA ou GA.

Exemplo

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
   name: 'organizations/123456/roles/appengine.customRoleEditor'`
   stage: 'DISABLED'
}
update_mask {
 paths:  stage
}

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para atualizar o papel.
INVALID_ARGUMENT	Não é possível atualizar os papéis selecionados.
INVALID_ARGUMENT	O nome na solicitação ([ROLE_NAME]) precisa ser igual ao nome do papel ([ROLE_NAME]).
INVALID_ARGUMENT	Permissão [PERMISSION] inválida.
ABORTED	Houve alterações simultâneas na política. Tente refazer a sequência de leitura-modificação-gravação com retirada exponencial.

Como listar os papéis

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

   
   Todos os papéis personalizados do projeto são listados na página.

API

Com o método roles.list(), liste todos os papéis personalizados definidos em uma organização ou um projeto. Liste também os papéis predefinidos configurando o campo pai na solicitação para "".

Para chamar roles.list(), configure o seguinte campo na solicitação:

• o recurso pai usado para chamar os papéis personalizados, por exemplo:
  • projects/{PROJECT_ID}
  • organizations/{ORGANIZATION_ID}

Para que o resultado contenha as permissões de cada papel, configure o campo view como RoleView::FULL.

Caso queira ver os papéis recentemente excluídos no resultado, defina o valor do campo show_deleted como verdadeiro.

Caso queira listar todos os papéis selecionados, defina o recurso pai como '', uma string vazia.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para listar papéis em {path}.
INVALID_ARGUMENT	Pai {path} inválido. O pai precisa estar no formato organizations/{organization_id}, projects/{project_id} ou vazio.
INVALID_ARGUMENT	Visualização de papel inválida.

Como ver os papéis atribuíveis a recursos

Console

1. Abra a página "IAM" no Console do GCP.

   Abrir a página "IAM"

2. Clique na lista suspensa "Selecionar um projeto" na parte superior da página.
3. Selecione o projeto ou organização dos papéis que deseja ver.
4. Clique em Adicionar.
5. Insira o e-mail do membro em Membros.

Na lista suspensa Papéis são exibidos todos os papéis, incluindo os personalizados, que podem ser concedidos ao membro.

API

Com o QueryGrantableRoles, é retornada uma lista de todos os papéis que um recurso pode se referir. Os papéis sem nenhuma permissão não são incluídos. O único parâmetro obrigatório na solicitação é o nome completo do recurso, por exemplo, //cloudresourcemanager.googleapis.com/projects/my-project. Se preferir, o autor da chamada fornece uma RoleView que determina se Role incluirá todas as permissões que o papel contém na resposta.

Exemplo

full_resource_name: '//automatedtests.googleapis.com/projects/my-project/buckets/bucket1'`

Códigos de erro

Código de erro	Mensagem de status
INVALID_ARGUMENT	{full_resource_name} precisa ser especificado
INVALID_ARGUMENT	{full_resource_name} não atende aos critérios //[a-z0-9.-]/

Como excluir um papel personalizado

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione o papel que você deseja excluir e clique no ícone lixeira, na parte superior da página.

O papel é suspenso e não pode ser usado para criar vinculações de política do IAM. As vinculações existentes permanecem, mas ficam inativas. A exclusão do papel pode ser cancelada em até sete dias. Após esse período, o papel entra em um processo de exclusão permanente que dura 30 dias.

Durante esse processo, o papel e todas as ligações associadas a ele são removidos permanentemente, e não é possível criar um papel novo com o mesmo código. Após a exclusão permanente do papel, 37 dias depois da solicitação de exclusão inicial, um papel novo pode ser criado com o código do que foi excluído.

API

Com roles.delete, você exclui um papel. O papel é suspenso e não pode ser usado para criar vinculações de política do IAM.

Use um destes formatos para name:

• organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}
• projects/{PROJECT_ID}/roles/{ROLE_NAME}

O papel deixa de ser incluído na list, a menos que show_deleted esteja definido na solicitação. Ele tem um valor booleano deleted que, quando definido como verdadeiro, indica que esse papel se encontra nesse estado.

As vinculações existentes permanecem, mas ficam inativas. A exclusão do papel pode ser cancelada em até sete dias. Após esse período, o papel entra em um processo de exclusão permanente que dura 30 dias.

Durante esse processo, o papel e todas as ligações associadas a ele são removidos permanentemente, e não é possível criar um papel novo com o mesmo código. Após a exclusão permanente do papel, 37 dias depois da solicitação de exclusão inicial, um papel novo pode ser criado com o código do que foi excluído.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para excluir o papel em {path}.
FAILED_PRECONDITION	Não é possível excluir o papel {ROLE_NAME}, ele já foi excluído.
FAILED_PRECONDITION	Não é possível excluir um papel {ROLE_NAME} reservado.
INVALID_ARGUMENT	O estado dos papéis selecionados não pode ser excluído.

Como cancelar a exclusão de um papel personalizado

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Localize o papel cuja exclusão quer cancelar e clique no ícone "Mais" no final da linha. Em seguida, clique em Cancelar exclusão.

A exclusão do papel só pode ser cancelada em até sete dias. Após esse período, ele é permanentemente excluído, e todas as vinculações associadas a ele são removidas.

API

Com roles.undelete, o papel volta ao estado anterior.

Use um destes formatos para name:

• organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}
• projects/{PROJECT_ID}/roles/{ROLE_NAME}

A exclusão do papel só pode ser cancelada em até sete dias. Após esse período, ele é permanentemente excluído, e todas as vinculações associadas a ele são removidas.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para cancelar a exclusão do papel em {path}.
FAILED_PRECONDITION	Não é possível cancelar a exclusão de um papel que não foi excluído.
FAILED_PRECONDITION	Não é possível cancelar a exclusão de um papel {ROLE_NAME} reservado.
INVALID_ARGUMENT	Não é possível cancelar a exclusão de papéis predefinidos.