Crea y administra roles personalizados

En esta página, se describe cómo crear y administrar roles personalizados de la administración de identidades y accesos (IAM). La administración de roles incluye la modificación, la inhabilitación, la enumeración, la eliminación y la recuperación de roles.

Antes de comenzar

• Enable the IAM API.

  Enable the API

• Configura la autenticación.

  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 las muestras de .NET de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

  Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

  C++

  Para usar las muestras de C++ de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

  Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

  Go

  Para usar las muestras de Go de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

  Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

  Java

  Para usar las muestras de Java de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

  Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

  Python

  Para usar las muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

  Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

  REST

  Para usar las muestras de la API de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a la CLI de gcloud.

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

  gcloud init

  Si deseas obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud.

• Comprende la jerarquía de recursos de Google Cloud.

• Lee Comprende los roles personalizados de IAM.

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar roles personalizados, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Para administrar roles en un proyecto: administrador de roles (roles/iam.roleAdmin) en el proyecto en el que deseas administrar roles
• Para administrar roles de una organización: administrador de roles de la organización (roles/iam.organizationRoleAdmin) en la organización en la que deseas administrar roles

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Visualiza los permisos disponibles para los proyectos, las carpetas y las organizaciones

Puedes crear roles personalizados para una organización completa o para un proyecto específico de esa organización. Los permisos que están disponibles para los roles personalizados dependen de dónde crees el rol. Por ejemplo, si un permiso solo se puede usar a nivel de la organización, no puedes incluir ese permiso en un rol personalizado a nivel del proyecto.

A fin de verificar qué permisos están disponibles para los roles personalizados a nivel de proyecto y de la organización, puedes usar la CLI de gcloud o la API de Identity and Access Management a fin de obtener una lista de los permisos que están disponibles en una organización o un proyecto específicos. Por ejemplo, puedes obtener todos los permisos disponibles para los roles personalizados que se crean en el proyecto.

Es posible que algunos permisos no sean visibles para ti o no se puedan usar en un rol personalizado, incluso si son compatibles con roles personalizados. Por ejemplo, puede que el uso de un permiso no esté habilitado en roles personalizados si no habilitaste la API para el servicio.

Para obtener más información sobre los permisos que puedes agregar a los roles personalizados, consulta Permisos admitidos.

gcloud

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

