Crear y gestionar roles personalizados

En esta página se describe cómo crear y gestionar roles personalizados de Gestión de Identidades y Accesos (IAM). Gestionar roles incluye modificar, inhabilitar, enumerar, eliminar y restaurar roles.

Antes de empezar

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  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.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación. Google Cloud

  C++

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  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.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación. Google Cloud

  Go

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  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.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación. Google Cloud

  Java

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  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.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación. Google Cloud

  Python

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  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.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local en la documentación de autenticación. Google Cloud

  REST

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

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  Para obtener más información, consulta el artículo Autenticación para usar REST de la documentación sobre autenticación de Google Cloud .

  Consulta la Google Cloud jerarquía de recursos.

  Consulta el artículo Conocer los roles personalizados de gestión de identidades y accesos.

Roles obligatorios

Para obtener los permisos que necesitas para crear y gestionar roles personalizados, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

• Para gestionar los roles de un proyecto, debes tener el rol Administrador de roles (roles/iam.roleAdmin) en el proyecto en el que quieras gestionar los roles.
• Para gestionar los roles de una organización, debes tener el rol Administrador de roles de la organización (roles/iam.organizationRoleAdmin) en la organización cuyos roles quieras gestionar.

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Ver los permisos disponibles de proyectos, carpetas y organizaciones

Puedes crear roles personalizados para toda una organización o para un proyecto específico de esa organización. Los permisos disponibles para los roles personalizados dependen de dónde crees el rol. Por ejemplo, si un permiso solo se puede usar a nivel de organización, no podrás incluirlo en un rol personalizado a nivel de proyecto.

Para comprobar qué permisos están disponibles para los roles personalizados a nivel de organización y de proyecto, puedes usar la CLI de gcloud o la API Identity and Access Management para consultar los permisos disponibles en una organización o un proyecto concretos. Por ejemplo, puedes obtener todos los permisos disponibles para los roles personalizados que se hayan creado en tu proyecto.

Es posible que algunos permisos no se muestren o no se puedan usar en un rol personalizado, aunque sean compatibles con ellos. Por ejemplo, es posible que un permiso no se pueda usar en roles personalizados si no has habilitado la API del servicio en cuestión.

Para obtener más información sobre los permisos que puedes añadir 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 para obtener una lista de los permisos disponibles para los roles personalizados de un proyecto o una organización concretos. La respuesta muestra los permisos que puedes usar en los roles personalizados de ese proyecto u organización.

   Para enumerar los permisos disponibles en los roles personalizados de un proyecto o una organización, ejecuta este comando:

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

   Sustituye 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 los roles personalizados. Los permisos que no tienen un campo customRolesSupportLevel se admiten por completo.

   El comando list-testable-permissions puede devolver 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

import os
from typing import List

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


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

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

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

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

REST

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

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• FULL_RESOURCE_NAME: un URI que consta del nombre del servicio y la ruta al recurso. Para ver ejemplos, consulta Nombres de recursos completos.
• PAGE_SIZE: opcional. Número de permisos que se incluirán en la respuesta. El valor predeterminado es 100 y el máximo es 1000. Si el número de permisos es superior al tamaño de la página, la respuesta contiene un token de paginación que puedes usar para obtener la siguiente página de resultados.
• NEXT_PAGE_TOKEN: opcional. El token de paginación devuelto en una respuesta anterior de este método. Si se especifica, la lista de permisos que se pueden probar empezará donde terminó la respuesta 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 APIs Explorer 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, rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la lista de permisos.

Nota: Los permisos que no tienen el campo customRolesSupportLevel se admiten por completo en los roles personalizados.

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

Obtener los metadatos del rol

Antes de crear un rol personalizado, puede obtener los metadatos de los roles predefinidos y personalizados. Los metadatos de los roles incluyen el ID del rol y los permisos que contiene. Puede ver los metadatos mediante laGoogle Cloud consola o la API de gestión de identidades y accesos.

Para ver los metadatos del rol, usa uno de los métodos que se indican a continuación:

Consola

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

   Ir a la página Roles

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

3. Selecciona la casilla de uno o varios roles para ver sus permisos. En el panel de la derecha se muestran los permisos incluidos en los roles, si los hay.

Los iconos de la columna Tipo indican si se trata de un rol personalizado (icono de fábrica) o de un rol predefinido (icono de hexágono).

Si quieres encontrar todos los roles que incluyen un permiso específico, escribe el nombre del permiso en el cuadro Filtrar situado en la parte superior de la lista Roles.

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:

   gcloud iam roles describe ROLE_ID

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

   En el siguiente ejemplo se muestra la salida 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 creado a nivel de 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

   A continuación se describe cada valor de marcador de posició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 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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 as exc:
        raise NotFound(f"Role with id [{role_id}] not found, take some actions") from exc

