Nesta página, descrevemos como criar e gerenciar um papel personalizado.
Antes de começar
- Leia Como entender papéis personalizados do IAM e confira informações sobre as permissões exigidas para criar papéis personalizados e práticas recomendadas.
- Se você estiver usando o utilitário de linha de comando
gcloud
, verifique se sua versão é 188.0.0 ou posterior. Para atualizar ogcloud
para a versão 188.0.0, execute o seguinte comando:gcloud components update --version 188.0.0
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. Para conseguir todas as permissões que podem ser aplicadas a um
recurso e aos que estão abaixo dele na hierarquia, use a ferramenta de linha de comando gcloud
,
o Console do Google Cloud ou a API Identity and Access Management. Por
exemplo, é possível receber todas as permissões que se pode aplicar em uma organização e
em projetos nessa organização.
Console
No Console do Cloud, acesse a página Papéis.
Na parte superior da página, selecione o projeto na lista suspensa.
Marque a caixa de seleção do papel de administrador do recurso. Assim, será possível ver todas as permissões aplicáveis a esse recurso. Por exemplo, quando você seleciona o papel Administrador de instâncias do Compute, o painel à direita exibe todas as permissões aplicáveis a uma instância do Compute Engine.
gcloud
Use o comando gcloud iam list-testable-permissions
para ver uma lista de permissões que podem ser aplicadas a um recurso de destino. As permissões retornadas são aquelas que podem ser usadas para a criação de um papel personalizado nesse recurso e em qualquer outro abaixo dele na hierarquia.
No exemplo a seguir, demonstramos como listar permissões testáveis para um recurso de projeto:
gcloud iam list-testable-permissions project-id
project-id
é o ID do projeto no formato de um nome de recurso completo: //cloudresourcemanager.googleapis.com/projects/project-id
, como //cloudresourcemanager.googleapis.com/projects/my-project-id
.
O comando list-testable-permissions
pode retornar centenas de resultados. Para limitar os resultados, especifique uma expressão de filtro.
Abaixo está um exemplo truncado de possíveis resultados:
---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---
Observe que a compatibilidade com um papel personalizado está indicada em cada permissão. Para uma lista completa de permissões compatíveis e não compatíveis, acesse Suporte a permissões de papéis personalizados.
REST
O
método
permissions.queryTestablePermissions
lista todas as permissões que podem ser testadas em um recurso.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
full-resource-name
: um URI que consiste no nome do serviço e no caminho para o recurso. Veja exemplos em Nomes de recursos completos.page-size
: opcional. O número de permissões a serem incluídas na resposta. O valor padrão é 100, e o valor máximo é 1.000. Se o número de permissões for maior que o tamanho da página, a resposta conterá um token de paginação que é possível usar para recuperar a próxima página de resultados.next-page-token
: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de permissões testáveis começará onde a resposta anterior terminou.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions
Corpo JSON da solicitação:
{ "fullResourceName": "full-resource-name" "pageSize": page-size, "pageToken": "next-page-token" }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "permissions": [ { "name": "iam.serviceAccountKeys.create", "stage": "GA" }, { "name": "iam.serviceAccountKeys.delete", "stage": "GA" }, { "name": "iam.serviceAccountKeys.get", "stage": "GA" } ], "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q" }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
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 ID e as permissões do papel. É possível visualizar os metadados usando o Console do Cloud ou a API do IAM.
Para visualizar os metadados do papel, use um dos métodos a seguir:
Console
No Console do Cloud, acesse a página Papéis.
Selecione a organização ou o projeto na lista suspensa na parte superior da página.
Marque a caixa de seleção de um ou mais papéis para visualizar as permissões. O painel do lado direito exibirá as permissões deles, se houver.
Os ícones na coluna Tipo indicam se é um papel personalizado
ou predefinido
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.
gcloud
Use o comando gcloud iam roles describe
para visualizar os metadados de papéis predefinidos e personalizados.
Para visualizar os metadados de um papel predefinido, execute o seguinte comando da gcloud
:
gcloud iam roles describe role-id
role-id
é o ID do papel. Os papéis predefinidos incluem o prefixo role
nos IDs. Por exemplo, roles/iam.roleViewer
.
O exemplo a seguir demonstra a saída do comando describe
quando executado no papel predefinido roles/iam.roleViewer
:
gcloud iam roles describe roles/iam.roleViewer
description: Read access to all custom roles in the project. etag: AA== includedPermissions: - iam.roles.get - iam.roles.list - resourcemanager.projects.get - resourcemanager.projects.getIamPolicy name: roles/iam.roleViewer stage: GA title: Role Viewer
Para visualizar os metadados de um papel personalizado, execute um dos seguintes comandos gcloud
:
Para visualizar os metadados de um papel personalizado criado no nível da organização, execute o seguinte comando:
gcloud iam roles describe --organization=organization-id role-id
Para visualizar os metadados de um papel personalizado criado no nível do projeto, execute o seguinte comando:
gcloud iam roles describe --project=project-id role-id
Cada valor do marcador é descrito a seguir:
organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.role-id
é o ID do papel, excluindo quaisquer prefixos comoprojects/
,organizations/
ouroles/
. Por exemplo:myCompanyAdmin
Para saber mais, consulte a documentação de referência para
gcloud iam roles describe
.
REST
O
método
roles.get
recebe a definição de um papel.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
full-role-id
: o ID completo do papel, incluindo os prefixosorganizations/
,projects/
ouroles/
. Exemplo:organizations/123456789012/roles/myCompanyAdmin
.
Método HTTP e URL:
GET https://iam.googleapis.com/v1/full-role-id
Para enviar a solicitação, expanda uma destas opções:
A resposta contém a definição do papel.
{ "name": "projects/my-project/roles/customRole", "title": "My Custom Role", "description": "My custom role description.", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "etag": "BwWiPg2fmDE=" }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Como criar um papel personalizado
É possível criar um papel personalizado no nível do projeto ou da organização.
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 "Administrador de papéis da organização" ou "Administrador de papéis do IAM".
O tamanho total do título, da descrição e dos nomes de permissão de um papel personalizado é limitado a 64 KB. Caso precise criar um maior, é possível dividir as permissões em vários papéis personalizados. Escolha títulos que mostrem a relação entre os papéis personalizados, como Custom
Admin (1 of 2)
e Custom Admin (2 of 2)
.
Console
Para criar um papel personalizado do zero:
No Console do Cloud, acesse a página Papéis.
Usando a lista suspensa na parte superior da página, selecione a organização ou o projeto em que você quer criar um papel.
Clique em Criar papel.
Insira um Nome, um Título e uma Descrição para o papel.
Clique em Adicionar permissões.
Selecione as permissões que você quer 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 selecionado:
- No Console do Cloud, acesse a página Papéis.
- Selecione a organização ou o projeto em que você quer criar um papel.
- Selecione os papéis em que você quer basear o novo papel personalizado.
- Clique em Criar papel a partir da seleção.
- Insira um Nome, um Título e uma Descrição para o papel.
- Desmarque as permissões que quer excluir do papel.
- Clique em Adicionar permissões para incluir permissões.
- Clique em Criar.
gcloud
Use o comando gcloud iam roles create
para criar novos papéis personalizados. Ele pode ser usado de duas maneiras:
- Com o fornecimento de um arquivo YAML que tenha a definição do papel.
- Com o uso de sinalizações para especificar a definição do papel.
Ao criar um papel personalizado, é necessário determinar se ele se aplica ao nível da organização ou do projeto usando os sinalizadores --organization=organization-id
ou --project=project-id
. Nos exemplos abaixo, são criados papéis personalizados no nível do projeto.
Para criar um papel personalizado usando um arquivo YAML:
Crie um arquivo YAML que tenha a definição do papel personalizado. É preciso que o arquivo seja estruturado da seguinte maneira:
title: role-title description: role-description stage: launch-stage includedPermissions: - permission-1 - permission-2
Cada valor do marcador é descrito a seguir:
role-title
é um título intuitivo para o papel, como"My Company Admin"
.role-description
é uma breve descrição do papel, como"My custom role description"
.launch-stage
indica o estágio de um papel no ciclo de vida do lançamento, comoALPHA
,BETA
ouGA
.permission-1
epermission-2
são permissões a serem incluídas no papel personalizado, comoiam.roles.get
.
Salve o arquivo YAML e execute um dos seguintes comandos:
Para criar um papel personalizado no nível da organização, execute o seguinte comando:
gcloud iam roles create role-id --organization=organization-id \ --file=yaml-file-path
Para criar um papel personalizado no nível do projeto, execute o seguinte comando:
gcloud iam roles create role-id --project=project-id \ --file=yaml-file-path
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.yaml-file-path
é o caminho do local do arquivo YAML que contém a definição do papel personalizado.
Exemplos
No arquivo YAML de exemplo a seguir, demonstramos como criar uma definição de papel:
title: "My Company Admin" description: "My custom role description." stage: "ALPHA" includedPermissions: - iam.roles.get - iam.roles.list
O exemplo a seguir demonstra como criar um papel no nível da organização usando o arquivo YAML:
gcloud iam roles create myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
Se o papel for criado, a saída do comando será semelhante a esta:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
O exemplo a seguir demonstra como criar um papel no nível do projeto usando o arquivo YAML:
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
Se o papel for criado, a saída do comando será semelhante a esta:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
Para criar um papel personalizado usando sinalizações:
Execute um dos seguintes comandos:
Para criar um papel personalizado no nível da organização, execute o seguinte comando:
gcloud iam roles create role-id --organization=organization-id \ --title=role-title --description=role-description \ --permissions=permissions-list --stage=launch-stage
Para criar um papel personalizado no nível do projeto, execute o seguinte comando:
gcloud iam roles create role-id --project=project-id \ --title=role-title --description=role-description \ --permissions=permissions-list --stage=launch-stage
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.role-title
é um título intuitivo para o papel, como"My Company Admin"
.role-description
é uma breve descrição do papel, como"My custom role description."
.permissions-list
contém uma lista de permissões separadas por vírgula que você quer incluir no papel personalizado. Por exemplo,iam.roles.get,iam.roles.list
.launch-stage
indica o estágio de um papel no ciclo de vida do lançamento, comoALPHA
,BETA
ouGA
.
Exemplos
O exemplo a seguir demonstra como criar um papel no nível da organização usando sinalizações:
gcloud iam roles create myCompanyAdmin --organization=123456789012\ --title="My Company Admin" --description="My custom role description." \ --permissions=iam.roles.get,iam.roles.list --stage=ALPHA
Se o papel for criado, a saída do comando será semelhante a esta:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
O exemplo a seguir demonstra como criar um papel no nível do projeto usando sinalizações:
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --title="My Company Admin" --description="My custom role description." \ --permissions=iam.roles.get,iam.roles.list --stage=ALPHA
Se o papel for criado, a saída do comando será semelhante a esta:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
O
método
roles.create
cria um papel personalizado em um projeto ou organização.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
resource-type
: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valorprojects
ouorganizations
.resource-id
: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar.role-id
: o nome do papel, comomyCompanyAdmin
.role-title
: o título legível do papel. Por exemplo,My Company Admin
.role-description
: uma descrição para o papel. Por exemplo,"The company admin role allows company admins to access important resources"
.permission-1
epermission-2
: as permissões que você quer incluir no papel. Por exemplo,storage.objects.update
.launch-stage
: o estágio de lançamento atual do papel. Esse campo pode conter um dos seguintes valores:EAP
,ALPHA
,BETA
,GA
,DEPRECATED
ouDISABLED
.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/resource-type/resource-id/roles
Corpo JSON da solicitação:
{ "roleId": "role-id", "role": { "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage" } }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém o papel que você criou.
{ "name": "projects/myProject/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWox/JbaZw=" }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Como editar um papel personalizado
Read-Modify-Write
Um padrão comum na atualização dos metadados de um recurso, como, 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. O IAM resolve esse problema usando uma propriedade etag
em
papéis personalizados. Essa propriedade é usada para verificar se o papel personalizado foi alterado
desde a última solicitação. Quando você faz uma solicitação ao IAM com um
valor ETag, o IAM compara o valor ETag na solicitação com o
valor ETag existente associado ao papel personalizado. A alteração só é gravada quando
esses valores são correspondentes.
Ao atualizar um papel, primeiro consiga o papel usando roles.get()
, atualize o papel
e, em seguida, grave o papel atualizado usando roles.patch()
. Ao configurar o papel, use o valor etag somente quando o papel correspondente em roles.get()
também contiver um valor etag.
Console
No Console do Cloud, acesse a página Papéis.
Na lista suspensa na parte superior da página, selecione o projeto ou a organização que contém o papel que você quer editar.
Clique em um papel personalizado.
Clique em Editar papel.
Clique em Adicionar permissões para adicionar novas permissões ao papel.
Desmarque as permissões para removê-las do papel.
Clique em Atualizar para salvar o papel editado.
gcloud
Use o comando gcloud iam roles update
para atualizar papéis personalizados. Ele pode ser usado de duas maneiras:
- Por meio de um arquivo YAML contendo a definição atualizada do papel.
- Com sinalizações para especificar a definição atualizada do papel.
Ao atualizar um papel personalizado, especifique se ele se aplica ao nível da organização ou do projeto usando as sinalizações --organization=organization-id
ou --project=project-id
. Nos exemplos abaixo, são criados papéis personalizados no nível do projeto.
Para atualizar um papel personalizado usando um arquivo YAML:
Veja a definição atual do papel executando um dos seguintes comandos:
Para ver a definição de um papel personalizado no nível da organização, execute o seguinte comando:
gcloud iam roles describe role-id --organization=organization-id
Para ver a definição de um papel personalizado no nível do projeto, execute o seguinte comando:
gcloud iam roles describe role-id --project=project-id
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel a ser atualizado, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.
O comando describe
retorna a definição do papel e inclui um valor etag
que identifica exclusivamente a versão atual do papel. O valor etag
precisa ser incluído na definição atualizada do papel para impedir a substituição de alterações de papel simultâneas.
O comando describe
retorna a seguinte saída:
description: role-description etag: etag-value includedPermissions: - permission-1 - permission-2 name: full-role-id stage: launch-stage title: role-title
Cada valor do marcador é descrito a seguir:
role-description
é uma breve descrição do papel, como"My custom role description"
.etag-value
é o identificador exclusivo da versão atual do papel, comoBwVkBkbfr70=
.permission-1
epermission-2
são permissões a serem incluídas no papel personalizado, comoiam.roles.get
.full-role-id
é o ID completo do papel, incluindo qualquer prefixoorganizations/
,projects/
ouroles/
. Por exemplo,organizations/123456789012/roles/myCompanyAdmin.
launch-stage
indica o estágio de um papel no ciclo de vida do lançamento, comoALPHA
,BETA
ouGA
.role-title
é um título intuitivo para o papel, como"My Company Admin"
.
Para atualizar o papel, inclua a definição gerada em um arquivo YAML ou atualize o arquivo YAML original com o valor etag
gerado.
Considere o seguinte arquivo YAML de exemplo, que contém a saída do comando describe
para um papel no nível do projeto e adiciona duas permissões do Cloud Storage:
description: My custom role description. etag: BwVkBkbfr70= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
Salve o arquivo YAML e execute um dos seguintes comandos:
Para atualizar um papel no nível da organização, execute o seguinte comando:
gcloud iam roles update role-id --organization=organization-id \ --file=yaml-file-path
Para atualizar um papel no nível do projeto, execute o seguinte comando:
gcloud iam roles update role-id --project=project-id \ --file=yaml-file-path
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel a ser atualizado, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.yaml-file-path
é o caminho do local do arquivo YAML que contém a definição atualizada do papel personalizado.
Exemplos
O exemplo a seguir demonstra como atualizar um papel no nível da organização usando um arquivo YAML:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
O exemplo a seguir demonstra como atualizar um papel no nível do projeto usando um arquivo YAML:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
Para atualizar um papel personalizado usando sinalizações:
Cada parte de uma definição de papel pode ser atualizada usando uma sinalização.
Consulte o tópico gcloud iam roles update
para ver uma lista de todas as sinalizações possíveis.
Use as sinalizações a seguir para adicionar ou remover permissões:
--add-permissions=permissions
: adiciona ao papel uma ou mais permissões separadas por vírgula.--remove-permissions=permissions
: remove do papel uma ou mais permissões separadas por vírgula.
Como alternativa, basta especificar as novas permissões usando a sinalização --permissions=permissions
e fornecendo uma lista de permissões separadas por vírgulas para substituir a lista atual.
Para atualizar outras partes da definição do papel, execute um dos seguintes comandos:
Para atualizar um papel no nível da organização, execute o seguinte comando:
gcloud iam roles update role-id --organization=organization-id \ --title=role-title --description=role-description \ --stage=launch-stage
Para atualizar um papel no nível do projeto, execute o seguinte comando:
gcloud iam roles update role-id --project=project-id \ --title=role-title --description=role-description \ --stage=launch-stage
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.role-title
é um título intuitivo para o papel, como"My Company Admin"
.role-description
é uma breve descrição do papel, como"My custom role description."
.launch-stage
indica o estágio de um papel no ciclo de vida do lançamento, comoALPHA
,BETA
ouGA
.
Exemplos
O exemplo a seguir demonstra como adicionar permissões a um papel no nível da organização usando sinalizações:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --add-permissions=storage.buckets.get,storage.buckets.list
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
O exemplo a seguir demonstra como adicionar permissões a um papel no nível do projeto usando sinalizações:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --add-permissions=storage.buckets.get,storage.buckets.list
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
O
método
roles.patch
atualiza um papel personalizado em um projeto ou organização.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
Obrigatório:
resource-type
: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valorprojects
ouorganizations
.resource-id
: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar.-
full-role-id
: o ID completo do papel, incluindo os prefixosorganizations/
,projects/
ouroles/
. Exemplo:organizations/123456789012/roles/myCompanyAdmin
.
Recomendação:
etag
: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.
Opcional (defina um ou mais dos seguintes valores):
role-title
: o título legível do papel. Por exemplo,My Company Admin
.role-description
: uma descrição para o papel. Por exemplo,"The company admin role allows company admins to access important resources"
.permission-1
epermission-2
: as permissões que você quer incluir no papel. Por exemplo,storage.objects.update
.launch-stage
: o estágio de lançamento atual do papel. Esse campo pode conter um dos seguintes valores:EAP
,ALPHA
,BETA
,GA
,DEPRECATED
ouDISABLED
.
Método HTTP e URL:
PATCH https://iam.googleapis.com/v1/resource-type/resource-id/roles
Corpo JSON da solicitação:
{ "roleId": "full-role-id", "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage", "etag": "etag" }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém uma definição de papel abreviada que inclui o nome do papel, os campos que você atualizou e uma ETag que identifica a versão atual do papel.
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "title": "My Updated Company Admin", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "stage": "BETA", "etag": "BwWoyDpAxBc=" }
Alguns papéis predefinidos têm permissões obsoletas 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.
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Como desativar um papel personalizado
É possível desativar um papel personalizado. Quando um papel é desativado, as vinculações de política relacionadas a ele ficam inativas e as permissões de atribuição não podem ser aplicadas a um usuário.
Console
No Console do Cloud, acesse a página Papéis.
Clique na lista suspensa "Selecionar um projeto" na parte superior da página.
Selecione a organização ou o projeto.
Selecione um papel personalizado e clique em Desativar.
gcloud
Use o comando gcloud iam roles update
para desativar um papel personalizado definindo seu estágio de inicialização como DISABLED
.
Conforme descrito na guia gcloud da seção Como editar um papel personalizado, é possível atualizar um papel personalizado das seguintes maneiras:
- Por meio de um arquivo YAML contendo a definição atualizada do papel.
- Com sinalizações para especificar a definição atualizada do papel.
A maneira mais fácil de desativar um papel personalizado existente é usar a sinalização --stage
e defini-la como DISABLED
. Execute um dos seguintes comandos:
Para desativar um papel no nível da organização, execute o seguinte comando:
gcloud iam roles update role-id --organization=organization-id \ --stage=DISABLED
Para desativar um papel no nível do projeto, execute o seguinte comando:
gcloud iam roles update role-id --project=project-id \ --stage=DISABLED
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.
Exemplos
O exemplo a seguir demonstra como desativar um papel no nível da organização:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --stage=DISABLED
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
O exemplo a seguir demonstra como desativar um papel no nível do projeto:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --stage=DISABLED
Se o papel for atualizado, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
REST
O
método
roles.patch
permite alterar o estágio de lançamento de um papel personalizado para DISABLED
,
o que desativa o papel.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
resource-type
: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valorprojects
ouorganizations
.resource-id
: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar.-
full-role-id
: o ID completo do papel, incluindo os prefixosorganizations/
,projects/
ouroles/
. Exemplo:organizations/123456789012/roles/myCompanyAdmin
. etag
: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.
Método HTTP e URL:
PATCH https://iam.googleapis.com/v1/resource/resource-id/roles
Corpo JSON da solicitação:
{ "roleId": "full-role-id", "stage": DISABLED, "etag": "etag" }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "stage": "DISABLED", "etag": "BwWoyDpAxBc=" }
C#
Atualize
o campo stage
do papel para DISABLED
.
Go
Atualize
o campo stage
do papel para DISABLED
.
Python
Atualize
o campo stage
do papel para DISABLED
.
Como listar papéis
É possível listar todos os papéis personalizados criados no seu projeto ou organização.
Console
No Console do Cloud, acesse a página Papéis.
Todos os papéis personalizados da organização ou do projeto que você selecionou são listados na página.
gcloud
Use o comando gcloud iam roles list
para listar papéis personalizados e papéis predefinidos de um projeto ou de uma organização.
Para listar papéis personalizados, execute um dos seguintes comandos:
Para listar papéis personalizados no nível da organização, execute o seguinte comando:
gcloud iam roles list --organization=organization-id
Para listar papéis personalizados no nível do projeto, execute o seguinte comando:
gcloud iam roles list --project=project-id
Cada valor do marcador é descrito a seguir:
organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.
Para listar os papéis excluídos, também é possível especificar a sinalização --show-deleted
.
Execute o seguinte comando gcloud
para listar papéis predefinidos:
gcloud iam roles list
REST
O
método
roles.list
lista todos os papéis personalizados em um projeto ou organização.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
resource-type
: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valorprojects
ouorganizations
.resource-id
: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar.role-view
: opcional. As informações a serem incluídas para os papéis retornados. Para incluir as permissões dos papéis, defina este campo comoFULL
. Para excluir as permissões dos papéis, defina este campo comoBASIC
. O valor padrão éBASIC
.page-size
: opcional. O número de papéis a serem incluídos na resposta. O valor padrão é 300 e o valor máximo é 1.000. Se o número de papéis for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.next-page-token
: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de papéis começará onde a solicitação anterior foi finalizada.
Método HTTP e URL:
GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "roles": [ { "name": "projects/my-project/roles/customRole1", "title": "First Custom Role", "description": "Created on: 2020-06-01", "etag": "BwWiPg2fmDE=" }, { "name": "projects/my-project/roles/customRole2", "title": "Second Custom Role", "description": "Created on: 2020-06-07", "etag": "BwWiuX53Wi0=" } ] }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Como excluir um papel personalizado
É possível excluir qualquer papel personalizado no seu projeto ou organização.
Console
No Console do Cloud, acesse a página Papéis.
Selecione o papel que você quer excluir e clique em delete Excluir na parte superior da página.
gcloud
Use o comando gcloud iam roles delete
para excluir um papel personalizado. O papel é suspenso e não pode ser usado para criar vinculações de política do IAM.
Para excluir um papel personalizado, execute um dos seguintes comandos:
Para excluir um papel personalizado no nível da organização, execute o seguinte comando:
gcloud iam roles delete role-id --organization=organization-id
Para excluir um papel personalizado no nível do projeto, execute o seguinte comando:
gcloud iam roles delete role-id --project=project-id
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.
O papel não será incluído em gcloud iam roles list
, a menos que a sinalização --show-deleted
seja incluída. Os papéis excluídos são indicados pelo
bloco deleted: true
em uma resposta list
, como:
--- deleted: true description: My custom role description. etag: BwVkB5NLIQw= name: projects/my-project-id/roles/myCompanyAdmin title: My Company Admin ---
REST
O
método
roles.delete
exclui um papel personalizado em um projeto ou organização.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
full-role-id
: o ID completo do papel, incluindo os prefixosorganizations/
,projects/
ouroles/
. Exemplo:organizations/123456789012/roles/myCompanyAdmin
.
Método HTTP e URL:
DELETE https://iam.googleapis.com/v1/full-role-id
Para enviar a solicitação, expanda uma destas opções:
A resposta contém a definição do papel que foi excluído.
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=", "deleted": true }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
Quando um papel é excluído, as vinculações associadas a ele permanecem, mas estão inativas. É possível recuperar um papel em até sete dias. Durante esse período de sete dias, o papel será mostrado como Excluído no Console do Cloud e não aparecerá nos comandos list
programáticos (a menos que showDeleted
esteja definido na solicitação).
Após sete dias, o papel será excluído permanentemente. Até aqui, o papel não conta mais para o limite de 300 papéis personalizados por organização ou 300 papéis personalizados por projeto.
O processo de exclusão permanente dura 30 dias. Durante esse período, o papel e todas as vinculações associadas são permanentemente removidos e não é possível criar um papel novo com o mesmo ID.
Depois que o papel for excluído permanentemente, 37 dias após a solicitação de exclusão inicial, será possível criar um novo usando o mesmo ID.
Como cancelar a exclusão de um papel personalizado
Cancelar a exclusão de um papel faz com que ele retorne ao estado anterior.
Só é possível cancelar a exclusão de papéis em até sete dias após a exclusão. Após esse período, o papel será permanentemente excluído e todas as vinculações associadas a ele serão removidas.
Console
No Console do Cloud, acesse a página Papéis.
Localize o papel para o cancelamento da exclusão e clique no ícone no final da linha. Em seguida, clique em Cancelar exclusão.
gcloud
Use o comando gcloud iam roles undelete
para cancelar a exclusão de um papel personalizado.
Para cancelar a exclusão de um papel personalizado, execute um dos seguintes comandos:
Para cancelar a exclusão de um papel personalizado no nível da organização, execute o seguinte comando:
gcloud iam roles undelete role-id --organization=organization-id
Para cancelar a exclusão de um papel personalizado no nível do projeto, execute o seguinte comando:
gcloud iam roles undelete role-id --project=project-id
Cada valor do marcador é descrito a seguir:
role-id
é o nome do papel, comomyCompanyAdmin
.organization-id
é o ID numérico da organização, como123456789012
.project-id
é o nome do projeto, comomy-project-id
.
Exemplos
O exemplo a seguir demonstra como cancelar a exclusão de um papel personalizado no nível da organização:
gcloud iam roles undelete myCompanyAdmin --organization=123456789012
Se a exclusão do papel for cancelada, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
O exemplo a seguir demonstra como cancelar a exclusão de um papel personalizado no nível do projeto:
gcloud iam roles undelete myCompanyAdmin --project=my-project-id
Se a exclusão do papel for cancelada, a saída do comando será semelhante a esta:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
O
método
roles.undelete
cancela a exclusão de um papel personalizado em um projeto ou organização.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
full-role-id
: o ID completo do papel, incluindo os prefixosorganizations/
,projects/
ouroles/
. Exemplo:organizations/123456789012/roles/myCompanyAdmin
. etag
: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/full-role-id:undelete
Corpo JSON da solicitação:
{ "etag": "etag" }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém a definição do papel que teve a exclusão cancelada.
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=" }
C#
Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para C#.
Go
Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Go.
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do IAM: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API IAM para Python.
A seguir
- Saiba como atribuir papéis aos membros.
- Saiba mais sobre atribuições condicionais de papéis para conceder papéis somente se condições específicas forem atendidas.