2. Usa el comando gcloud iam list-testable-permissions a fin de obtener una lista de permisos disponibles para roles personalizados en una organización o proyecto específico. En la respuesta, se enumeran los permisos que puedes usar en los roles personalizados de esa organización o proyecto.

   A fin de enumerar los permisos que están disponibles en roles personalizados para una organización o un proyecto, ejecuta este comando:

   gcloud iam list-testable-permissions FULL_RESOURCE_NAME \
       --filter="customRolesSupportLevel!=NOT_SUPPORTED"

   Reemplaza FULL_RESOURCE_NAME por uno de los siguientes valores:

   • Proyecto: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID (por ejemplo, //cloudresourcemanager.googleapis.com/projects/my-project)

   • Organización: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID (por ejemplo, //cloudresourcemanager.googleapis.com/organizations/123456789012)

   Los resultados indican si cada permiso es compatible con roles personalizados. Los permisos que no tienen un campo customRolesSupportLevel son totalmente compatibles.

   El comando list-testable-permissions puede mostrar cientos de resultados. En este ejemplo parcial, se muestra el formato de cada resultado:

   ---
   name: appengine.applications.create
   stage: GA
   ---
   customRolesSupportLevel: TESTING
   name: appengine.applications.disable
   stage: GA
   ---
   name: appengine.applications.get
   stage: GA
   ---
   name: appengine.applications.update
   stage: GA
   ---
   name: appengine.instances.delete
   stage: GA
   ---
   name: appengine.instances.get
   stage: GA
   ---
   

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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
}

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

    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

REST

El método permissions.queryTestablePermissions permite enumerar los permisos disponibles en una organización o proyecto.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• FULL_RESOURCE_NAME: Un URI que consiste en el nombre del servicio y la ruta al recurso. Para ver ejemplos, consulta Nombres completos de recursos.
• PAGE_SIZE: Opcional Es la cantidad de permisos que se incluirán en la respuesta. El valor predeterminado es 100 y el valor máximo es 1,000. Si la cantidad de permisos es mayor que el tamaño de la página, la respuesta contiene un token de paginación que puedes usar para consultar la siguiente página de resultados.
• NEXT_PAGE_TOKEN: Opcional Es el token de paginación que se mostró en una respuesta anterior de este método. Si se especifica, la lista de permisos que se pueden probar comenzará desde el punto en que finalizó la solicitud anterior.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la lista de permisos.

Nota: Los permisos que no tienen un campo customRolesSupportLevel son totalmente compatibles con las funciones personalizadas.

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

Obtén los metadatos del rol

Antes de crear un rol personalizado, es posible que desees obtener los metadatos para los roles predefinidos y personalizados. Los metadatos de rol incluyen el ID de rol y los permisos contenidos en el rol. Puedes ver los metadatos con la consola de Google Cloud o la API de IAM.

Para ver los metadatos de rol, usa uno de los siguientes métodos:

Console

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. Selecciona tu organización o proyecto de la lista desplegable en la parte superior de la página.

3. Selecciona la casilla de verificación de uno o más roles para ver los permisos de rol. El panel lateral derecho muestra los permisos contenidos en los roles, si los hay.

Los íconos de la columna Tipo (Type) indican si es un rol personalizado (ícono “fábrica”) o un rol predefinido (ícono hexagonal).

Si deseas buscar todas las funciones que incluyen un permiso específico, escribe el nombre del permiso en el cuadro Filtro en la parte superior de la lista de funciones.

gcloud

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

2. Usa el comando gcloud iam roles describe para ver los metadatos de los roles predefinidos y personalizados.

   Para ver los metadatos de un rol predefinido, ejecuta el siguiente comando de :

   gcloud iam roles describe ROLE_ID

   ROLE_ID es el ID del rol. Los roles predefinidos incluyen el prefijo role en sus ID, por ejemplo, roles/iam.roleViewer.

   En el siguiente ejemplo, se demuestra el resultado del comando describe cuando se ejecuta en el rol 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 ver los metadatos de un rol personalizado, ejecuta uno de los siguientes comandos :

   • Para ver los metadatos de un rol personalizado creada a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles describe --organization=ORGANIZATION_ID ROLE_ID

   • Para ver los metadatos de un rol personalizado creado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles describe --project=PROJECT_ID ROLE_ID

   Cada valor de marcador de posición se describe a continuación:

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   • ROLE_ID es el ID del rol, sin incluir los prefijos como projects/, organizations/ o roles/. Por ejemplo, myCompanyAdmin.

   Para obtener más información, consulta la documentación de referencia de gcloud iam roles describe.

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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
}

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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:
        role = client.get_role(request)
        print(f"Retrieved role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

REST

El método roles.get permite obtener la definición de un rol.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• ROLE_NAME: Es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin

Método HTTP y URL:

GET https://iam.googleapis.com/v1/ROLE_NAME

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

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

Explorador de APIs (navegador)

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la definición de la función.

{
  "name": "projects/my-project/roles/customRole",
  "title": "My Custom Role",
  "description": "My custom role description.",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "etag": "BwWiPg2fmDE="
}

Crea un rol personalizado

Puedes crear un rol personalizado a nivel del proyecto o de la organización.

Nota: No puedes definir roles personalizados a nivel de la carpeta. Si necesitas usar un rol personalizado dentro de una carpeta, define el rol a nivel de organización.

Un rol personalizado a nivel de la organización puede incluir cualquiera de los permisos de IAM compatibles con los roles personalizados. Un rol personalizado a nivel del proyecto puede contener cualquier permiso admitido, excepto los permisos que solo se pueden usar a nivel de la organización o carpeta, como resourcemanager.organizations.get. Si intentas agregar estos permisos a un rol personalizada a nivel de proyecto, verás un mensaje de error:

Console

Se muestra un mensaje que advierte que no es aplicable para roles personalizados a nivel de proyecto. De forma automática, se anulará la selección del permiso en la lista de permisos incluidos y podrás continuar con la creación del rol.

gcloud

Se devuelve el siguiente mensaje de error: INVALID_ARGUMENT: Permission PERMISSION is not valid. El rol personalizado no se creará hasta que quites el permiso de la definición del rol y vuelvas a intentar realizar la operación.

API de REST

Se devuelve el siguiente mensaje de error: Permission PERMISSION is not valid junto con un código de error HTTP 400 y el estado de INVALID_ARGUMENT. El rol personalizado no se creará hasta que quites el permiso de la definición del rol y vuelvas a intentar realizar la operación.

Cada rol personalizado puede contener hasta 3,000 permisos. Además, el tamaño total máximo del título, la descripción y los nombres de permisos para un rol personalizado es de 64 KB. Si necesitas crear un rol personalizado más grande, puedes dividir los permisos en varios roles personalizados. Elige títulos de roles que muestren la relación entre los roles personalizados, como Custom Admin (1 of 2) y Custom Admin (2 of 2).

Cada rol personalizado puede tener una etapa de lanzamiento. La mayoría de las etapas de lanzamiento son informativas y te ayudan a realizar un seguimiento sobre cada rol a fin de determinar si está lista para el uso generalizado. Además, la etapa de lanzamiento DISABLED te permite inhabilitar un rol personalizado. Para obtener más información sobre las etapas de lanzamiento, consulta Ejecuta pruebas y realiza la implementación.

Console

Algunos roles predefinidos contienen permisos obsoletos o permisos que, de otra manera, no están permitidos en los roles personalizados. Si intentas crear un rol personalizado basado en uno de estos roles predefinidos, el rol personalizado omitirá los permisos obsoletos y restringidos.

Para crear un nuevo rol personalizado desde cero:

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. En la lista desplegable de la parte superior de la página, selecciona la organización o el proyecto en el que deseas crear un rol.

3. Haz clic en Crear rol.

4. Escribe un Título, una Descripción, un ID y una Etapa de lanzamiento del rol para el rol. El ID del rol no se puede cambiar después de que este se crea.

5. Haz clic en Agregar permisos.

6. Selecciona los permisos que desees incluir en el rol y haz clic en Agregar permisos. Usa las listas desplegables Todos los servicios y Todos los tipos para filtrar y seleccionar permisos por servicios y tipos.

Crea un rol personalizado según un rol predefinido existente:

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. Selecciona la organización o el proyecto en el que deseas crear un rol.
3. Selecciona los roles en los que deseas basar el nuevo rol personalizado.
4. Haz clic en Crear función de selección.
5. Escribe un Título, una Descripción, un ID y una Etapa de lanzamiento del rol para el rol. El ID del rol no se puede cambiar después de que este se crea.
6. Desmarca los permisos que deseas excluir de la función.
7. Haz clic en Agregar permisos para incluir cualquier permiso.
8. Haz clic en Crear.

gcloud

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

2. Usa el comando gcloud iam roles create para crear nuevos roles personalizados. Puede utilizar este comando de dos maneras:

   • Con un archivo YAML que contiene la definición del rol.

   • Con marcas para especificar la definición del rol

   Cuando crees un rol personalizado, debes especificar si se aplica a nivel de la organización o a nivel del proyecto mediante las marcas --organization=ORGANIZATION_ID o --project=PROJECT_ID. En cada uno de los siguientes ejemplos, se crea un rol personalizado a nivel del proyecto.

   Un rol personalizado solo puede contener permisos que se admiten en los roles personalizados. Si el rol personalizado contiene otros permisos, el comando falla.

   Para crear un rol personalizado con un archivo YAML, haz lo siguiente:

   Cree un archivo YAML que contenga la definición de su función personalizada. El archivo debe estar estructurado de la siguiente manera:

   title: ROLE_TITLE
   description: ROLE_DESCRIPTION
   stage: LAUNCH_STAGE
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_TITLE es un título descriptivo para el rol, como "My Company Admin".

   • ROLE_DESCRIPTION es una descripción breve del rol, como "My custom role description".

   • LAUNCH_STAGE indica la etapa en la que se encuentra un rol en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

   • PERMISSION_1 y PERMISSION_2 son permisos para incluir en el rol personalizado, como iam.roles.get. No puedes usar caracteres comodín (*) en los nombres de permisos.

   Guarda el archivo YAML y, luego, ejecuta uno de los siguientes comandos:

   • Para crear un rol personalizado a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

   • Para crear un rol personalizado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles create ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   • YAML_FILE_PATH es la ruta a la ubicación de tu archivo YAML que contiene la definición del rol personalizado.

   Ejemplos

   En el siguiente archivo YAML de ejemplo, se muestra cómo crear una definición de rol:

   title: "My Company Admin"
   description: "My custom role description."
   stage: "ALPHA"
   includedPermissions:
   - iam.roles.get
   - iam.roles.list

   En el siguiente ejemplo, se muestra cómo crear un rol a nivel de la organización mediante el archivo YAML:

   gcloud iam roles create myCompanyAdmin --organization=123456789012 \
       --file=my-role-definition.yaml

   Si el rol se creó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo crear un rol a nivel de proyecto mediante el archivo YAML:

   gcloud iam roles create myCompanyAdmin --project=my-project \
       --file=my-role-definition.yaml

   Si el rol se creó con éxito, el resultado del comando es similar al siguiente:

   Created role [myCompanyAdmin].
   description: My custom role description.
   etag: BwVkBX0sQD0=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

   Para crear un rol personalizado mediante marcas, haz lo siguiente:

   Ejecuta uno de los siguientes comandos:

   • Para crear un rol personalizado a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

   • Para crear un rol personalizado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles create ROLE_ID --project=PROJECT_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   • ROLE_TITLE es un título descriptivo para el rol, como "My Company Admin".

   • ROLE_DESCRIPTION es una descripción breve del rol, como "My custom role description.".

   • PERMISSIONS_LIST contiene una lista de permisos separada por comas que deseas incluir en el rol personalizado. Por ejemplo: iam.roles.get,iam.roles.list. No puedes usar caracteres comodín (*) en los nombres de permisos.

   • LAUNCH_STAGE indica la etapa en la que se encuentra un rol en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo crear un rol a nivel de la organización mediante marcas:

   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

   Si el rol se creó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo crear un rol a nivel del proyecto mediante marcas:

   gcloud iam roles create myCompanyAdmin --project=my-project \
       --title="My Company Admin" --description="My custom role description." \
       --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

   Si el rol se creó con éxito, el resultado del comando es similar al siguiente:

   Created role [myCompanyAdmin].
   description: My custom role description.
   etag: BwVkBX0sQD0=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& parent, std::string const& role_id,
   std::vector<std::string> const& included_permissions) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::CreateRoleRequest request;
  request.set_parent("projects/" + parent);
  request.set_role_id(role_id);
  google::iam::admin::v1::Role role;
  role.set_stage(google::iam::admin::v1::Role::GA);
  for (auto const& permission : included_permissions) {
    *role.add_included_permissions() = permission;
  }
  *request.mutable_role() = role;
  auto response = client.CreateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.CreateRoleRequest;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import java.io.IOException;
