Creazione e gestione di ruoli personalizzati

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

In questa pagina viene descritto come creare e gestire i ruoli personalizzati di Identity and Access Management (IAM). La gestione dei ruoli include la modifica, la disattivazione, l'elenco, l'eliminazione e l'annullamento dell'eliminazione dei ruoli.

Prima di iniziare

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire i ruoli personalizzati, chiedi al tuo amministratore di concederti i seguenti ruoli IAM:

  • Per gestire i ruoli di un progetto: Amministratore ruoli (roles/iam.roleAdmin) nel progetto di cui vuoi gestire i ruoli
  • Per gestire i ruoli di un'organizzazione: Amministratore ruoli organizzazione (roles/iam.organizationRoleAdmin) nell'organizzazione per cui vuoi gestire i ruoli

Per maggiori informazioni sulla concessione dei ruoli, consulta Gestire l'accesso.

Visualizzazione delle autorizzazioni disponibili per progetti, cartelle e organizzazioni

Puoi creare ruoli personalizzati per un'intera organizzazione o per un progetto specifico in tale organizzazione.

Nei ruoli personalizzati puoi includere molte autorizzazioni IAM, ma non tutte. Ogni autorizzazione dispone di uno dei seguenti livelli di assistenza da utilizzare nei ruoli personalizzati:

Livello di supporto Descrizione
SUPPORTED L'autorizzazione è completamente supportata nei ruoli personalizzati.
TESTING Google sta testando l'autorizzazione per verificare la compatibilità con i ruoli personalizzati. Puoi includere l'autorizzazione nei ruoli personalizzati, ma potresti notare un comportamento imprevisto. Opzione sconsigliata per l'uso in produzione.
NOT_SUPPORTED L'autorizzazione non è supportata nei ruoli personalizzati.

Un ruolo personalizzato a livello di organizzazione può includere qualsiasi autorizzazione IAM supportata nei ruoli personalizzati. Un ruolo personalizzato a livello di progetto può contenere qualsiasi autorizzazione supportata ad eccezione delle autorizzazioni pertinenti solo a livello di organizzazione o cartella, ad esempio resourcemanager.organizations.get.

Per verificare quali autorizzazioni sono disponibili per i ruoli personalizzati a livello di organizzazione e di progetto, puoi utilizzare l'interfaccia a riga di comando gcloud o l'API Identity and Access Management per elencare le autorizzazioni disponibili in un'organizzazione o un progetto specifico. Ad esempio, puoi ottenere tutte le autorizzazioni disponibili per i ruoli personalizzati creati nel tuo progetto.

Alcune autorizzazioni potrebbero non essere visibili o utilizzabili in un ruolo personalizzato, anche se sono supportate nei ruoli personalizzati. Ad esempio, se non hai attivato l'API per il servizio, un'autorizzazione potrebbe non essere disponibile nei ruoli personalizzati.

gcloud CLI

Utilizza il comando gcloud iam list-testable-permissions per visualizzare un elenco delle autorizzazioni disponibili per i ruoli personalizzati in un progetto o un'organizzazione specifici. La risposta elenca le autorizzazioni che puoi utilizzare nei ruoli personalizzati per il progetto o l'organizzazione.

Per elencare le autorizzazioni disponibili nei ruoli personalizzati per un progetto o un'organizzazione, esegui questo comando:

gcloud iam list-testable-permissions full-resource-name \
    --filter="customRolesSupportLevel!=NOT_SUPPORTED"

Sostituisci full-resource-name con uno dei seguenti valori:

  • Progetto: //cloudresourcemanager.googleapis.com/projects/project-id (ad esempio, //cloudresourcemanager.googleapis.com/projects/my-project-id)
  • Organizzazione: //cloudresourcemanager.googleapis.com/organizations/numeric-id (ad esempio, //cloudresourcemanager.googleapis.com/organizations/123456789012)

I risultati indicano se ciascuna autorizzazione è supportata nei ruoli personalizzati. Le autorizzazioni che non hanno un campo customRolesSupportLevel sono completamente supportate.

Il comando list-testable-permissions potrebbe restituire centinaia di risultati. Questo esempio parziale mostra il formato di ciascun risultato:

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

REST