REST

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

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• ROLE_NAME: 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

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

PowerShell (Windows)

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

$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 APIs Explorer se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la definición del rol.

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

Crear una función personalizada

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

Nota: No puedes definir roles personalizados a nivel de carpeta. Si necesitas usar un rol personalizado en una carpeta, defínelo a nivel de organización.

Un rol personalizado a nivel de organización puede incluir cualquiera de los permisos de gestión de identidades y accesos que se admiten en los roles personalizados. Un rol personalizado a nivel de proyecto puede contener cualquier permiso admitido excepto los permisos que solo se pueden usar a nivel de organización o de carpeta, como resourcemanager.organizations.get. Si intentas añadir estos permisos a un rol personalizado a nivel de proyecto, verás un mensaje de error:

Consola

Se muestra el siguiente mensaje de advertencia: "No se aplican a los roles personalizados de nivel de proyecto". El permiso se desmarcará automáticamente de la lista de permisos incluidos y podrás crear el 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 la operación.

API 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 INVALID_ARGUMENT. El rol personalizado no se creará hasta que elimines el permiso de la definición del rol y vuelvas a intentar la operación.

Cada rol personalizado puede contener hasta 3000 permisos. Además, el tamaño total máximo del título, la descripción y los nombres de los permisos de 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 rol 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 fase de lanzamiento. La mayoría de las fases de lanzamiento son informativas y te ayudan a hacer un seguimiento de si cada rol está listo para un uso generalizado. Además, la fase de lanzamiento DISABLED te permite inhabilitar un rol personalizado. Para obtener más información sobre las fases de lanzamiento, consulta Pruebas e implementaciones.

Consola

Algunos roles predefinidos contienen permisos obsoletos o permisos que no se permiten en 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 rol personalizado desde cero, sigue estos pasos:

1. En la Google Cloud consola, 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 quieras crear un rol.

3. Haz clic en Crear rol.

4. Introduce un título, una descripción, un ID y la fase de lanzamiento del rol. El ID del rol no se puede cambiar una vez creado el rol.

5. Haz clic en Añadir permisos.

6. Seleccione los permisos que quiera incluir en el rol y haga clic en Añadir permisos. Usa las listas desplegables Todos los servicios y Todos los tipos para filtrar y seleccionar permisos por servicios y tipos.

Para crear un rol personalizado a partir de un rol predefinido, sigue estos pasos:

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

   Ir a la página Roles

2. Selecciona la organización o el proyecto en el que quieras crear un rol.
3. Selecciona los roles en los que quieras basar el nuevo rol personalizado.
4. Haz clic en Crear rol a partir de los roles seleccionados.
5. Introduce un título, una descripción, un ID y la fase de lanzamiento del rol. El ID del rol no se puede cambiar una vez creado el rol.
6. Desmarca los permisos que quieras excluir del rol.
7. Haz clic en Añadir permisos para incluir los permisos que quieras.
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 roles personalizados. Puedes usar este comando de dos formas:

   • Proporcionando un archivo YAML que contenga la definición del rol

   • Usando marcas para especificar la definición del rol

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

   Un rol personalizado solo puede contener permisos que sean compatibles con roles personalizados. Si el rol personalizado contiene otros permisos, el comando fallará.

   Para crear un rol personalizado con un archivo YAML, sigue estos pasos:

   Crea un archivo YAML que contenga la definición de tu rol personalizado. El archivo debe tener la siguiente estructura:

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

   A continuación se describe cada valor de marcador de posición:

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

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

   • LAUNCH_STAGE indica la fase de un rol en el ciclo de vida del lanzamiento, como ALPHA, BETA o GA.

   • PERMISSION_1 y PERMISSION_2 son permisos que se pueden 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, a continuación, ejecuta uno de los siguientes comandos:

   • Para crear un rol personalizado a nivel de 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

   A continuación se describe cada valor de marcador de posició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 del 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 organización mediante el archivo YAML:

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

   Si el rol se ha creado correctamente, el resultado del comando será 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 un archivo YAML:

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

   Si el rol se ha creado correctamente, el resultado del comando será 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 con marcas, sigue estos pasos:

   Ejecuta uno de los siguientes comandos:

   • Para crear un rol personalizado a nivel de 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

   A continuación se describe cada valor de marcador de posició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 breve descripción del rol, como "My custom role description.".

   • PERMISSIONS_LIST contiene una lista separada por comas de los permisos que quieres 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 fase de un rol en el ciclo de vida del lanzamiento, como ALPHA, BETA o GA.

   Ejemplos

   En el siguiente ejemplo se muestra cómo crear un rol a nivel de 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 ha creado correctamente, el resultado del comando será 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 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 ha creado correctamente, el resultado del comando será 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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 crea un rol personalizado en un proyecto o una organización.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

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

