Como ver os papéis atribuíveis a recursos

Antes de conceder um papel de gerenciamento de identidade e acesso (IAM, na sigla em inglês) a um usuário para um recurso, talvez você queira saber quais papéis estão disponíveis para um determinado recurso.

Antes de começar

• Enable the IAM API.

  Enable the API

• Configure a autenticação.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  C++

  Para usar as amostras de C++ nesta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e, em seguida, configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  C#

  Para usar os exemplos .NET desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Go

  Para usar os exemplos Go desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Java

  Para usar os exemplos Java desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  Python

  Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  REST

  Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Funções exigidas

Para ter a permissão necessária para listar papéis atribuíveis, peça ao administrador que conceda a você o papel do IAM Avaliador de segurança (roles/iam.securityReviewer) no recurso com os papéis atribuíveis que você quer listar. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões getIamPolicy para todos os tipos de recursos. Para listar os papéis atribuíveis, é preciso ter a permissão getIamPolicy para o recurso em que você quer listar os papéis atribuíveis. Por exemplo, para listar os papéis atribuíveis de um projeto, você precisa da permissão resourcemanager.projects.getIamPolicy.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Como entender quais papéis são atribuíveis

Um papel será concedido em um recurso ou sobre ele se contiver permissões para esse tipo de recurso. Por exemplo, o papel storage.admin concede permissões às APIs storage.buckets.get e storage.objects.get. Por isso, pode ser concedido nos tipos de recursos buckets de armazenamento e Objetos de armazenamento.

Os papéis também podem ser concedidos "acima" dos tipos de recursos com permissões definidas. Em outras palavras, os papéis para recursos de nível inferior podem ser concedidos em um recurso que está mais acima na hierarquia de recursos do Google Cloud. Por exemplo, o papel storage.admin também pode ser concedido nos níveis do projeto ou da organização, além dos buckets do Storage.

As permissões concedidas por um papel afetam somente recursos no nível especificado ou abaixo, e não recursos de nível superior ou pares. Além disso, quando um papel é concedido em um recurso, somente as permissões aplicáveis ao recurso fornecido são concedidas, independentemente do nome, da descrição ou de outras permissões do papel. Por exemplo, atribuir o papel resourcemanager.organizationAdmin (que concede a permissão resourcemanager.projects.list) a um usuário no nível do projeto concede somente a ele permissões para esse projeto específico. O usuário não terá permissão para listar ou administrar todos os projetos na organização. Da mesma maneira, atribuir o papel compute.admin a uma instância específica do Compute Engine só concede permissões para essa instância, não para outras no projeto.

Como listar papéis atribuíveis

É possível listar os papéis atribuíveis usando o console do Google Cloud, a CLI do Google Cloud, a API IAM ou as bibliotecas de cliente do IAM.

O console do Google Cloud sempre lista todos os papéis atribuíveis do recurso que você está visualizando. A CLI do Google Cloud, a API IAM e as bibliotecas de cliente listam apenas os papéis atribuíveis de APIs ativadas.

Console

Para ver os papéis atribuíveis de um projeto, uma pasta ou uma organização, realize estas ações:

1. No console do Google Cloud, abra a página IAM.

   Acessar a página do IAM

2. Clique em Selecionar um projeto na parte superior da página.

3. Selecione o projeto, a pasta ou a organização com os papéis atribuíveis que você quer visualizar.

4. Clique em CONCEDER ACESSO.

5. Clique em Selecionar papel. Esse menu exibe todos os papéis, incluindo aqueles personalizados, que podem ser concedidos nesse recurso.

Para visualizar os papéis atribuíveis de outros tipos de recurso, realize estas ações:

1. No console do Google Cloud, acesse a página que lista o recurso com os papéis atribuíveis que você quer visualizar.

   Por exemplo, para gerenciar o acesso a uma instância do Compute Engine, acesse a página Instâncias de VM.

   Acessar instâncias de VM

2. Marque a caixa de seleção ao lado do recurso com os papéis atribuíveis que você quer visualizar.

3. Verifique se o painel de informações está visível. Se não estiver, clique em Mostrar painel de informações.

4. Clique em Adicional principal.