Il metodo permissions.queryTestablePermissions elenca le autorizzazioni disponibili in un'organizzazione o in un progetto.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • full-resource-name: un URI composto dal nome del servizio e dal percorso della risorsa. Per gli esempi, consulta la pagina Nomi completi delle risorse.
  • page-size: facoltativo. Il numero di autorizzazioni da includere nella risposta. Il valore predefinito è 100 e il valore massimo è 1000. Se il numero di autorizzazioni è maggiore delle dimensioni della pagina, la risposta contiene un token di impaginazione che puoi utilizzare per recuperare la pagina successiva dei risultati.
  • next-page-token: facoltativo. Il token di impaginazione restituito in una risposta precedente da questo metodo. Se specificato, l'elenco delle autorizzazioni verificabili inizierà dal punto in cui è terminata la risposta precedente.

Metodo HTTP e URL:

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

Corpo JSON richiesta:

{
  "fullResourceName": "full-resource-name"
  "pageSize": page-size,
  "pageToken": "next-page-token"
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene l'elenco delle autorizzazioni.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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 const& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::runtime_error(permission.status().message());
    std::cout << "Permission successfully retrieved: " << permission->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No testable permissions found in resource: " << resource
              << "\n";
  }
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

Recupero dei metadati del ruolo

Prima di creare un ruolo personalizzato, può essere utile recuperare i metadati dei ruoli predefiniti e personalizzati. I metadati del ruolo includono l'ID del ruolo e le autorizzazioni contenute nel ruolo. Per visualizzare i metadati, utilizza la console Google Cloud o l'API IAM.

Per visualizzare i metadati del ruolo, utilizza uno dei seguenti metodi:

Console

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona l'organizzazione o il progetto nell'elenco a discesa nella parte superiore della pagina.

  3. Seleziona la casella di controllo relativa a uno o più ruoli per visualizzare le autorizzazioni del ruolo. Nel riquadro laterale a destra vengono visualizzate le autorizzazioni contenute nei ruoli, se presenti.

Le icone nella colonna Tipo indicano se si tratta di un ruolo personalizzato o di un ruolo predefinito

Se vuoi trovare tutti i ruoli che includono un'autorizzazione specifica, digita il nome dell'autorizzazione nella casella Filtro nella parte superiore dell'elenco Ruoli.

gcloud CLI

Utilizza il comando gcloud iam roles describe per visualizzare i metadati per i ruoli predefiniti e i ruoli personalizzati.

Per visualizzare i metadati per un ruolo predefinito, esegui questo comando:

gcloud iam roles describe role-id

role-id è l'ID del ruolo. I ruoli predefiniti includono il prefisso role nei rispettivi ID, ad esempio roles/iam.roleViewer.

L'esempio seguente mostra l'output del comando describe quando viene eseguito sul ruolo predefinito 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

Per visualizzare i metadati di un ruolo personalizzato, esegui uno dei seguenti comandi:

  • Per visualizzare i metadati per un ruolo personalizzato creato a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles describe --organization=organization-id role-id
    
  • Per visualizzare i metadati per un ruolo personalizzato creato a livello di progetto, esegui il comando seguente:

    gcloud iam roles describe --project=project-id role-id
    

Ogni valore segnaposto è descritto di seguito:

  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.
  • role-id è l'ID del ruolo, esclusi eventuali prefissi come projects/, organizations/ o roles/. Ad esempio, myCompanyAdmin.

Per maggiori informazioni, consulta la documentazione di riferimento per gcloud iam roles describe.

REST

Il metodo roles.get ottiene la definizione di un ruolo.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • role-name: nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene la definizione del ruolo.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

Creazione di un ruolo personalizzato

Puoi creare un ruolo personalizzato a livello di progetto o di organizzazione.

Per creare un ruolo personalizzato, il chiamante deve disporre dell'autorizzazione iam.roles.create. Per impostazione predefinita, il proprietario di un progetto o di un'organizzazione dispone di questa autorizzazione e può creare e gestire ruoli personalizzati.

Agli utenti che non sono proprietari, inclusi gli amministratori dell'organizzazione, deve essere assegnato il ruolo Amministratore ruolo organizzazione o il ruolo Amministratore IAM.