import java.util.Arrays;

/** Create role. */
public class CreateRole {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String title = "a title for your role (e.g. IAM Role Viewer)";
    String description = "a description of the role";
    Iterable<String> includedPermissions =
        Arrays.asList("roles/iam.roleViewer", "roles/logging.viewer");

    createRole(projectId, title, description, includedPermissions, roleId);
  }

  public static void createRole(
      String projectId,
      String title,
      String description,
      Iterable<String> includedPermissions,
      String roleId)
      throws IOException {
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setTitle(title)
            .setDescription(description)
            .addAllIncludedPermissions(includedPermissions)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.BETA);
    CreateRoleRequest createRoleRequest =
        CreateRoleRequest.newBuilder()
            .setParent("projects/" + projectId)
            .setRoleId(roleId)
            .setRole(roleBuilder)
            .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 result = iamClient.createRole(createRoleRequest);
      System.out.println("Created role: " + result.getName());
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

from typing import List, Optional

from google.api_core.exceptions import AlreadyExists, FailedPrecondition
from google.cloud.iam_admin_v1 import CreateRoleRequest, IAMClient, Role


def create_role(
    project_id: str, role_id: str, permissions: List[str], title: Optional[str] = None
) -> Role:
    """
    Creates iam role with given parameters.
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role
        permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"]
        title: title for iam role. role_id will be used in case of None

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()

    parent = f"projects/{project_id}"

    request = CreateRoleRequest(
        parent=parent,
        role_id=role_id,
        role=Role(title=title, included_permissions=permissions),
    )
    try:
        role = client.create_role(request)
        print(f"Created iam role: {role_id}: {role}")
        return role
    except AlreadyExists:
        print(f"Role with id [{role_id}] already exists, take some actions")
    except FailedPrecondition:
        print(
            f"Role with id [{role_id}] already exists and in deleted state, take some actions"
        )

REST

El método roles.create permite crear un rol personalizado en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• RESOURCE_TYPE: Es el tipo de recurso cuyos roles personalizados quieres administrar. Usa el valor projects o organizations.
• RESOURCE_ID: es el ID del proyecto o de la organización cuyos roles personalizados deseas administrar. Los ID de proyecto son strings alfanuméricas, como my-project. Los ID de la organización son numéricos, como 123456789012.
• ROLE_ID: Es el nombre del rol, como myCompanyAdmin.
• ROLE_TITLE: Es el título legible para el rol. Por ejemplo, My Company Admin.
• ROLE_DESCRIPTION: Es una descripción para el rol. Por ejemplo, "The company admin role allows company admins to access important resources".

• PERMISSION_1 y PERMISSION_2: Son los permisos que deseas incluir en el rol. Por ejemplo, storage.objects.update. No puedes usar caracteres comodín (*) en los nombres de permisos.

  Un rol personalizado solo puede contener permisos que se admiten en los roles personalizados. Si el rol personalizado contiene otros permisos, la solicitud falla.

• LAUNCH_STAGE: Es la etapa de lanzamiento actual del rol. Este campo puede contener uno de los siguientes valores: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Método HTTP y URL:

POST https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

Cuerpo JSON de la solicitud:

{
  "roleId": "ROLE_ID",
  "role": {
    "title": "ROLE_TITLE",
    "description": "ROLE_DESCRIPTION",
    "includedPermissions": [
      "PERMISSION_1",
      "PERMISSION_2"
    ],
    "stage": "LAUNCH_STAGE"
  }
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la función que creaste.

{
  "name": "projects/myProject/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWox/JbaZw="
}

Edita un rol personalizado existente

Un patrón común para actualizar los metadatos de un recurso, como un rol personalizado, es el patrón lectura-modificación-escritura. Con este patrón, se lee el estado actual del rol, se actualizan los datos de forma local y, luego, se envían los datos modificados para que se escriban.

El patrón lectura-modificación-escritura puede causar un conflicto si dos o más procesos independientes intentan la secuencia en simultáneo. Por ejemplo, si dos propietarios de un proyecto intentan realizar cambios conflictivos en un rol al mismo tiempo, algunos cambios podrían fallar. IAM resuelve este problema mediante una propiedad etag en los roles personalizados. Esta propiedad se usa para verificar si el rol personalizado cambió desde la última solicitud. Cuando realizas una solicitud a IAM con un valor ETag, IAM compara ese valor en la solicitud con el valor ETag existente asociado con el rol personalizado. Solo escribe el cambio si los valores ETag coinciden.

Cuando actualices un rol, primero debes obtenerlo con roles.get(), actualizarlo y, luego, escribir el rol actualizado con roles.patch(). Usa el valor de Etag cuando establezcas el rol solo si el rol correspondiente en roles.get() contiene un valor de Etag.

Nota: El cambio de un rol personalizado puede tardar hasta 24 horas en tener efecto para las API de Cloud Resource Manager organizations.search y folders.search mediante la agregación o eliminación de alguno de los siguientes permisos: resourcemanager.organizations.get, resourcemanager.folders.get o resourcemanager.projects.get. La projects.list de la API también está sujeta a este retraso para llamadas a la API que no proporcionan un filtro que especifique el ID y un tipo de superior. Este retraso ocurre porque estos permisos implican la funcionalidad de búsqueda y puede tardar hasta 24 horas entre las reconstrucciones del índice de búsqueda.

Console

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. En la lista desplegable de la parte superior de la página, selecciona el proyecto o la organización que contiene el rol que deseas editar.

3. Haz clic en un rol personalizado.

4. Haz clic en Editar rol.

5. Para actualizar los metadatos del rol, edita el Título, la Descripción o la Etapa de lanzamiento del rol del rol.

6. Para actualizar los permisos del rol, haz lo siguiente:

   1. Haz clic en Agregar permisos para agregar permisos nuevos al rol.
   2. Desmarca permisos para quitarlos del rol.

7. Haz clic en Actualizar para guardar la función editada.

gcloud

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

2. Usa el comando gcloud iam roles update para actualizar los roles personalizados. Puede utilizar este comando de dos maneras:

   • Con un archivo YAML que contiene la definición del rol actualizado

   • Con marcas para especificar la definición de la función actualizada

   Cuando actualices un rol personalizado, debes especificar si se aplica a nivel de la organización o a nivel del proyecto mediante las marcas --organization=ORGANIZATION_ID o --project=PROJECT_ID. En cada uno de los siguientes ejemplos, se crea un rol personalizado a nivel del proyecto.

   Para actualizar un rol personalizado con un archivo YAML, haz lo siguiente:

   Ejecuta uno de los siguientes comandos para obtener la definición actual del rol:

   • Para obtener la definición de un rol personalizado a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

   • Para obtener la definición de rol de un rol personalizado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol que quieres actualizar, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   El comando describe muestra la definición del rol y, además, incluye un valor de etag que identifica de forma única la versión actual del rol. El valor de etag debe proporcionarse en la definición del rol actualizado para garantizar que no se reemplace ningún cambio de rol simultáneo.

   El comando describe muestra el siguiente resultado:

   description: ROLE_DESCRIPTION
   etag: ETAG
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2
   name: ROLE_NAME
   stage: LAUNCH_STAGE
   title: ROLE_TITLE

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_DESCRIPTION es una descripción breve del rol, como "My custom role description".

   • ETAG es el identificador único de la versión actual del rol, como BwVkBkbfr70=.

   • PERMISSION_1 y PERMISSION_2 son permisos para incluir en el rol personalizado, como iam.roles.get. No puedes usar caracteres comodín (*) en los nombres de permisos.

   • ROLE_NAME es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo, organizations/123456789012/roles/myCompanyAdmin.:

   • LAUNCH_STAGE indica la etapa en la que se encuentra un rol en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

   • ROLE_TITLE es un título descriptivo para el rol, como "My Company Admin".

   Para actualizar el rol, incluye la definición de rol de salida en un archivo YAML o actualiza el archivo original YAML con el valor de salida de etag.

   Considera el siguiente archivo YAML de ejemplo, que contiene la salida del comando describe para un rol a nivel de proyecto y agrega dos permisos de 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/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

   Guarda el archivo YAML y, luego, ejecuta uno de los siguientes comandos:

   • Para actualizar un rol a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

   • Para actualizar un rol a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol que quieres actualizar, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project-id.

   • YAML_FILE_PATH es la ruta de acceso a la ubicación de tu archivo YAML que contiene la definición del rol personalizado actualizado.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo actualizar un rol a nivel de la organización mediante un archivo YAML:

   gcloud iam roles update ROLE_ID --organization=ORGANIZATION_ID \
       --file=YAML_FILE_PATH

   • Para actualizar un rol a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol que quieres actualizar, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   • YAML_FILE_PATH es la ruta de acceso a la ubicación de tu archivo YAML que contiene la definición del rol personalizado actualizado.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo actualizar un rol a nivel de la organización mediante un archivo YAML:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --file=my-role-definition.yaml

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo actualizar un rol a nivel de proyecto mediante un archivo YAML:

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --file=my-role-definition.yaml

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   description: My custom role description.
   etag: BwVkBwDN0lg=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   - storage.buckets.get
   - storage.buckets.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

   Para actualizar un rol personalizado mediante marcas, haz lo siguiente:

   Cada parte de la definición de una función se puede actualizar con la marca correspondiente. Consulta el tema gcloud iam roles update para obtener una lista de todas las marcas posibles.

   Puede usar las siguientes marcas para agregar o quitar permisos:

   • --add-permissions=PERMISSIONS: Agrega al rol uno o más permisos separados por comas. No puedes usar caracteres comodín (*) en los nombres de permisos.

   • --remove-permissions=PERMISSIONS: Quita del rol uno o más permisos separados por comas. No puedes usar caracteres comodín (*) en los nombres de permisos.

   De manera alternativa, puedes especificar los permisos nuevos mediante la marca --permissions=PERMISSIONS y proporcionar una lista de permisos separados por comas para reemplazar la lista existente.

   Para actualizar otras partes de la definición del rol, ejecuta uno de los siguientes comandos:

   • Para actualizar un rol a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --stage=LAUNCH_STAGE

   • Para actualizar un rol a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --stage=LAUNCH_STAGE

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   • ROLE_TITLE es un título descriptivo para el rol, como "My Company Admin".

   • ROLE_DESCRIPTION es una descripción breve del rol, como "My custom role description.".

   • LAUNCH_STAGE indica la etapa en la que se encuentra un rol en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo agregar permisos a un rol a nivel de la organización mediante marcas:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --add-permissions="storage.buckets.get,storage.buckets.list"

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo agregar permisos a un rol a nivel de proyecto mediante marcas:

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --add-permissions="storage.buckets.get,storage.buckets.list"

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   description: My custom role description.
   etag: BwVkBwDN0lg=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   - storage.buckets.get
   - storage.buckets.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name, std::string const& title) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UpdateRoleRequest request;
  request.set_name(name);
  google::iam::admin::v1::Role role;
  role.set_title(title);
  google::protobuf::FieldMask update_mask;
  *update_mask.add_paths() = "title";
  *request.mutable_role() = role;
  *request.mutable_update_mask() = update_mask;
  auto response = client.UpdateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

/** Edit role metadata. Specifically, update description and launch stage. */
public class EditRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String description = "a new description of the role";

    editRole(projectId, roleId, description);
  }

  public static void editRole(String projectId, String roleId, String description)
      throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setName(roleName)
            .setDescription(description)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.GA);
    FieldMask fieldMask = FieldMask.newBuilder().addPaths("description").addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
        UpdateRoleRequest.newBuilder()
            .setName(roleName)
            .setRole(roleBuilder)
            .setUpdateMask(fieldMask)
            .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 result = iamClient.updateRole(updateRoleRequest);
      System.out.println("Edited role:\n" + result);
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

from snippets.get_role import get_role


def edit_role(role: Role) -> Role:
    """
    Edits an existing IAM role in a GCP project.
    Args:
        role: google.cloud.iam_admin_v1.Role object to be updated

    Returns: Updated google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    request = UpdateRoleRequest(name=role.name, role=role)
    try:
        role = client.update_role(request)
        print(f"Edited role: {role.name}: {role}")
        return role
    except NotFound:
        print(f"Role [{role.name}] not found, take some actions")

