Como criar e gerenciar papéis personalizados

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.

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 os recursos que estão abaixo dele na hierarquia, use a ferramenta 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

1. No Console do Cloud, acesse a página Papéis.

   Acessar 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, 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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/permissions:queryTestablePermissions

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/permissions:queryTestablePermissions" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Permission> QueryTestablePermissions(
        string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	request := &iam.QueryTestablePermissionsRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Permissions.QueryTestablePermissions(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Permissions.QueryTestablePermissions: %v", err)
	}
	for _, p := range response.Permissions {
		fmt.Fprintf(w, "Found permissions: %v", p.Name)
	}
	return response.Permissions, nil
}

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.

Veja no GitHub Feedback

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

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

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Selecione a organização ou o projeto na lista suspensa na parte superior da página.

3. 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 (í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.

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:

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:

• 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, como 123456789012.
• project-id é o nome do projeto, como my-project-id.
• role-id é o ID do papel, excluindo quaisquer prefixos como projects/, organizations/ ou roles/. 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 prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  Observação: se você não souber o ID completo do papel, use o método roles.list para listar todos os papéis personalizados em uma organização, um projeto ou todos os papéis predefinidos do IAM. O ID completo do papel está no campo name do corpo da resposta.

Método HTTP e URL:

GET https://iam.googleapis.com/v1/full-role-id

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o comando a seguir:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/full-role-id

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/full-role-id" | Select-Object -Expand Content

APIs Explorer (navegador)

Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role GetRole(string name)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %v", err)
	}
	fmt.Fprintf(w, "Got role: %v\n", role.Name)
	for _, permission := range role.IncludedPermissions {
		fmt.Fprintf(w, "Got permission: %v\n", permission)
	}
	return role, nil
}

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.

Veja no GitHub Feedback

def get_role(name):
    """Gets a role."""

    # pylint: disable=no-member
    role = service.roles().get(name=name).execute()
    print(role['name'])
    for permission in role['includedPermissions']:
        print(permission)

Como criar um papel personalizado

É possível criar um papel personalizado no nível do projeto ou da organização.

Observação: não é possível definir papéis personalizados no nível da pasta. Se você precisar usar um papel personalizado dentro de uma pasta, defina-o no nível 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 de administrador de papéis da organização ou de papéis de 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).

Cada papel personalizado pode ter um estágio de lançamento. Os estágios de lançamento são informativos e ajudam a monitorar se cada papel está pronto para uso geral. Para mais informações sobre as etapas de lançamento, consulte Como testar e implantar.

Console

Para criar um papel personalizado do zero:

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Usando a lista suspensa na parte superior da página, selecione a organização ou o projeto em que você quer criar um papel.

3. Clique em Criar papel.

4. Insira um Nome, Título, Descrição e Estágio de lançamento do papel para o papel. Após a criação do papel, não é possível alterar o nome dele.

5. Clique em Adicionar permissões.