Ogni ruolo personalizzato può contenere fino a 3000 autorizzazioni. Inoltre, le dimensioni totali massime di titolo, descrizione e nomi delle autorizzazioni per un ruolo personalizzato sono di 64 kB. Se devi creare un ruolo personalizzato più grande, puoi suddividere le autorizzazioni in più ruoli personalizzati. Scegli titoli che mostrino la relazione tra i ruoli personalizzati, ad esempio Custom Admin (1 of 2) e Custom Admin (2 of 2).

Ogni ruolo personalizzato può avere una fase di lancio. La maggior parte delle fasi di lancio è informativa e ti consente di tenere traccia di se ogni ruolo è pronto per un uso ampio. Inoltre, la fase di lancio di DISABLED consente di disattivare un ruolo personalizzato. Per ulteriori informazioni sulle fasi di lancio, consulta la pagina Test e deployment.

Console

Alcuni ruoli predefiniti contengono autorizzazioni obsolete o autorizzazioni che non sono altrimenti consentite nei ruoli personalizzati. Se provi a creare un ruolo personalizzato in base a uno di questi ruoli predefiniti, il ruolo personalizzato ometterà le autorizzazioni ritirate e limitate.

Per creare un nuovo ruolo personalizzato da zero:

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Utilizzando l'elenco a discesa nella parte superiore della pagina, seleziona l'organizzazione o il progetto in cui vuoi creare un ruolo.

  3. Fai clic su Crea ruolo.

  4. Inserisci un Nome, un Titolo, una Descrizione e una Fase di lancio del ruolo per il ruolo. Non è possibile modificare il nome del ruolo dopo averlo creato.

  5. Fai clic su Aggiungi autorizzazioni.

  6. Seleziona le autorizzazioni da includere nel ruolo e fai clic su Aggiungi autorizzazioni. Utilizza gli elenchi a discesa Tutti i servizi e Tutti i tipi per filtrare e selezionare le autorizzazioni in base a servizi e tipi.

Creazione di un ruolo personalizzato basato su un ruolo predefinito esistente:

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona l'organizzazione o il progetto in cui vuoi creare un ruolo.
  3. Seleziona i ruoli su cui basare il nuovo ruolo personalizzato.
  4. Fai clic su Crea ruolo da selezione.
  5. Inserisci un Nome, un Titolo, una Descrizione e una Fase di lancio del ruolo per il ruolo. Non è possibile modificare il nome del ruolo dopo averlo creato.
  6. Deseleziona le autorizzazioni che vuoi escludere dal ruolo.
  7. Fai clic su Aggiungi autorizzazioni per includere tutte le autorizzazioni.
  8. Fai clic su Crea.

gcloud CLI

Utilizza il comando gcloud iam roles create per creare nuovi ruoli personalizzati. Puoi utilizzare questo comando in due modi:

  • Fornendo un file YAML che contiene la definizione del ruolo
  • Utilizzando i flag per specificare la definizione del ruolo

Quando crei un ruolo personalizzato, devi specificare se si applica a livello di organizzazione o di progetto utilizzando i flag --organization=organization-id o --project=project-id. Ciascun esempio seguente crea un ruolo personalizzato a livello di progetto.

Un ruolo personalizzato può contenere solo autorizzazioni supportate nei ruoli personalizzati. Se il ruolo personalizzato contiene altre autorizzazioni, il comando non andrà a buon fine.

Per creare un ruolo personalizzato utilizzando un file YAML:

Crea un file YAML che contenga la definizione del ruolo personalizzato. Il file deve essere strutturato nel seguente modo:

title: role-title
description: role-description
stage: launch-stage
includedPermissions:
- permission-1
- permission-2

Ogni valore segnaposto è descritto di seguito:

  • role-title è un titolo descrittivo per il ruolo, ad esempio "My Company Admin".
  • role-description è una breve descrizione del ruolo, ad esempio "My custom role description".
  • launch-stage indica la fase di un ruolo nel ciclo di vita del lancio, come ALPHA, BETA o GA.
  • permission-1 e permission-2 sono autorizzazioni da includere nel ruolo personalizzato, come iam.roles.get. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

