Le Unified Access Policies (UAP) ti consentono di concedere e negare alle entità l'accesso alle risorseGoogle Cloud . Questo documento spiega come modificare gli UAP esistenti e le risorse a cui si applicano.
Prima di iniziare
Configurare l'autenticazione.
Seleziona la scheda relativa al modo in cui prevedi di utilizzare gli esempi in questa pagina:
Console
Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.
gcloud
Nella console Google Cloud , attiva Cloud Shell.
Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.
REST
Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.
Installa Google Cloud CLI.
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .
-
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .
Facoltativo. Leggi la panoramica delle UAP.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per modificare le UAP, chiedi all'amministratore di concederti il ruolo IAM Amministratore policy di accesso (roles/iam.accessPolicyAdmin) nel progetto, nella cartella o nell'organizzazione proprietaria della UAP che vuoi modificare.
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene le autorizzazioni necessarie per modificare gli UAP. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per modificare gli UAP sono necessarie le seguenti autorizzazioni:
-
iam.accesspolicies.update -
Modifica le UAP nella console Google Cloud :
-
iam.accesspolicies.get -
iam.accessPolicies.list
-
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Modifica una policy Unified Access Policy esistente
Puoi modificare una policy di accesso unificato per aggiornarne il nome visualizzato o le regole.
Puoi modificare una policy di accesso utente (UAP) utilizzando la console Google Cloud , gcloud CLI o l'API REST IAM.
Console
-
Nella console Google Cloud , vai alla pagina Policy di accesso unificato.
Vai a Policy di accesso unificato - Seleziona il progetto, la cartella o l'organizzazione proprietaria della UAP che vuoi modificare.
- Fai clic sull'ID della policy dell'UAP che desideri modificare.
-
Per aggiungere regole per gli annunci, fai clic su Aggiungi regola per gli annunci e poi aggiungi i dettagli della regola per gli annunci. Per salvare la regola, fai clic su Aggiungi regola.
Per scoprire di più sui campi di una regola, consulta Crea una UAP.
- Per modificare altri campi della policy di accesso utente, fai clic su Modifica policy.
-
Modifica uno dei seguenti campi:
- Nome policy: inserisci un nuovo nome visualizzato per la UAP.
- Regole: aggiorna, aggiungi o rimuovi le regole nella UAP.
- Al termine della modifica della UAP, fai clic su Aggiorna policy.
gcloud
Il comando gcloud iam access-policies update aggiorna un UAP esistente.
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
-
UAP_ID: l'ID della piattaforma di attivazione utente che vuoi aggiornare, ad esempioexample-policy. -
UAP_PARENT_RESOURCE_TYPE: il tipo di risorsa Resource Manager (progetto, cartella o organizzazione) proprietaria della UAP che vuoi aggiornare. Utilizza il valoreproject,folderoorganization. -
UAP_PARENT_RESOURCE_ID: l'ID del progetto, della cartella o dell'organizzazione proprietaria della UAP che vuoi aggiornare. Gli ID progetto sono stringhe alfanumeriche, comemy-project. Gli ID cartella e ID organizzazione sono numerici, ad esempio123456789012. -
FIELD_TO_UPDATE=UPDATED_VALUE: i campi che vuoi aggiornare e il valore aggiornato corrispondente.Di seguito sono riportati esempi di flag che puoi utilizzare per aggiornare i campi della policy:
-
--display-name=DISPLAY_NAME: sostituisci il nome visualizzato della piattaforma di accesso utente con il nome specificato. -
--details-rules=RULES_FILE: sostituisce le regole UAP con le regole nel file specificato. Ogni regola nel file deve avere il seguente formato:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
Sostituisci i seguenti valori:
-
DESCRIPTION: una descrizione della regola leggibile da una persona. -
EFFECT: l'impatto della regola sull'accesso. I valori supportati sonoALLOWeDENY:-
ALLOW: concede le autorizzazioni specificate alle entità specificate. -
DENY: impedisce alle entità specificate di utilizzare le autorizzazioni specificate.
-
-
Sostituisci i seguenti valori per specificare le entità incluse nella regola:
-
INCLUDED_PRINCIPALS: le entità da includere nella regola. -
EXCLUDED_PRINCIPALS: (Facoltativo) Le entità da escludere dalla regola, anche se sono presenti nell'elenco delle entità incluse. Ad esempio, puoi aggiungere un gruppo Google all'elenco delle entità incluse, quindi escludere utenti specifici che appartengono a quel gruppo.
Per un elenco degli identificatori delle entità supportati, consulta Tipi di entità per le UAP.
-
-
Sostituisci i seguenti valori per specificare le autorizzazioni da includere nella regola:
-
INCLUDED_PERMISSIONS: le autorizzazioni da includere nella regola. -
EXCLUDED_PERMISSIONS: (Facoltativo) Le autorizzazioni da escludere dalla regola, anche se sono presenti nell'elenco delle autorizzazioni incluse. Ad esempio, puoi aggiungere un ruolo all'elenco delle autorizzazioni incluse, quindi escludere autorizzazioni specifiche in quel ruolo.
Quando crei questi elenchi di autorizzazioni, puoi fare riferimento ai nomi delle autorizzazioni, ai nomi dei ruoli e ai gruppi di autorizzazioni. Per scoprire di più, consulta Ruoli e autorizzazioni nelle regole UAP.
-
-
CONDITIONS: (Facoltativo) Le condizioni in base alle quali viene applicata la regola. Utilizza il formato seguente:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
Sostituisci i seguenti valori:
-
SERVICE: il servizio che fornisce gli attributi utilizzati nell'espressione della condizione. -
CONDITION_TITLE: (Facoltativo) Un breve riepilogo dello scopo della condizione. -
CONDITION_DESCRIPTION: (Facoltativo) Una descrizione più lunga della condizione. -
CONDITION_EXPRESSION: un'espressione booleana che fa riferimento agli attributi del tentativo di accesso, ad esempio i tag associati alla risorsa nel tentativo di accesso. Se l'espressione restituiscetrue, la regola viene applicata al tentativo di accesso. Se restituiscefalse, la regola non viene applicata al tentativo di accesso.
Per un elenco degli attributi di supporto e dei relativi servizi, consulta Attributi di supporto supportati.
-
-
-
--add-details-rules=RULES_FILE: aggiungi le regole nel file specificato alle regole esistenti nell'UAP. -
--remove-details-rules=RULES_FILE: rimuovi le regole nel file specificato dalle regole esistenti nell'UAP. Vengono rimosse solo le regole che corrispondono esattamente a una delle regole nel file specificato. -
--clear-details-rules: cancella tutte le regole dalla UAP.
Per un elenco completo dei flag che puoi utilizzare per aggiornare un criterio di accesso utente, consulta il riferimento dei comandi
gcloud iam access-policies update. Alcuni flag si escludono a vicenda. -
FORMAT: il formato della risposta. Utilizzajsonoyaml.
Esegui questo comando:
Linux, macOS o Cloud Shell
gcloud iam access-policies update UAP_ID \ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE \ --format=FORMAT
Windows (PowerShell)
gcloud iam access-policies update UAP_ID ` --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ` --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ` --format=FORMAT
Windows (cmd.exe)
gcloud iam access-policies update UAP_ID ^ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ^ --format=FORMAT
La risposta contiene un'operazione a lunga esecuzione che rappresenta la tua richiesta. Al termine dell'operazione, la risposta stampa l'UAP aggiornato.
Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated accessPolicy [example-policy].
{
"createTime": "2026-08-31T21:43:39.822441Z",
"details": {
"rules": [
{
"conditions": {
"iam.googleapis.com": {
"expression": "resource.matchTag('environment', 'prod')"
}
},
"description": "Grant non-delete compute permissions to compute admins in prod",
"effect": "ALLOW",
"excludedPrincipals": [
"principal://goog/subject/access-restricted@example.com"
],
"operation": {
"excludedPermissions": [
"*/*.delete"
],
"permissions": [
"role:roles/compute.admin"
]
},
"principals": [
"principalSet://goog/group/compute-admins@example.com"
]
}
]
},
"displayName": "Updated display name",
"etag": "W/\"YZtdQgtulCVzvTwlBTFjPQ==\"",
"name": "projects/0123456789012/locations/global/accessPolicies/example-policy",
"uid": "puid_0123456789012345678",
"updateTime": "2026-08-31T21:43:39.822441Z"
}
REST
Il metodo accessPolicies.patch aggiorna un UAP esistente.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
-
UAP_PARENT_RESOURCE_TYPE: il tipo di risorsa Resource Manager (progetto, cartella o organizzazione) proprietaria della UAP che vuoi aggiornare. Utilizza il valoreprojects,foldersoorganizations. -
UAP_PARENT_RESOURCE_ID: l'ID del progetto, della cartella o dell'organizzazione proprietaria della UAP che vuoi aggiornare. Gli ID progetto sono stringhe alfanumeriche, comemy-project. Gli ID cartella e ID organizzazione sono numerici, ad esempio123456789012. -
UAP_ID: l'ID della piattaforma di attivazione utente che vuoi aggiornare, ad esempioexample-policy. DISPLAY_NAME: (Facoltativo) Una descrizione della policy di accesso utente leggibile da una persona, ad esempioExample policy. Il nome visualizzato può contenere un massimo di 63 caratteri.-
UAP_RULES: un elenco di regole UAP, che definiscono l'accesso da concedere o negare e le entità a cui concedere o negare l'accesso. Un UAP può avere fino a 100 regole. Ogni regola ha il seguente formato:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
Sostituisci i seguenti valori:
-
DESCRIPTION: una descrizione della regola leggibile da una persona. -
EFFECT: l'impatto della regola sull'accesso. I valori supportati sonoALLOWeDENY:-
ALLOW: concede le autorizzazioni specificate alle entità specificate. -
DENY: impedisce alle entità specificate di utilizzare le autorizzazioni specificate.
-
-
Sostituisci i seguenti valori per specificare le entità incluse nella regola:
-
INCLUDED_PRINCIPALS: le entità da includere nella regola. -
EXCLUDED_PRINCIPALS: (Facoltativo) Le entità da escludere dalla regola, anche se sono presenti nell'elenco delle entità incluse. Ad esempio, puoi aggiungere un gruppo Google all'elenco delle entità incluse, quindi escludere utenti specifici che appartengono a quel gruppo.
Per un elenco degli identificatori delle entità supportati, consulta Tipi di entità per le UAP.
-
-
Sostituisci i seguenti valori per specificare le autorizzazioni da includere nella regola:
-
INCLUDED_PERMISSIONS: le autorizzazioni da includere nella regola. -
EXCLUDED_PERMISSIONS: (Facoltativo) Le autorizzazioni da escludere dalla regola, anche se sono presenti nell'elenco delle autorizzazioni incluse. Ad esempio, puoi aggiungere un ruolo all'elenco delle autorizzazioni incluse, quindi escludere autorizzazioni specifiche in quel ruolo.
Quando crei questi elenchi di autorizzazioni, puoi fare riferimento ai nomi delle autorizzazioni, ai nomi dei ruoli e ai gruppi di autorizzazioni. Per scoprire di più, consulta Ruoli e autorizzazioni nelle regole UAP.
-
-
CONDITIONS: (Facoltativo) Le condizioni in base alle quali viene applicata la regola. Utilizza il formato seguente:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
Sostituisci i seguenti valori:
-
SERVICE: il servizio che fornisce gli attributi utilizzati nell'espressione della condizione. -
CONDITION_TITLE: (Facoltativo) Un breve riepilogo dello scopo della condizione. -
CONDITION_DESCRIPTION: (Facoltativo) Una descrizione più lunga della condizione. -
CONDITION_EXPRESSION: un'espressione booleana che fa riferimento agli attributi del tentativo di accesso, ad esempio i tag associati alla risorsa nel tentativo di accesso. Se l'espressione restituiscetrue, la regola viene applicata al tentativo di accesso. Se restituiscefalse, la regola non viene applicata al tentativo di accesso.
Per un elenco degli attributi di supporto e dei relativi servizi, consulta Attributi di supporto supportati.
-
-
Metodo HTTP e URL:
PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID
Corpo JSON della richiesta:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
UAP_RULES
]
}
}
Per inviare la richiesta, espandi una di queste opzioni:
La risposta contiene un'operazione a lunga esecuzione che rappresenta la tua richiesta. Per scoprire come ottenere lo stato di un'operazione a lunga esecuzione, consulta Controlla lo stato di un'operazione a lunga esecuzione in questa pagina.
{
"name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-13T18:58:43.721277235Z",
"target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
"verb": "update",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
Modifica le risorse a cui si applica la policy
Dopo aver creato un'associazione per una UAP, non puoi modificare l'ID della policy o la risorsa nell'associazione. Di conseguenza, se vuoi modificare la risorsa a cui si applica un criterio di accesso utente, devi eseguire una delle seguenti operazioni:
- Per applicare la policy di accesso uniforme a un'altra risorsa, crea una nuova associazione che associa la policy di accesso uniforme a quella risorsa.
- Per rimuovere un UAP da una risorsa, elimina l'associazione che associa l'UAP alla risorsa.
Controlla lo stato di un'operazione a lunga esecuzione
Quando utilizzi l'API REST o le librerie client, qualsiasi metodo che modifica una policy o un'associazione restituisce un'operazione a lunga esecuzione (LRO). L'operazione a lunga esecuzione monitora lo stato della richiesta e indica se la modifica della policy o dell'associazione è stata completata.
REST
Il metodo operations.get restituisce lo stato di un'operazione a lunga esecuzione.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
-
OPERATION_NAME: il nome completo dell'operazione. Ricevi questo nome nella risposta alla tua richiesta originale.Il nome dell'operazione ha il seguente formato:
RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
Metodo HTTP e URL:
GET https://iam.googleapis.com/v3/OPERATION_NAME
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "organizations/314340013352/locations/global/operations/operation-1732752311821-627edd607a3df-9a62cdea-2a7d9f07",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-11-28T00:05:12.006289686Z",
"endTime": "2024-11-28T00:05:12.192141801Z",
"target": "organizations/314340013352/locations/global/POLICY_TYPE/POLICY_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": true,
"response": {
POLICY
}
}
Se il campo done dell'operazione non è presente, continua a monitorare lo stato recuperando ripetutamente l'operazione. Utilizza il backoff esponenziale troncato per introdurre un ritardo tra ogni richiesta. Quando il campo done è impostato su true, l'operazione è completata e puoi interrompere il recupero dell'operazione.
Passaggi successivi
- Crea e applica i profili di attività degli utenti
- Visualizza le associazioni e le policy di accesso degli utenti
- Rimuovi gli UAP