6. 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:

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Selecione a organização ou o projeto em que você quer criar um papel.
3. Selecione os papéis em que você quer basear o novo papel personalizado.
4. Clique em Criar papel a partir da seleção.
5. Insira um Nome, Título, Descrição e Estágio de lançamento do papel para o papel. Após a criação do papel, não é possível alterar o nome dele.
6. Desmarque as permissões que quer excluir do papel.
7. Clique em Adicionar permissões para incluir permissões.
8. 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, como ALPHA, BETA ou GA.
• permission-1 e permission-2 são permissões a serem incluídas no papel personalizado, como iam.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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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, como ALPHA, BETA ou GA.

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 valor projects ou organizations.
• 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, como myCompanyAdmin.
• 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 e permission-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 ou DISABLED.

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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource-type/resource-id/roles

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role CreateRole(string name, string projectId, string title,
        string description, IList<string> permissions, string stage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = new Role
        {
            Title = title,
            Description = description,
            IncludedPermissions = permissions,
            Stage = stage
        };
        var request = new CreateRoleRequest
        {
            Role = role,
            RoleId = name
        };
        role = service.Projects.Roles.Create(request,
            "projects/" + projectId).Execute();
        Console.WriteLine("Created role: " + role.Name);
        return role;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// createRole creates a custom role.
func createRole(w io.Writer, projectID, name, title, description, stage string, permissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	request := &iam.CreateRoleRequest{
		Role: &iam.Role{
			Title:               title,
			Description:         description,
			IncludedPermissions: permissions,
			Stage:               stage,
		},
		RoleId: name,
	}
	role, err := service.Projects.Roles.Create("projects/"+projectID, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Create: %v", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

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.

Veja no GitHub Feedback

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

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.

Observação: Ao modificar um papel personalizado adicionando ou removendo qualquer uma das seguintes permissões: resourcemanager.organizations.get, resourcemanager.folders.get e resourcemanager.projects.get, a alteração no papel personalizado pode levar até 24 horas para entrar em vigor para as APIs Cloud Resource Manager organizations.search e folders.search. A API projects.list também está sujeita a esse atraso para chamadas de API que não fornecem um filtro com a especificação de ID e tipo pai. Esse atraso ocorre porque essas permissões envolvem a funcionalidade de pesquisa e podem levar até 24 horas entre as reconstruções do índice de pesquisa.

Console

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. 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.

3. Clique em um papel personalizado.

4. Clique em Editar papel.

5. Para atualizar os metadados do papel, edite o Título, a Descrição ou o Estágio de lançamento do papel.

6. Para atualizar as permissões do papel, faça o seguinte:

   1. Clique em Adicionar permissões para adicionar novas permissões ao papel.
   2. Desmarque as permissões para removê-las do papel.

7. 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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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, como BwVkBkbfr70=.
• permission-1 e permission-2 são permissões a serem incluídas no papel personalizado, como iam.roles.get.
• full-role-id é o ID completo do papel, incluindo qualquer prefixo organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.
• launch-stage indica o estágio de um papel no ciclo de vida do lançamento, como ALPHA, BETA ou GA.
• 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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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, como ALPHA, BETA ou GA.

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 valor projects ou organizations.
• 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 prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  Observação: se você não souber o ID completo do papel, use o método roles.list para listar todos os papéis personalizados em uma organização, um projeto ou todos os papéis predefinidos do IAM. O ID completo do papel está no campo name do corpo da resposta.

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 e permission-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 ou DISABLED.

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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource-type/resource-id/roles

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// editRole modifies a custom role.
func editRole(w io.Writer, projectID, name, newTitle, newDescription, newStage string, newPermissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %v", err)
	}
	role.Title = newTitle
	role.Description = newDescription
	role.IncludedPermissions = newPermissions
	role.Stage = newStage
	role, err = service.Projects.Roles.Patch(resource, role).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Patch: %v", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

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.

Veja no GitHub Feedback

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

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

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Clique na lista suspensa "Selecionar um projeto" na parte superior da página.

3. Selecione a organização ou o projeto.

4. 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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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 valor projects ou organizations.
• 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 prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  Observação: se você não souber o ID completo do papel, use o método roles.list para listar todos os papéis personalizados em uma organização, um projeto ou todos os papéis predefinidos do IAM. O ID completo do papel está no campo name do corpo da resposta.
• 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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource/resource-id/roles

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource/resource-id/roles" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

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.

Acessar 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, como 123456789012.
• project-id é o nome do projeto, como my-project-id.

Para listar os papéis excluídos, também é possível especificar a sinalização --show-deleted.

Execute o seguinte comando 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 valor projects ou organizations.
• 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 como FULL. Para excluir as permissões dos papéis, defina este campo como BASIC. 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.

Observação: para listar todos os papéis predefinidos do IAM, omita os campos resource-type e resource-id. Exemplo: GET https://iam.googleapis.com/v1/roles.

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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o comando a seguir:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token" | Select-Object -Expand Content

APIs Explorer (navegador)

Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Role> ListRoles(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.Roles.List("projects/" + projectId)
            .Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine(role.Name);
        }
        return response.Roles;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID string) ([]*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	response, err := service.Projects.Roles.List("projects/" + projectID).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.List: %v", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Listing role: %v\n", role.Name)
	}
	return response.Roles, nil
}

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.

Veja no GitHub Feedback

def list_roles(project_id):
    """Lists roles."""

    # pylint: disable=no-member
    roles = service.roles().list(
        parent='projects/' + project_id).execute()['roles']
    for role in roles:
        print(role['name'])

Como excluir um papel personalizado

É possível excluir qualquer papel personalizado no seu projeto ou organização.

Importante: os papéis excluídos são suspensos e não podem ser usados para criar novas vinculações de política do IAM. As vinculações atuais que incluem o papel excluído não serão mais efetivas.

Console

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Selecione o papel que você quer excluir e clique em 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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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 prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  Observação: se você não souber o ID completo do papel, use o método roles.list para listar todos os papéis personalizados em uma organização, um projeto ou todos os papéis predefinidos do IAM. O ID completo do papel está no campo name do corpo da resposta.

Método HTTP e URL:

DELETE https://iam.googleapis.com/v1/full-role-id

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o comando a seguir:

curl -X DELETE \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/full-role-id

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method DELETE `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/full-role-id" | Select-Object -Expand Content

APIs Explorer (navegador)

Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return fmt.Errorf("iam.NewService: %v", err)
	}

	_, err = service.Projects.Roles.Delete("projects/" + projectID + "/roles/" + name).Do()
	if err != nil {
		return fmt.Errorf("Projects.Roles.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted role: %v", name)
	return nil
}

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.

Veja no GitHub Feedback

def delete_role(name, project):
    """Deletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().delete(
        name='projects/' + project + '/roles/' + name).execute()

    print('Deleted role: ' + name)
    return role

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.

Observação: os papéis personalizados criados em um projeto não contam para o limite de papéis personalizados da organização.

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

1. No Console do Cloud, acesse a página Papéis.

   Acessar a página "Papéis"

2. Localize o papel que você quer cancelar a exclusão e clique no ícone de mais 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, como myCompanyAdmin.
• organization-id é o ID numérico da organização, como 123456789012.
• project-id é o nome do projeto, como my-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 prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  Observação: se você não souber o ID completo do papel, use o método roles.list para listar todos os papéis personalizados em uma organização, um projeto ou todos os papéis predefinidos do IAM. O ID completo do papel está no campo name do corpo da resposta.
• 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:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/full-role-id:undelete

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALScomo o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/full-role-id:undelete" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

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#.

Veja no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role UndeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

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.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	request := &iam.UndeleteRoleRequest{}
	role, err := service.Projects.Roles.Undelete(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Undelete: %v", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

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.

Veja no GitHub Feedback

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role

A seguir

• Saiba como atribuir papéis aos membros.
• Saiba como usar o recomendador do IAM para reduzir o escopo das permissões dos seus membros.
• Saiba mais sobre atribuições condicionais de papéis para conceder papéis somente se condições específicas forem atendidas.