REST

El método roles.patch permite actualizar un rol personalizado en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

Obligatorio:

• RESOURCE_TYPE: Es el tipo de recurso cuyos roles personalizados quieres administrar. Usa el valor projects o organizations.
• RESOURCE_ID: es el ID del proyecto o de la organización cuyos roles personalizados deseas administrar. Los ID de proyecto son strings alfanuméricas, como my-project. Los ID de la organización son numéricos, como 123456789012.
• ROLE_NAME: Es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin

Recomendado:

• ETAG: Es un identificador para una versión del rol. Incluye este campo para evitar reemplazar otros cambios de roles.

Opcional (define uno o más de los siguientes valores):

• ROLE_TITLE: Es el título legible para el rol. Por ejemplo, My Company Admin.
• ROLE_DESCRIPTION: Es una descripción para el rol. Por ejemplo, "The company admin role allows company admins to access important resources".
• PERMISSION_1 y PERMISSION_2: Son los permisos que deseas incluir en el rol. Por ejemplo, storage.objects.update. No puedes usar caracteres comodín (*) en los nombres de permisos.
• LAUNCH_STAGE: Es la etapa de lanzamiento actual del rol. Este campo puede contener uno de los siguientes valores: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Método HTTP y URL:

PATCH https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

Cuerpo JSON de la solicitud:

{
  "roleId": "ROLE_NAME",
  "title": "ROLE_TITLE",
  "description": "ROLE_DESCRIPTION",
  "includedPermissions": [
    "PERMISSION_1",
    "PERMISSION_2"
  ],
  "stage": "LAUNCH-STAGE",
  "etag": "ETAG"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth 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)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth 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

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene una definición de función abreviada que incluye el nombre de la función, los campos que actualizaste y un ETag que identifica la versión actual de la función.

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "title": "My Updated Company Admin",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "stage": "BETA",
  "etag": "BwWoyDpAxBc="
}

Inhabilita un rol personalizado

Para inhabilitar un rol personalizado, cambia su etapa de lanzamiento a DISABLED. Cuando un rol está inhabilitado, todas las vinculaciones de roles relacionadas con él se desactivan, lo que significa que otorgar este rol a un usuario no tendrá efecto alguno.

Console

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. Haz clic en la lista desplegable "Seleccionar un proyecto" en la parte superior de la página.

3. Selecciona tu organización o proyecto.

4. Selecciona una función personalizada y haz clic en Inhabilitar.

gcloud

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

2. Si quieres usar el comando gcloud iam roles update para inhabilitar un rol personalizado, establece su etapa de lanzamiento en DISABLED.

   Como se describe en la pestaña gcloud de la sección Edita un rol personalizado existente, puedes actualizar un rol personalizado existente mediante los siguientes dos métodos:

   • Con un archivo YAML que contiene la definición del rol actualizado

   • Con marcas para especificar la definición de la función actualizada

   La forma más fácil de inhabilitar un rol personalizado existente es usar la marca --stage y establecerla en DISABLED. Ejecuta uno de los siguientes comandos:

   • Para inhabilitar un rol a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --stage=DISABLED

   • Para inhabilitar un rol a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --stage=DISABLED

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo inhabilitar un rol a nivel de la organización:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --stage=DISABLED

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo inhabilitar un rol a nivel del proyecto:

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --stage=DISABLED

   Si el rol se actualizó con éxito, el resultado del comando es similar al siguiente:

   description: My custom role description.
   etag: BwVkB5NLIQw=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: DISABLED
   title: My Company Admin

