Criar e gerenciar funções personalizadas

Nesta página, descrevemos como criar e gerenciar papéis personalizados de gerenciamento de identidade e acesso (IAM). O gerenciamento de papéis inclui modificar, desativar, listar, excluir e cancelar a exclusão de papéis.

Antes de começar

• Ative a API IAM.

  Funções necessárias para ativar APIs

  Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

  Ativar a API

• Configure a autenticação.

  Selecione a guia para como planeja usar as amostras nesta página:

  Console

  Quando você usa o console Google Cloud para acessar serviços Google Cloud e APIs, não é necessário configurar a autenticação.

  gcloud

  No console do Google Cloud , ative o Cloud Shell.

  Ativar o Cloud Shell

  Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  C#

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

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

     gcloud auth application-default login

     Não é necessário fazer isso se você estiver usando o Cloud Shell.

     Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

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

  C++

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

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

     gcloud auth application-default login

     Não é necessário fazer isso se você estiver usando o Cloud Shell.

     Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

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

  Go

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

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

     gcloud auth application-default login

     Não é necessário fazer isso se você estiver usando o Cloud Shell.

     Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

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

  Java

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

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

     gcloud auth application-default login

     Não é necessário fazer isso se você estiver usando o Cloud Shell.

     Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

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

  Python

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

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

     gcloud auth application-default login

     Não é necessário fazer isso se você estiver usando o Cloud Shell.

     Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

  Para mais informações, consulte Configurar o ADC 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 a CLI gcloud.

  Instale a CLI do Google Cloud.

  Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

• Entenda a Google Cloud hierarquia de recursos.

• Leia Noções básicas sobre papéis personalizados do IAM.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar papéis personalizados, peça ao administrador que conceda a você os seguintes papéis do IAM:

• Para gerenciar papéis para um projeto: administrador de papéis (roles/iam.roleAdmin) no projeto em que você quer gerenciar os papéis
• Para gerenciar papéis para uma organização: administrador de papéis da organização (roles/iam.organizationRoleAdmin) na organização em que você quer gerenciar os papéis

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Ver as permissões disponíveis para projetos, pastas e organizações

É possível criar papéis personalizados para uma organização inteira ou para um projeto específico dessa organização. As permissões disponíveis para papéis personalizados dependem de onde o papel é criado. Por exemplo, se uma permissão só pode ser usada no nível da organização, ela não pode ser incluída em um papel personalizado no nível do projeto.

Para verificar quais permissões estão disponíveis para os papéis personalizados no nível da organização e do projeto, use a CLI gcloud ou a API de gerenciamento de identidade e acesso para listar as permissões disponíveis em uma organização ou projeto específico. Por exemplo, é possível conseguir todas as permissões disponíveis para papéis personalizados criados no projeto.

Algumas permissões podem não estar visíveis para você ou utilizáveis em um papel personalizado, mesmo que sejam suportadas por papéis personalizados. Por exemplo, uma permissão pode não estar disponível para uso em papéis personalizados se você não tiver ativado a API para o serviço.

Para saber mais sobre as permissões que podem ser adicionadas aos papéis personalizados, consulte Permissões compatíveis.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::QueryTestablePermissionsRequest request;
  request.set_full_resource_name(resource);
  int count = 0;
  for (auto& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::move(permission).status();
    std::cout << "Permission successfully retrieved: " << permission->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No testable permissions found in resource: " << resource
              << "\n";
  }
}

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;
    }
}

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: %w", err)
	}

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

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;
import com.google.iam.admin.v1.QueryTestablePermissionsRequest;
import java.io.IOException;

/** View available permissions in a project. */
public class QueryTestablePermissions {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    // Full resource names can take one of the following forms:
    // cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    // cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID
    String fullResourceName = "your-full-resource-name";

    queryTestablePermissions(fullResourceName);
  }

  public static void queryTestablePermissions(String fullResourceName) throws IOException {
    QueryTestablePermissionsRequest queryTestablePermissionsRequest =
        QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();

    try (IAMClient iamClient = IAMClient.create()) {
      QueryTestablePermissionsPagedResponse queryTestablePermissionsPagedResponse =
          iamClient.queryTestablePermissions(queryTestablePermissionsRequest);
      queryTestablePermissionsPagedResponse
          .iterateAll()
          .forEach(permission -> System.out.println(permission.getName()));
    }
  }
}

import os
from typing import List

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2, policy_pb2


def query_testable_permissions(
    project_id: str, permissions: List[str]
) -> policy_pb2.Policy:
    """Tests IAM permissions of the caller.

    project_id: ID or number of the Google Cloud project you want to use.
    permissions: List of permissions to get.
    """

    client = resourcemanager_v3.ProjectsClient()
    request = iam_policy_pb2.TestIamPermissionsRequest()
    request.resource = f"projects/{project_id}"
    request.permissions.extend(permissions)

    permissions_reponse = client.test_iam_permissions(request)
    print(permissions_reponse)
    return permissions_reponse.permissions

POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions

{
  "fullResourceName": "FULL_RESOURCE_NAME"
  "pageSize": PAGE_SIZE,
  "pageToken": "NEXT_PAGE_TOKEN"
}

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/permissions:queryTestablePermissions"

$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/permissions:queryTestablePermissions" | Select-Object -Expand Content

{
  "permissions": [
    {
      "name": "iam.serviceAccountKeys.create",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.delete",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.get",
      "stage": "GA"
    }
  ],
  "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q"
}

acessar os metadados do papel

Antes de criar um papel personalizado, consulte os metadados dos papéis predefinidos e personalizados. Esses metadados incluem o código e as permissões do papel. É possível visualizar os metadados usando o console doGoogle Cloud ou a API IAM.

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

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::GetRoleRequest request;
  request.set_name(name);
  auto response = client.GetRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

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;
    }
}

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: %w", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %w", 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
}

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.GetRoleRequest;
import com.google.iam.admin.v1.Role;
import java.io.IOException;

/** Get role metadata. Specifically, printing out role permissions. */
public class GetRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String roleId = "a unique identifier (e.g. testViewer)";

    getRole(roleId);
  }

  public static void getRole(String roleId) throws IOException {
    GetRoleRequest getRoleRequest = GetRoleRequest.newBuilder().setName(roleId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role role = iamClient.getRole(getRoleRequest);
      role.getIncludedPermissionsList().forEach(permission -> System.out.println(permission));
    }
  }
}

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role


def get_role(project_id: str, role_id: str) -> Role:
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = GetRoleRequest(name=name)
    try