• PERMISSION_1 y PERMISSION_2: los permisos que quieras 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 sean compatibles con roles personalizados. Si el rol personalizado contiene otros permisos, la solicitud fallará.

• LAUNCH_STAGE: la fase 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 APIs Explorer 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, rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene el rol que has creado.

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

Editar un rol personalizado

Un patrón habitual para actualizar los metadatos de un recurso, como un rol personalizado, es el patrón lectura, modificación y escritura. Con este patrón, lees el estado actual del rol, actualizas los datos de forma local y, a continuación, envías los datos modificados para escribirlos.

El patrón de lectura-modificación-escritura puede provocar un conflicto si dos o más procesos independientes intentan realizar la secuencia simultáneamente. Por ejemplo, si dos propietarios de un proyecto intentan hacer cambios conflictivos en un rol al mismo tiempo, es posible que algunos cambios no se apliquen. IAM resuelve este problema mediante una propiedad etag en los roles personalizados. Esta propiedad se usa para verificar si el rol personalizado ha cambiado desde la última solicitud. Cuando haces una solicitud a IAM con un valor de etag, IAM compara el valor de etag de la solicitud con el valor de etag asociado al rol personalizado. Solo escribe el cambio si los valores de etag coinciden.

Cuando actualices un rol, primero obtén el rol con roles.get(), actualízalo y, a continuación, escribe el rol actualizado con roles.patch(). Utilice el valor etag al definir el rol solo si el rol correspondiente de roles.get() contiene un valor etag.

Nota: Cuando se modifica un rol personalizado añadiendo o quitando cualquiera de los siguientes permisos: resourcemanager.organizations.get, resourcemanager.folders.get y resourcemanager.projects.get, el cambio en el rol personalizado puede tardar hasta 24 horas en aplicarse a las APIs organizations.search y folders.search de Cloud Resource Manager. La API projects.list también está sujeta a este retraso en las llamadas a la API que no proporcionan un filtro que especifique un tipo y un ID de elemento superior. Este retraso se produce porque estos permisos implican la funcionalidad de búsqueda y pueden tardar hasta 24 horas entre las recompilaciones del índice de búsqueda.

Consola

1. En la Google Cloud consola, 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 contenga el rol que quieras 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 Fase de lanzamiento del rol.

6. Para actualizar los permisos del rol, sigue estos pasos:

   1. Haga clic en Añadir permisos para añadir permisos al rol.
   2. Desmarca los permisos que quieras quitar del rol.

7. Haz clic en Actualizar para guardar el rol editado.

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. Puedes usar este comando de dos formas:

   • Proporcionando un archivo YAML que contenga la definición de rol actualizada

   • Usando marcas para especificar la definición de rol actualizada

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

   Para actualizar un rol personalizado mediante un archivo YAML, sigue estos pasos:

   Para obtener la definición actual del rol, ejecuta uno de los siguientes comandos:

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

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

   A continuación se describe cada valor de marcador de posición:

   • ROLE_ID es el nombre del rol que se va a 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 devuelve la definición del rol e incluye un valor etag que identifica de forma única la versión actual del rol. El valor etag debe proporcionarse en la definición de rol actualizada para asegurarse de que no se sobrescriban los cambios de rol simultáneos.

   El comando describe devuelve el siguiente resultado:

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

   A continuación se describe cada valor de marcador de posición:

   • ROLE_DESCRIPTION es una breve descripción 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 que se pueden 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 fase de un rol en el ciclo de vida del 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 del rol en un archivo YAML o actualiza el archivo YAML original con el valor etag.

   Consulta el siguiente archivo YAML de ejemplo, que contiene el resultado del comando describe para un rol a nivel de proyecto y añade 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, a continuación, ejecuta uno de los siguientes comandos:

   • Para actualizar un rol a nivel de 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

   A continuación se describe cada valor de marcador de posición:

   • ROLE_ID es el nombre del rol que se va a 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 a la ubicación del 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 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

   A continuación se describe cada valor de marcador de posición:

   • ROLE_ID es el nombre del rol que se va a 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 a la ubicación del 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 organización mediante un archivo YAML:

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

   Si el rol se ha actualizado correctamente, el resultado del comando será 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 ha actualizado correctamente, el resultado del comando será 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, sigue estos pasos:

   Cada parte de una definición de rol se puede actualizar mediante una marca correspondiente. Consulta el gcloud iam roles update tema para ver una lista de todas las posibles marcas.

   Puedes usar las siguientes marcas para añadir o quitar permisos:

   • --add-permissions=PERMISSIONS: añade uno o varios permisos separados por comas al rol. No puedes usar caracteres comodín (*) en los nombres de permisos.

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

   También puedes especificar los nuevos permisos con la marca --permissions=PERMISSIONS y proporcionar una lista de permisos separados por comas para sustituir la lista de permisos actual.

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

   • Para actualizar un rol a nivel de 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

   A continuación se describe cada valor de marcador de posició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 breve descripción del rol, como "My custom role description.".

   • LAUNCH_STAGE indica la fase de un rol en el ciclo de vida del lanzamiento, como ALPHA, BETA o GA.

   Ejemplos

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

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

   Si el rol se ha actualizado correctamente, el resultado del comando será 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 añadir 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 ha actualizado correctamente, el resultado del comando será 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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 actualiza un rol personalizado en un proyecto o una organización.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