C++

Actualiza el campo stage del rol a DISABLED.

C#

Actualiza el campo stage del rol a DISABLED.

Go

Actualiza el campo stage del rol a DISABLED.

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class DisableRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "testRole";

    Role role = disableRole(projectId, roleId);
    System.out.println("Role name: " + role.getName());
    System.out.println("Role stage: " + role.getStage());
  }

  public static Role disableRole(String projectId, String roleId)
          throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role role = Role.newBuilder()
                    .setName(roleName)
                    .setStage(Role.RoleLaunchStage.DISABLED)
                    .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
              UpdateRoleRequest.newBuilder()
                      .setName(roleName)
                      .setRole(role)
                      .setUpdateMask(fieldMask)
                      .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()) {
      return iamClient.updateRole(updateRoleRequest);
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role, UpdateRoleRequest


def disable_role(project_id: str, role_id: str) -> Role:
    """
    Disables an IAM role in a GCP project.
    Args:
        project_id: GCP project ID
        role_id: ID of GCP IAM role

    Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    get_request = GetRoleRequest(name=name)
    try:
        role = client.get_role(get_request)
        role.stage = Role.RoleLaunchStage.DISABLED
        update_request = UpdateRoleRequest(name=role.name, role=role)
        client.update_role(update_request)
        print(f"Disabled role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

REST

El método roles.patch permite cambiar la etapa de lanzamiento de un rol personalizado a DISABLED para inhabilitarlo.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• RESOURCE_TYPE: Es el tipo de recurso cuyos roles personalizados quieres administrar. Usa el valor projects o organizations.
• RESOURCE_ID: es el ID del proyecto o de la organización cuyos roles personalizados deseas administrar. Los ID de proyecto son strings alfanuméricas, como my-project. Los ID de la organización son numéricos, como 123456789012.
• ROLE_NAME: Es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin
• ETAG: Es un identificador para una versión de la función. Incluye este campo para evitar reemplazar otros cambios de roles.

Método HTTP y URL:

PATCH https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

Cuerpo JSON de la solicitud:

{
  "roleId": "ROLE_NAME",
  "stage": DISABLED,
  "etag": "ETAG"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth 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)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth 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

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "stage": "DISABLED",
  "etag": "BwWoyDpAxBc="
}

Enumera roles

Puedes enumerar todos los roles personalizados creados en tu organización o proyecto.

Console

En la consola de Google Cloud, ve a la página Roles.

Ir a la página Funciones

Todos los roles personalizados para la organización o el proyecto que seleccionaste se enumeran en la página.

gcloud

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

2. Usa el comando gcloud iam roles list a fin de enumerar los roles personalizados y predefinidos de una organización o un proyecto.

   • Para enumerar los roles personalizados a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles list --organization=ORGANIZATION_ID

   • Para enumerar los roles personalizados a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles list --project=PROJECT_ID

   Cada valor de marcador de posición se describe a continuación:

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   Para enumerar los roles que se borraron, también puedes especificar la marca --show-deleted.

   Ejecuta el siguiente comando para enumerar las funciones predefinidas:

   gcloud iam roles list

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

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

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.ListRolesPagedResponse;
import com.google.iam.admin.v1.ListRolesRequest;
import java.io.IOException;

/** List roles in a project. */
public class ListRoles {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String projectId = "your-project-id";

    listRoles(projectId);
  }

  public static void listRoles(String projectId) throws IOException {
    ListRolesRequest listRolesRequest =
        ListRolesRequest.newBuilder().setParent("projects/" + projectId).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()) {
      ListRolesPagedResponse listRolesResponse = iamClient.listRoles(listRolesRequest);
      listRolesResponse.iterateAll().forEach(role -> System.out.println(role));
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

from google.cloud.iam_admin_v1 import IAMClient, ListRolesRequest, RoleView
from google.cloud.iam_admin_v1.services.iam.pagers import ListRolesPager


def list_roles(
    project_id: str, show_deleted: bool = True, role_view: RoleView = RoleView.BASIC
) -> ListRolesPager:
    """
    Lists IAM roles in a GCP project.
    Args:
        project_id: GCP project ID
        show_deleted: Whether to include deleted roles in the results
        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)

    Returns: A pager for traversing through the roles
    """
    client = IAMClient()
    parent = f"projects/{project_id}"
    request = ListRolesRequest(parent=parent, show_deleted=show_deleted, view=role_view)
    roles = client.list_roles(request)
    for page in roles.pages:
        for role in page.roles:
            print(role)
    print("Listed all iam roles")
    return roles

REST

El método roles.list permite enumerar todos los roles personalizados de un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• RESOURCE_TYPE: Es el tipo de recurso cuyos roles personalizados quieres administrar. Usa el valor projects o organizations.
• RESOURCE_ID: es el ID del proyecto o de la organización cuyos roles personalizados deseas administrar. Los ID de proyecto son strings alfanuméricas, como my-project. Los ID de la organización son numéricos, como 123456789012.
• ROLE_VIEW: Opcional Es la información que se debe incluir para los roles que se muestran. Para incluir los permisos de los roles, establece este campo en FULL. Para excluir los permisos de los roles, establece este campo en BASIC. El valor predeterminado es BASIC.
• PAGE_SIZE: Opcional Es la cantidad de roles que se deben incluir en la respuesta. El valor predeterminado es 300 y el valor máximo es 1,000. Si la cantidad de roles es mayor que el tamaño de la página, la respuesta contiene un token de paginación que puedes usar para consultar la siguiente página de resultados.
• NEXT_PAGE_TOKEN: Opcional Es el token de paginación que se mostró en una respuesta anterior de este método. Si se especifica, la lista de roles comenzará desde el punto en que finalizó la solicitud anterior.

Nota: Para enumerar todos los roles de IAM predefinidos, omite los campos RESOURCE_TYPE y RESOURCE_ID. Por ejemplo: GET https://iam.googleapis.com/v1/roles.

Método HTTP y URL:

GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth 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)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

$cred = gcloud auth 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

Explorador de APIs (navegador)

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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="
    }
  ]
}

Borra un rol personalizado

Puedes borrar cualquier rol personalizado en tu organización o proyecto.

Importante: Los roles que se borran se suspenden y no se pueden usar para crear nuevas vinculaciones de roles en las políticas de permisos. Las vinculaciones de roles existentes que incluyen el rol borrado no tienen efecto.

Console

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. Selecciona la función que deseas borrar y haz clic en  Borrar en la parte superior de la página.

gcloud

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

2. Usa el comando gcloud iam roles delete para borrar un rol personalizado.

   • Para borrar un rol personalizado a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

   • Para borrar un rol personalizado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   El rol no se incluirá en la gcloud iam roles list, a menos que se incluya la marca --show-deleted. Los roles que se borraron se indican mediante el bloque deleted: true en una respuesta de la list, como la que se muestra a continuación:

   ---
   deleted: true
   description: My custom role description.
   etag: BwVkB5NLIQw=
   name: projects/my-project/roles/myCompanyAdmin
   title: My Company Admin
   ---
   

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

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

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

/** Delete role. */
public class DeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    deleteRole(projectId, roleId);
  }

  public static void deleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    DeleteRoleRequest deleteRoleRequest = DeleteRoleRequest.newBuilder().setName(roleName).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()) {
      iamClient.deleteRole(deleteRoleRequest);
      System.out.println("Role deleted.");
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)

def delete_role(project_id: str, role_id: str) -> Role:
    """
    Deletes iam role in GCP project. Can be undeleted later
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = DeleteRoleRequest(name=name)
    try:
        role = client.delete_role(request)
        print(f"Deleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] already deleted, take some actions)", err)