Salva il file YAML, quindi esegui uno dei seguenti comandi:

  • Per creare un ruolo personalizzato a livello di organizzazione, esegui questo comando:

    gcloud iam roles create role-id --organization=organization-id \
        --file=yaml-file-path
    
  • Per creare un ruolo personalizzato a livello di progetto, esegui questo comando:

    gcloud iam roles create role-id --project=project-id \
        --file=yaml-file-path
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.
  • yaml-file-path è il percorso della posizione del file YAML che contiene la definizione del ruolo personalizzato.

Esempi

Il seguente file YAML di esempio illustra come creare una definizione di ruolo:

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

L'esempio seguente mostra come creare un ruolo a livello di organizzazione utilizzando il file YAML:

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

Se il ruolo è stato creato, l'output del comando è simile al seguente:

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

L'esempio seguente mostra come creare un ruolo a livello di progetto utilizzando il file YAML:

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

Se il ruolo è stato creato, l'output del comando è simile al seguente:

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

Per creare un ruolo personalizzato con i flag:

Esegui uno dei seguenti comandi:

  • Per creare un ruolo personalizzato a livello di organizzazione, esegui questo comando:

    gcloud iam roles create role-id --organization=organization-id \
        --title=role-title --description=role-description \
        --permissions="permissions-list" --stage=launch-stage
    
  • Per creare un ruolo personalizzato a livello di progetto, esegui questo comando:

    gcloud iam roles create role-id --project=project-id \
        --title=role-title --description=role-description \
        --permissions="permissions-list" --stage=launch-stage
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.
  • role-title è un titolo descrittivo per il ruolo, ad esempio "My Company Admin".
  • role-description è una breve descrizione del ruolo, ad esempio "My custom role description.".
  • permissions-list contiene un elenco di autorizzazioni separate da virgole che vuoi includere nel ruolo personalizzato. Ad esempio: iam.roles.get,iam.roles.list. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.
  • launch-stage indica la fase di un ruolo nel ciclo di vita del lancio, come ALPHA, BETA o GA.

Esempi

L'esempio seguente illustra come creare un ruolo a livello di organizzazione utilizzando i flag:

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

Se il ruolo è stato creato, l'output del comando è simile al seguente:

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

L'esempio seguente mostra come creare un ruolo a livello di progetto utilizzando i flag:

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

Se il ruolo è stato creato, l'output del comando è simile al seguente:

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

REST

Il metodo roles.create crea un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • resource-type: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • resource-id: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, ad esempio my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • role-id: nome del ruolo, ad esempio myCompanyAdmin.
  • role-title: titolo leggibile per il ruolo. Ad esempio, My Company Admin.
  • role-description: una descrizione del ruolo. Ad esempio, "The company admin role allows company admins to access important resources".
  • permission-1 e permission-2: le autorizzazioni che vuoi includere nel ruolo. Ad esempio, storage.objects.update. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    Un ruolo personalizzato può contenere solo autorizzazioni supportate nei ruoli personalizzati. Se il ruolo personalizzato contiene altre autorizzazioni, la richiesta non andrà a buon fine.

  • launch-stage: fase di lancio attuale del ruolo. Questo campo può contenere uno dei seguenti valori: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Metodo HTTP e URL:

POST https://iam.googleapis.com/v1/resource-type/resource-id/roles

Corpo JSON richiesta:

{
  "roleId": "role-id",
  "role": {
    "title": "role-title",
    "description": "role-description",
    "includedPermissions": [
      "permission-1",
      "permission-2"
    ],
    "stage": "launch-stage"
  }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene il ruolo che hai creato.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

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

Modificare un ruolo personalizzato esistente

Un pattern comune per aggiornare i metadati di una risorsa, ad esempio un ruolo personalizzato, è il pattern read-modify-write. Con questo pattern devi leggere lo stato attuale del ruolo, aggiornare i dati localmente e inviare i dati modificati in scrittura.

Il pattern di lettura, modifica e scrittura può causare un conflitto se due o più processi indipendenti tentano di seguire la sequenza contemporaneamente. Ad esempio, se due proprietari di un progetto tentano di apportare modifiche in conflitto a un ruolo contemporaneamente, alcune modifiche potrebbero non riuscire. IAM risolve questo problema utilizzando una proprietà etag nei ruoli personalizzati. Questa proprietà viene utilizzata per verificare se il ruolo personalizzato è stato modificato dopo l'ultima richiesta. Quando effettui una richiesta a IAM con un valore etag, IAM confronta il valore etag nella richiesta con il valore etag esistente associato al ruolo personalizzato. Scrive la modifica solo se i valori etag corrispondono.

Quando aggiorni un ruolo, per prima cosa usa il ruolo roles.get(), aggiorna il ruolo, quindi scrivi il ruolo aggiornato utilizzando roles.patch(). Utilizza il valore etag quando imposti il ruolo solo se il ruolo corrispondente in roles.get() contiene un valore etag.

Console

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Utilizzando l'elenco a discesa nella parte superiore della pagina, seleziona il progetto o l'organizzazione che contiene il ruolo che vuoi modificare.

  3. Fai clic su un ruolo personalizzato.

  4. Fai clic su Modifica ruolo.

  5. Per aggiornare i metadati del ruolo, modifica il Titolo, la Descrizione o la Fase di avvio del ruolo.

  6. Per aggiornare le autorizzazioni del ruolo:

    1. Fai clic su Aggiungi autorizzazioni per aggiungere nuove autorizzazioni al ruolo.
    2. Deseleziona le autorizzazioni per rimuovere le autorizzazioni dal ruolo.
  7. Fai clic su Aggiorna per salvare il ruolo modificato.

gcloud CLI

Utilizza il comando gcloud iam roles update per aggiornare i ruoli personalizzati. Puoi utilizzare questo comando in due modi:

  • Fornendo un file YAML che contiene la definizione aggiornata del ruolo
  • Utilizzando i flag per specificare la definizione del ruolo aggiornata

Quando aggiorni un ruolo personalizzato, devi specificare se si applica a livello di organizzazione o di progetto utilizzando i flag --organization=organization-id o --project=project-id. Ciascun esempio seguente crea un ruolo personalizzato a livello di progetto.

Per aggiornare un ruolo personalizzato utilizzando un file YAML:

Ottieni la definizione corrente del ruolo eseguendo uno dei seguenti comandi:

  • Per ottenere la definizione del ruolo personalizzato a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles describe role-id --organization=organization-id
    
  • Per ottenere la definizione del ruolo personalizzato a livello di progetto, esegui il comando seguente:

    gcloud iam roles describe role-id --project=project-id
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo da aggiornare, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.

Il comando describe restituisce la definizione del ruolo e include un valore etag che identifica in modo univoco la versione corrente del ruolo. Il valore etag deve essere fornito nella definizione del ruolo aggiornata per garantire che le modifiche simultanee dei ruoli non vengano sovrascritte.

Il comando describe restituisce il seguente output:

description: role-description
etag: etag-value
includedPermissions:
- permission-1
- permission-2
name: role-name
stage: launch-stage
title: role-title

Ogni valore segnaposto è descritto di seguito:

  • role-description è una breve descrizione del ruolo, ad esempio "My custom role description".
  • etag-value è l'identificatore univoco della versione corrente del ruolo, ad esempio BwVkBkbfr70=.
  • permission-1 e permission-2 sono autorizzazioni da includere nel ruolo personalizzato, come iam.roles.get. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.
  • role-name è il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.
  • launch-stage indica la fase di un ruolo nel ciclo di vita del lancio, come ALPHA, BETA o GA.
  • role-title è un titolo descrittivo per il ruolo, ad esempio "My Company Admin".

Per aggiornare il ruolo, includi la definizione del ruolo emesso in un file YAML o aggiorna il file YAML originale con il valore etag emesso.

Esamina il seguente file YAML di esempio, che contiene l'output del comando describe per un ruolo a livello di progetto e aggiunge due autorizzazioni Cloud Storage:

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

Salva il file YAML, quindi esegui uno dei seguenti comandi:

  • Per aggiornare un ruolo a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles update role-id --organization=organization-id \
        --file=yaml-file-path
    
  • Per aggiornare un ruolo a livello di progetto, esegui il comando seguente:

    gcloud iam roles update role-id --project=project-id \
        --file=yaml-file-path
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo da aggiornare, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.
  • yaml-file-path è il percorso della posizione del file YAML che contiene la definizione aggiornata del ruolo personalizzato.

Esempi

L'esempio seguente mostra come aggiornare un ruolo a livello di organizzazione utilizzando un file YAML:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

Nell'esempio seguente viene illustrato come aggiornare un ruolo a livello di progetto utilizzando un file YAML:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

Per aggiornare un ruolo personalizzato utilizzando i flag:

Ogni parte della definizione di un ruolo può essere aggiornata utilizzando un flag corrispondente. Consulta l'argomento gcloud iam roles update per un elenco di tutti i possibili flag.

Per aggiungere o rimuovere le autorizzazioni:

  • --add-permissions=permissions: aggiunge al ruolo una o più autorizzazioni separate da virgole. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.
  • --remove-permissions=permissions: rimuove dal ruolo una o più autorizzazioni separate da virgole. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

In alternativa, puoi semplicemente specificare le nuove autorizzazioni utilizzando il flag --permissions=permissions e fornire un elenco di autorizzazioni separate da virgole per sostituire l'elenco delle autorizzazioni esistente.

Per aggiornare altre parti della definizione del ruolo, esegui uno dei seguenti comandi:

  • Per aggiornare un ruolo a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles update role-id --organization=organization-id \
        --title=role-title --description=role-description \
        --stage=launch-stage
    
  • Per aggiornare un ruolo a livello di progetto, esegui il comando seguente:

    gcloud iam roles update role-id --project=project-id \
        --title=role-title --description=role-description \
        --stage=launch-stage
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.
  • role-title è un titolo descrittivo per il ruolo, ad esempio "My Company Admin".
  • role-description è una breve descrizione del ruolo, ad esempio "My custom role description.".
  • launch-stage indica la fase di un ruolo nel ciclo di vita del lancio, come ALPHA, BETA o GA.

Esempi

L'esempio seguente mostra come aggiungere autorizzazioni a un ruolo a livello di organizzazione utilizzando i flag:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

L'esempio seguente mostra come aggiungere autorizzazioni a un ruolo a livello di progetto utilizzando i flag:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

REST

Il metodo roles.patch aggiorna un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Obbligatorio:

  • resource-type: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • resource-id: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, ad esempio my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • role-name: nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Consigliato:

  • etag: un identificatore per una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche del ruolo.

Facoltativo (definisci uno o più dei seguenti valori):

  • role-title: titolo leggibile per il ruolo. Ad esempio, My Company Admin.
  • role-description: una descrizione del ruolo. Ad esempio, "The company admin role allows company admins to access important resources".
  • permission-1 e permission-2: le autorizzazioni che vuoi includere nel ruolo. Ad esempio, storage.objects.update. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.
  • launch-stage: fase di lancio attuale del ruolo. Questo campo può contenere uno dei seguenti valori: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Metodo HTTP e URL:

PATCH https://iam.googleapis.com/v1/resource-type/resource-id/roles

Corpo JSON richiesta:

{
  "roleId": "full-role-id",
  "title": "role-title",
  "description": "role-description",
  "includedPermissions": [
    "permission-1",
    "permission-2"
  ],
  "stage": "launch-stage",
  "etag": "etag"
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene una definizione di ruolo abbreviata che include il nome del ruolo, i campi che hai aggiornato e un tag che identifica la versione corrente del ruolo.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

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

Disattivazione di un ruolo personalizzato

Puoi disattivare un ruolo personalizzato modificando la fase di lancio in DISABLED. Quando un ruolo è disabilitato, tutte le associazioni di ruolo correlate al ruolo vengono disattivate, il che significa che la concessione del ruolo a un utente non ha alcun effetto.

Console

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Fai clic sull'elenco a discesa "Seleziona un progetto" nella parte superiore della pagina.

  3. Seleziona la tua organizzazione o il tuo progetto.

  4. Seleziona un ruolo personalizzato e fai clic su Disattiva.

gcloud CLI

Utilizza il comando gcloud iam roles update per disabilitare un ruolo personalizzato impostando la fase di lancio su DISABLED. Come descritto nella scheda gcloud della sezione Modifica di un ruolo personalizzato esistente, puoi aggiornare un ruolo personalizzato esistente nei due modi seguenti:

  • Fornendo un file YAML che contiene la definizione aggiornata del ruolo
  • Utilizzando i flag per specificare la definizione del ruolo aggiornata

Il modo più semplice per disattivare un ruolo personalizzato esistente è utilizzare il flag --stage e impostarlo su DISABLED. Esegui uno dei seguenti comandi:

  • Per disattivare un ruolo a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles update role-id --organization=organization-id \
        --stage=DISABLED
    
  • Per disattivare un ruolo a livello di progetto, esegui il comando seguente:

    gcloud iam roles update role-id --project=project-id \
        --stage=DISABLED
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.

Esempi

L'esempio seguente mostra come disattivare un ruolo a livello di organizzazione:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

L'esempio seguente mostra come disattivare un ruolo a livello di progetto:

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

Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

REST

Il metodo roles.patch consente di modificare la fase di lancio di un ruolo personalizzato in DISABLED, disattivando il ruolo.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • resource-type: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • resource-id: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, ad esempio my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • role-name: nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.
  • etag: un identificatore per una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche del ruolo.

Metodo HTTP e URL:

PATCH https://iam.googleapis.com/v1/resource/resource-id/roles

Corpo JSON richiesta:

{
  "roleId": "full-role-id",
  "stage": DISABLED,
  "etag": "etag"
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

C++

Aggiorna il campo stage del ruolo in DISABLED.

C#

Aggiorna il campo stage del ruolo in DISABLED.

Go

Aggiorna il campo stage del ruolo in DISABLED.

Python

Aggiorna il campo stage del ruolo in DISABLED.

Ruoli elenco

Puoi elencare tutti i ruoli personalizzati creati nel progetto o nell'organizzazione.

Console

In Google Cloud Console, vai alla pagina Ruoli.

Vai alla pagina Ruoli

Tutti i ruoli personalizzati per l'organizzazione o il progetto che hai selezionato sono elencati nella pagina.

gcloud CLI

Utilizza il comando gcloud iam roles list per elencare i ruoli personalizzati e i ruoli predefiniti per un progetto o un'organizzazione:

  • Per elencare i ruoli personalizzati a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles list --organization=organization-id
    
  • Per elencare i ruoli personalizzati a livello di progetto, esegui il comando seguente:

    gcloud iam roles list --project=project-id
    

Ogni valore segnaposto è descritto di seguito:

  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.

Per elencare i ruoli eliminati, puoi anche specificare il flag --show-deleted.

Esegui il comando seguente per elencare i ruoli predefiniti:

gcloud iam roles list

REST

Il metodo roles.list elenca tutti i ruoli personalizzati di un progetto o un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • resource-type: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • resource-id: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, ad esempio my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • role-view: facoltativo. Le informazioni da includere per i ruoli restituiti. Per includere le autorizzazioni dei ruoli, imposta questo campo su FULL. Per escludere le autorizzazioni dei ruoli, imposta questo campo su BASIC. Il valore predefinito è BASIC.
  • page-size: facoltativo. Il numero di ruoli da includere nella risposta. Il valore predefinito è 300 e il valore massimo è 1000. Se il numero di ruoli è maggiore delle dimensioni della pagina, la risposta contiene un token di impaginazione che puoi utilizzare per recuperare la pagina successiva dei risultati.
  • next-page-token: facoltativo. Il token di impaginazione restituito in una risposta precedente da questo metodo. Se specificato, l'elenco dei ruoli inizierà da dove è terminata la richiesta precedente.

Metodo HTTP e URL:

GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "roles": [
    {
      "name": "projects/my-project/roles/customRole1",
      "title": "First Custom Role",
      "description": "Created on: 2020-06-01",
      "etag": "BwWiPg2fmDE="
    },
    {
      "name": "projects/my-project/roles/customRole2",
      "title": "Second Custom Role",
      "description": "Created on: 2020-06-07",
      "etag": "BwWiuX53Wi0="
    }
  ]
}

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

Eliminazione di un ruolo personalizzato

Puoi eliminare qualsiasi ruolo personalizzato nel tuo progetto o nella tua organizzazione.

Console

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona il ruolo che vuoi eliminare e fai clic su Elimina nella parte superiore della pagina.

gcloud CLI

Usa il comando gcloud iam roles delete per eliminare un ruolo personalizzato:

  • Per eliminare un ruolo personalizzato a livello di organizzazione, esegui il comando seguente:

    gcloud iam roles delete role-id --organization=organization-id
    
  • Per eliminare un ruolo personalizzato a livello di progetto, esegui il comando seguente:

    gcloud iam roles delete role-id --project=project-id
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.

Il ruolo non sarà incluso in gcloud iam roles list, a meno che non venga incluso il flag --show-deleted. I ruoli eliminati sono indicati dal blocco deleted: true in una risposta list, ad esempio:

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

REST

Il metodo roles.delete elimina un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • role-name: nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene la definizione del ruolo che è stato eliminato.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

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

Quando un ruolo viene eliminato, le associazioni di ruoli che fanno riferimento al ruolo rimangono nei criteri di autorizzazione, ma non hanno effetto. Puoi annullare l'eliminazione di un ruolo entro 7 giorni. Durante questo periodo di 7 giorni, la console Google Cloud mostra che il ruolo è stato eliminato. Puoi anche elencare i ruoli eliminati in modo programmatico, ma vengono omessi per impostazione predefinita.

Dopo 7-14 giorni, il ruolo viene pianificato per l'eliminazione permanente. A questo punto, il ruolo non rientra più nel limite di 300 ruoli personalizzati per organizzazione o di 300 ruoli personalizzati per progetto.

Il processo di eliminazione definitiva richiede 30 giorni. Durante il periodo di 30 giorni, il ruolo e tutte le associazioni associate vengono rimosse definitivamente e non puoi creare un nuovo ruolo con lo stesso ID ruolo.

Dopo che il ruolo è stato eliminato definitivamente, fino a 44 giorni dopo la richiesta di eliminazione iniziale, puoi creare un nuovo ruolo utilizzando lo stesso ID ruolo.

Annullamento dell'eliminazione di un ruolo personalizzato

L'annullamento dell'eliminazione di un ruolo comporta il ripristino dello stato precedente.

L'eliminazione dei ruoli può essere annullata solo entro 7 giorni. Dopo 7 giorni, il ruolo può essere eliminato definitivamente in qualsiasi momento e tutte le associazioni di ruoli che fanno riferimento al ruolo vengono rimosse.

Console

  1. In Google Cloud Console, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Individua il ruolo di cui vuoi annullare l'eliminazione, fai clic sull'icona Altro alla fine della riga e su Annulla eliminazione.

gcloud CLI

Utilizza il comando gcloud iam roles undelete per annullare l'eliminazione di un ruolo personalizzato:

  • Per annullare l'eliminazione di un ruolo personalizzato a livello di organizzazione, esegui questo comando:

    gcloud iam roles undelete role-id --organization=organization-id
    
  • Per annullare l'eliminazione di un ruolo personalizzato a livello di progetto, esegui il comando seguente:

    gcloud iam roles undelete role-id --project=project-id
    

Ogni valore segnaposto è descritto di seguito:

  • role-id è il nome del ruolo, ad esempio myCompanyAdmin.
  • organization-id è l'ID numerico dell'organizzazione, ad esempio 123456789012.
  • project-id è il nome del progetto, ad esempio my-project-id.

Esempi

L'esempio seguente mostra come annullare l'eliminazione di un ruolo personalizzato a livello di organizzazione:

gcloud iam roles undelete myCompanyAdmin --organization=123456789012

Se il ruolo è stato annullato correttamente, l'output del comando è simile al seguente:

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

Nell'esempio seguente viene illustrato come annullare l'eliminazione di un ruolo personalizzato a livello di progetto:

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

Se il ruolo è stato annullato correttamente, l'output del comando è simile al seguente:

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

REST

Il metodo roles.undelete annulla l'eliminazione di un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • role-name: nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.
  • etag: un identificatore per una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche del ruolo.

Metodo HTTP e URL:

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

Corpo JSON richiesta:

{
  "etag": "etag"
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

La risposta contiene la definizione del ruolo che è stato annullato.

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++.

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C#.


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

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, consulta la pagina sulle librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.

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

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

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

Passaggi successivi