Obligatorio:

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

Recomendado:

• ETAG: identificador de una versión del rol. Incluye este campo para evitar que se sobrescriban otros cambios de rol.

Opcional (define uno o varios de los siguientes valores):

• ROLE_TITLE: título legible por humanos del rol. Por ejemplo, My Company Admin.
• ROLE_DESCRIPTION: descripción del rol. Por ejemplo, "The company admin role allows company admins to access important resources".
• PERMISSION_1 y PERMISSION_2: los permisos que quieras incluir en el rol. Por ejemplo, storage.objects.update. No puedes usar caracteres comodín (*) en los nombres de permisos.
• LAUNCH_STAGE: la fase 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 APIs Explorer 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, rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene una definición abreviada del rol que incluye el nombre del rol, los campos que has actualizado y un etag que identifica la versión actual del rol.

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

Inhabilitar un rol personalizado

Para inhabilitar un rol personalizado, cambia su fase de lanzamiento a DISABLED. Cuando se inhabilita un rol, se desactivan todas las vinculaciones de roles relacionadas con él, lo que significa que conceder el rol a un usuario no tiene ningún efecto.

Consola

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

   Ir a la página Roles

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

3. Selecciona tu organización o proyecto.

4. Selecciona un rol personalizado 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. Usa el comando gcloud iam roles update para inhabilitar un rol personalizado asignando el valor DISABLED a su fase de lanzamiento.

   Tal como se describe en la pestaña gcloud de la sección Editar un rol personalizado, puedes actualizar un rol personalizado de dos formas:

   • Proporcionando un archivo YAML que contenga la definición de rol actualizada

   • Usando marcas para especificar la definición de rol actualizada

   La forma más sencilla de inhabilitar un rol personalizado es usar la marca --stage y asignarle el valor DISABLED. Ejecuta uno de los siguientes comandos:

   • Para inhabilitar un rol a nivel de 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

   A continuación se describe cada valor de marcador de posició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 organización:

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

   Si el rol se ha actualizado correctamente, el resultado del comando será similar al siguiente:

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

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

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

   Si el rol se ha actualizado correctamente, el resultado del comando será 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

from google.api_core.exceptions import NotFound
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 as exc:
        raise NotFound(f'Role with id [{role_id}] not found, take some actions') from exc

REST

El método roles.patch te permite cambiar la fase de lanzamiento de un rol personalizado a DISABLED, lo que inhabilita el rol.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

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

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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 APIs Explorer 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, rellena los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la siguiente:

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

Mostrar roles

Puedes consultar todos los roles personalizados creados en tu proyecto u organización.

Consola

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

Ir a la página Roles

En la página se muestran todos los roles personalizados de la organización o el proyecto que hayas seleccionado.

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 para consultar los roles personalizados y predefinidos de un proyecto o una organización:

   • Para enumerar los roles personalizados a nivel de 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

   A continuación se describe cada valor de marcador de posició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 eliminados, también puedes especificar la marca --show-deleted.

   Ejecuta el siguiente comando para enumerar los roles predefinidos:

   gcloud iam roles list