REST

El método roles.delete permite borrar un rol personalizado en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• ROLE_NAME: Es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin

Método HTTP y URL:

DELETE https://iam.googleapis.com/v1/ROLE_NAME

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

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

Explorador de APIs (navegador)

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la definición de la función que se borró.

{
  "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
}

Cuando se borra un rol, todas las vinculaciones de roles que hagan referencia a él permanecen en las políticas de permisos, pero no tienen efecto. Puedes recuperar un rol en un plazo de 7 días. Durante ese período de 7 días, la consola de Google Cloud muestra que se borró el rol. También puedes enumerar los roles que se borraron de manera programática, pero se omiten de forma predeterminada.

Después de 7 a 14 días, el rol está programado para borrarse de forma definitiva. En este punto, el rol ya no se tiene en cuenta para el límite de 300 roles personalizados por organización o 300 roles personalizados por proyecto.

Nota: Los roles personalizados creados en un proyecto no se tienen en cuenta para el límite de roles personalizados de la organización.

El proceso de eliminación permanente demora 30 días. Durante el período de 30 días, el rol y todos los enlaces asociados se quitan de forma permanente, y no puedes crear un rol nuevo con el mismo ID de rol.

Una vez que el rol se haya borrado de forma definitiva, hasta 44 días después de la solicitud de eliminación inicial, puedes crear un rol nuevo con el mismo ID de rol.