5. Clique em Selecionar papel. Esse menu exibe todos os papéis, incluindo aqueles personalizados, que podem ser concedidos nesse recurso.

gcloud

Use o comando gcloud iam list-grantable-roles para retornar uma lista de todos os papéis que podem ser aplicados a determinado recurso.

gcloud iam list-grantable-roles full-resource-name

Dependendo do recurso escolhido, um grande número de papéis pode ser retornado. Para limitar os resultados, especifique uma expressão de filtro.

A resposta será similar a esta:

description: Full control of all Compute Engine resources.
name: roles/compute.admin
title: Compute Admin
---
description: Full control of Compute Engine instance resources.
name: roles/compute.instanceAdmin
title: Compute Instance Admin

# Additional results here...

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C++ do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  for (auto& role : client.QueryGrantableRoles(resource)) {
    if (!role) throw std::move(role).status();
    std::cout << "Role successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No grantable roles found in resource: " << resource << "\n";
  }
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API C# do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

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> ViewGrantableRoles(string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryGrantableRolesRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Roles.QueryGrantableRoles(request).Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine("Title: " + role.Title);
            Console.WriteLine("Name: " + role.Name);
            Console.WriteLine("Description: " + role.Description);
            Console.WriteLine();
        }
        return response.Roles;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Go do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

import (
	"context"
	"fmt"
	"io"

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

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

	request := &iam.QueryGrantableRolesRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Roles.QueryGrantableRoles(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.QueryGrantableRoles: %w", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Found grantable role: %v\n", role.Name)
	}
	return response.Roles, err
}

Java

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Java do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

QueryGrantableRolesRequest request = new QueryGrantableRolesRequest();
request.setFullResourceName(fullResourceName);

QueryGrantableRolesResponse response = service.roles().queryGrantableRoles(request).execute();

for (Role role : response.getRoles()) {
  System.out.println("Title: " + role.getTitle());
  System.out.println("Name: " + role.getName());
  System.out.println("Description: " + role.getDescription());
  System.out.println();
}

Python

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API Python do IAM.

Para autenticar no IAM, configure o Application Default Credentials. Para mais informações, consulte Antes de começar.

def view_grantable_roles(full_resource_name: str) -> None:
    roles = (
        service.roles()
        .queryGrantableRoles(body={"fullResourceName": full_resource_name})
        .execute()
    )

    for role in roles["roles"]:
        if "title" in role:
            print("Title: " + role["title"])
        print("Name: " + role["name"])
        if "description" in role:
            print("Description: " + role["description"])
        print(" ")

REST

O método roles.queryGrantableRoles retorna uma lista de todos os papéis que podem ser concedidos 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.

Método HTTP e URL:

POST https://iam.googleapis.com/v1/roles:queryGrantableRoles

Corpo JSON da solicitação:

{
  "fullResourceName": "FULL_RESOURCE_NAME"
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

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

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

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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

$cred = gcloud auth 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/roles:queryGrantableRoles" | 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:

{
  "roles": [
    {
      "name": "roles/compute.admin",
      "title": "Compute Admin",
      "description": "Full control of all Compute Engine resources."
    },
    {
      "name": "roles/compute.instanceAdmin",
      "title": "Compute Instance Admin (beta)",
      "description": "Full control of Compute Engine instance resources."
    }
  ]
}

Nos exemplos acima, o nome completo do recurso é um URI sem esquema, consistindo em um nome de serviço de API compatível com DNS e um caminho de recurso.

Por exemplo, para retornar todos os papéis que possam ser atribuídos em um projeto, use:

//cloudresourcemanager.googleapis.com/projects/project-id

Os recursos de nível inferior têm um nome totalmente qualificado mais detalhado. Por exemplo, use o seguinte comando para retornar todos os papéis que podem ser atribuídos em uma instância do Compute Engine:

//compute.googleapis.com/projects/project-id/zones/zone-name/instances/instance-id

A seguir

• Conheça os papéis de IAM disponíveis.
• Saiba como escolher os papéis predefinidos mais apropriados.
• Saiba como conceder, alterar e revogar o acesso de um principal.
• Veja exemplos de nomes de recursos para diferentes tipos de recursos.