C++

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

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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 muestra todos los roles personalizados de un proyecto o una organización.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• RESOURCE_TYPE: el tipo de recurso cuyos roles personalizados quieres gestionar. Usa el valor projects o organizations.
• RESOURCE_ID: el ID del proyecto o de la organización cuyos roles personalizados quieres gestionar. Los IDs de proyecto son cadenas alfanuméricas, como my-project. Los IDs de organización son numéricos, como 123456789012.
• ROLE_VIEW: opcional. Información que se debe incluir en los roles devueltos. Para incluir los permisos de los roles, asigna el valor FULL a este campo. Para excluir los permisos de los roles, asigna el valor BASIC a este campo. El valor predeterminado es BASIC.
• PAGE_SIZE: opcional. Número de roles que se incluirán en la respuesta. El valor predeterminado es 300 y el máximo es 1000. Si el número de roles es superior al tamaño de la página, la respuesta contiene un token de paginación que puedes usar para obtener la siguiente página de resultados.
• NEXT_PAGE_TOKEN: opcional. El token de paginación devuelto en una respuesta anterior de este método. Si se especifica, la lista de roles empezará donde terminó la solicitud anterior.

Nota: Para enumerar todos los roles predefinidos de gestión de identidades y accesos, 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

$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 APIs Explorer se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Rellena los campos obligatorios y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la siguiente:

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

Eliminar un rol personalizado

Puedes eliminar cualquier rol personalizado de tu proyecto u organización.

Importante: Los roles eliminados se suspenden y no se pueden usar para crear enlaces de roles en las políticas de permiso. Los enlaces de rol que incluyan el rol eliminado no tendrán ningún efecto.

Consola

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

   Ir a la página Roles

2. Selecciona el rol que quieras eliminar y haz clic en Eliminar 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 eliminar un rol personalizado:

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

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

   A continuación se describe cada valor de marcador de posició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 gcloud iam roles list, a menos que se incluya la marca --show-deleted. Los roles eliminados se indican con el bloque deleted: true en una respuesta list, como 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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 elimina un rol personalizado de un proyecto o una organización.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• ROLE_NAME: 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

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

PowerShell (Windows)

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Ejecuta el comando siguiente:

$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 APIs Explorer se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la definición del rol que se ha eliminado.

{
  "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 elimina un rol, los enlaces de rol que hagan referencia a él permanecen en tus políticas de permisos, pero no tienen ningún efecto. Puedes restaurar un rol en un plazo de 7 días. Durante este periodo de 7 días, la consola Google Cloud muestra que el rol se ha eliminado. También puedes enumerar los roles eliminados mediante programación, pero se omiten de forma predeterminada.

El rol se eliminará definitivamente entre 7 y 14 días después de la solicitud inicial para eliminarlo. En ese momento, el rol ya no se contabiliza en 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 contabilizan en el límite de roles personalizados de tu organización.

Una vez que se haya programado la eliminación permanente del rol, Google Cloud inicia el proceso para eliminarlo de forma definitiva. Este proceso dura 30 días. Durante este periodo de 30 días, el rol y todos los enlaces asociados se eliminarán de forma permanente y no podrás crear un rol con el mismo ID.

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

Restaurar un rol personalizado

Si restauras un rol, volverá a su estado anterior.

Los roles solo se pueden restaurar en un plazo de 7 días. Transcurridos 7 días, Google Cloud inicia el proceso para eliminar el rol permanentemente. Este proceso de eliminación permanente puede tardar hasta 30 días. Una vez que se haya eliminado un rol de forma permanente, se quitarán todos los enlaces de rol que hagan referencia a él y podrás crear un rol con el mismo ID.

Consola

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

   Ir a la página Roles

2. Busca el rol que quieras restaurar, haz clic en el icono Más al final de la fila y, a continuación, en Restaurar.

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 restaurar un rol personalizado:

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

     gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

   A continuación se describe cada valor de marcador de posició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 restaurar un rol personalizado a nivel de organización:

   gcloud iam roles undelete myCompanyAdmin --organization=123456789012

   Si el rol se ha restaurado correctamente, el resultado del comando será similar al siguiente:

   description: My custom role description.
   etag: BwVkCAx9W6w=
   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 restaurar un rol personalizado a nivel de proyecto:

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

   Si el rol se ha restaurado correctamente, el resultado del comando será 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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C++ de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API C# de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Go de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Java de gestión de identidades y accesos.

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

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 saber cómo instalar y usar la biblioteca de cliente de IAM, consulta Bibliotecas de cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API Python de gestión de identidades y accesos.

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

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
    """
    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 restaura un rol personalizado en un proyecto o una organización.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

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

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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 APIs Explorer 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, rellena los campos obligatorios y haz clic en Ejecutar.

La respuesta contiene la definición del rol que se ha restaurado.

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

Siguientes pasos

• Consulta cómo asignar roles a las cuentas principales.
• Descubre cómo puedes usar las recomendaciones de roles para reducir los permisos de las entidades.
• Consulta información sobre las concesiones de roles condicionales, que conceden un rol solo si se cumplen condiciones específicas.