Recupera una función personalizada

Cuando recuperas un rol, este vuelve a su estado anterior.

Los roles solo se pueden recuperar en un plazo de 7 días. Después de 7 días, el rol se puede borrar de forma definitiva en cualquier momento, y se quitan todas las vinculaciones de roles que hacen referencia al rol.

Console

1. En la consola de Google Cloud, ve a la página Roles.

   Ir a la página Roles

2. Encuentra la función que deseas recuperar, haz clic en el ícono más al final de la fila y luego en Recuperar.

gcloud

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

2. Usa el comando gcloud iam roles undelete para recuperar un rol personalizado.

   • Para recuperar un rol personalizado a nivel de la organización, ejecuta el siguiente comando:

     gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID

   • Para recuperar un rol personalizado a nivel de proyecto, ejecuta el siguiente comando:

     gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

   Cada valor de marcador de posición se describe a continuación:

   • ROLE_ID es el nombre del rol, como myCompanyAdmin.

   • ORGANIZATION_ID es el ID numérico de la organización, como 123456789012.

   • PROJECT_ID es el nombre del proyecto, como my-project.

   Ejemplos

   En el siguiente ejemplo, se muestra cómo recuperar un rol personalizado a nivel de la organización:

   gcloud iam roles undelete myCompanyAdmin --organization=123456789012

   Si el rol se recuperó con éxito, el resultado del comando es similar al siguiente:

   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

   En el siguiente ejemplo, se muestra cómo recuperar un rol personalizado a nivel del proyecto:

   gcloud iam roles undelete myCompanyAdmin --project=my-project

   Si el rol se recuperó con éxito, el resultado del comando es similar al siguiente:

   description: My custom role description.
   etag: BwVkCAx9W6w=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C++.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

C#

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM C#.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Go.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

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

/**
 * Undelete a role to return it to its previous state. Undeleting only works on roles that were
 * deleted in the past 7 days.
 */
public class UndeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to a role that was deleted in the past 7 days.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    undeleteRole(projectId, roleId);
  }

  public static void undeleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    UndeleteRoleRequest undeleteRoleRequest =
        UndeleteRoleRequest.newBuilder().setName(roleName).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 result = iamClient.undeleteRole(undeleteRoleRequest);
      System.out.println("Undeleted role:\n" + result);
    }
  }
}

Python

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Python.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Antes de comenzar.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)

def undelete_role(project_id: str, role_id: str) -> Role:
    """
    Undeleted deleted iam role in GCP project
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = UndeleteRoleRequest(name=name)
    try:
        role = client.undelete_role(request)
        print(f"Undeleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] is not deleted, take some actions)", err)

REST

El método roles.undelete permite recuperar un rol personalizado en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• ROLE_NAME: Es el nombre completo del rol, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin
• ETAG: Es un identificador para una versión de la función. Incluye este campo para evitar reemplazar otros cambios de roles.

Método HTTP y URL:

POST https://iam.googleapis.com/v1/ROLE_NAME:undelete

Cuerpo JSON de la solicitud:

{
  "etag": "ETAG"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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/ROLE_NAME:undelete"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la definición de la función que se recuperó.

{
  "name": "projects/my-project/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWiPg2fmDE="
}

¿Qué sigue?

• Descubre cómo otorgar roles a los principales.
• Explora cómo puedes usar las recomendaciones de roles para reducir los permisos de los principales.
• Obtén información sobre los otorgamientos de roles condicionales, que otorgan un rol solo si se cumplen condiciones específicas.