As políticas de acesso unificadas (UAPs) permitem conceder e negar aos principais o acesso aos recursos doGoogle Cloud . Neste documento, explicamos como editar as UAPs existentes e modificar os recursos a que uma UAP se aplica.
Antes de começar
Configure a autenticação.
Selecione a guia para como planeja usar as amostras nesta página:
Console
Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.
gcloud
No console do Google Cloud , ative o Cloud Shell.
Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
REST
Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.
Instale a CLI do Google Cloud.
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Opcional. Leia a visão geral das UAPs.
Funções exigidas
Para receber as permissões necessárias para editar UAPs, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de acesso (roles/iam.accessPolicyAdmin) no projeto, na pasta ou na organização que possui a UAP que você quer editar.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esse papel predefinido contém as permissões necessárias para editar UAPs. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para editar UAPs:
-
iam.accesspolicies.update -
Editar UAPs no console do Google Cloud :
-
iam.accesspolicies.get -
iam.accessPolicies.list
-
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Editar uma Política de Acesso Unificada
É possível editar uma UAP para atualizar o nome de exibição ou as regras dela.
É possível editar uma UAP usando o Google Cloud console, a CLI gcloud ou a API REST do IAM.
Console
-
No console do Google Cloud , acesse a página Políticas de acesso unificadas.
Acesse as políticas de acesso unificadas - Selecione o projeto, a pasta ou a organização que possui a UAP que você quer editar.
- Clique no ID da política de UAP que você quer editar.
-
Para adicionar regras, clique em Adicionar regra de anúncio e insira os detalhes da regra. Para salvar a regra, clique em Adicionar regra.
Para saber mais sobre os campos de uma regra, consulte Criar uma UAP.
- Para editar outros campos da UAP, clique em Editar política.
-
Edite qualquer um dos seguintes campos:
- Nome da política: insira um novo nome de exibição para a UAP.
- Regras: atualize, adicione ou remova regras na UAP.
- Quando terminar de editar a UAP, clique em Atualizar política.
gcloud
O comando
gcloud iam access-policies update
atualiza uma UAP atual.
Antes de usar os dados do comando abaixo, faça estas substituições:
-
UAP_ID: o ID da UAP que você quer atualizar, por exemplo,example-policy. -
UAP_PARENT_RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) que é proprietário da UAP que você quer atualizar. Use o valorproject,folderouorganization. -
UAP_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização que é proprietária da UAP que você quer atualizar. Os IDs do projeto são strings alfanuméricas, comomy-project. Os IDs de pastas e organizações são numéricos, como123456789012. -
FIELD_TO_UPDATE=UPDATED_VALUE: os campos que você quer atualizar e o valor atualizado correspondente.Confira abaixo exemplos de flags que podem ser usadas para atualizar os campos na política:
-
--display-name=DISPLAY_NAME: substitua o nome de exibição da UAP pelo nome especificado. -
--details-rules=RULES_FILE: substitui as regras de UAP pelas regras no arquivo especificado. Cada regra no arquivo precisa ter o seguinte formato:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
Substitua os seguintes valores:
-
DESCRIPTION: uma descrição legível por humanos da regra. -
EFFECT: como a regra afeta o acesso. Os valores compatíveis sãoALLOWeDENY:-
ALLOW: conceder as permissões especificadas aos principais especificados. -
DENY: impede que os principais especificados usem as permissões especificadas.
-
-
Substitua os seguintes valores para especificar os principais incluídos na regra:
-
INCLUDED_PRINCIPALS: os principais a serem incluídos na regra. -
EXCLUDED_PRINCIPALS: opcional. Os principais a serem excluídos da regra, mesmo que estejam na lista de principais incluídos. Por exemplo, é possível adicionar um grupo do Google à lista de principais incluídos e, em seguida, excluir usuários específicos que pertencem a esse grupo.
Para uma lista de identificadores principais compatíveis, consulte Tipos de principais para UAPs.
-
-
Substitua os seguintes valores para especificar as permissões a serem incluídas na regra:
-
INCLUDED_PERMISSIONS: as permissões a serem incluídas na regra. -
EXCLUDED_PERMISSIONS: opcional. As permissões a serem excluídas da regra, mesmo que estejam na lista de permissões incluídas. Por exemplo, é possível adicionar um papel à lista de permissões incluídas e, em seguida, excluir permissões específicas desse papel.
Ao criar essas listas de permissões, é possível referenciar nomes de permissões, nomes de papéis e grupos de permissões. Para saber mais, consulte Papéis e permissões nas regras de UAP.
-
-
CONDITIONS: opcional. As condições em que a regra se aplica. Use o seguinte formato:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
Substitua os seguintes valores:
-
SERVICE: o serviço que fornece os atributos usados na expressão de condição. -
CONDITION_TITLE: opcional. Um breve resumo da finalidade da condição. -
CONDITION_DESCRIPTION: opcional. Uma descrição mais longa da condição. -
CONDITION_EXPRESSION: uma expressão booleana que faz referência a atributos da tentativa de acesso, como as tags anexadas ao recurso na tentativa de acesso. Se a expressão for avaliada comotrue, a regra será aplicada à tentativa de acesso. Se for avaliada comofalse, a regra não será aplicada à tentativa de acesso.
Para uma lista de atributos de suporte e os serviços deles, consulte Atributos de condição compatíveis.
-
-
-
--add-details-rules=RULES_FILE: adiciona as regras no arquivo especificado ao final das regras atuais na UAP. -
--remove-details-rules=RULES_FILE: remove as regras no arquivo especificado das regras atuais na UAP. Somente as regras que correspondem exatamente a uma das regras no arquivo especificado são removidas. -
--clear-details-rules: limpa todas as regras da UAP.
Para conferir uma lista completa de flags que podem ser usadas para atualizar uma UAP, consulte a referência do comando
gcloud iam access-policies update. Algumas flags são mutuamente exclusivas. -
FORMAT: o formato da resposta. Usejsonouyaml.
Execute o seguinte comando:
Linux, macOS ou 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
A resposta contém uma operação de longa duração que representa a solicitação. Depois que a operação for concluída, a resposta vai mostrar a UAP atualizada.
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
O método accessPolicies.patch atualiza uma UAP atual.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
UAP_PARENT_RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) que é proprietário da UAP que você quer atualizar. Use o valorprojects,foldersouorganizations. -
UAP_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização que é proprietária da UAP que você quer atualizar. Os IDs do projeto são strings alfanuméricas, comomy-project. Os IDs de pastas e organizações são numéricos, como123456789012. -
UAP_ID: o ID da UAP que você quer atualizar, por exemplo,example-policy. DISPLAY_NAME: opcional. Uma descrição legível por humanos da UAP, por exemplo,Example policy. O nome de exibição pode ter no máximo 63 caracteres.-
UAP_RULES: uma lista de regras de UAP, que definem o acesso a ser concedido ou negado e os principais que terão o acesso concedido ou negado. Uma UAP pode ter até 100 regras. Cada regra tem o seguinte formato:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
Substitua os seguintes valores:
-
DESCRIPTION: uma descrição legível por humanos da regra. -
EFFECT: como a regra afeta o acesso. Os valores compatíveis sãoALLOWeDENY:-
ALLOW: conceder as permissões especificadas aos principais especificados. -
DENY: impede que os principais especificados usem as permissões especificadas.
-
-
Substitua os seguintes valores para especificar os principais incluídos na regra:
-
INCLUDED_PRINCIPALS: os principais a serem incluídos na regra. -
EXCLUDED_PRINCIPALS: opcional. Os principais a serem excluídos da regra, mesmo que estejam na lista de principais incluídos. Por exemplo, é possível adicionar um grupo do Google à lista de principais incluídos e, em seguida, excluir usuários específicos que pertencem a esse grupo.
Para uma lista de identificadores principais compatíveis, consulte Tipos de principais para UAPs.
-
-
Substitua os seguintes valores para especificar as permissões a serem incluídas na regra:
-
INCLUDED_PERMISSIONS: as permissões a serem incluídas na regra. -
EXCLUDED_PERMISSIONS: opcional. As permissões a serem excluídas da regra, mesmo que estejam na lista de permissões incluídas. Por exemplo, é possível adicionar um papel à lista de permissões incluídas e, em seguida, excluir permissões específicas desse papel.
Ao criar essas listas de permissões, é possível referenciar nomes de permissões, nomes de papéis e grupos de permissões. Para saber mais, consulte Papéis e permissões nas regras de UAP.
-
-
CONDITIONS: opcional. As condições em que a regra se aplica. Use o seguinte formato:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
Substitua os seguintes valores:
-
SERVICE: o serviço que fornece os atributos usados na expressão de condição. -
CONDITION_TITLE: opcional. Um breve resumo da finalidade da condição. -
CONDITION_DESCRIPTION: opcional. Uma descrição mais longa da condição. -
CONDITION_EXPRESSION: uma expressão booleana que faz referência a atributos da tentativa de acesso, como as tags anexadas ao recurso na tentativa de acesso. Se a expressão for avaliada comotrue, a regra será aplicada à tentativa de acesso. Se for avaliada comofalse, a regra não será aplicada à tentativa de acesso.
Para uma lista de atributos de suporte e os serviços deles, consulte Atributos de condição compatíveis.
-
-
Método HTTP e URL:
PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID
Corpo JSON da solicitação:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
UAP_RULES
]
}
}
Para enviar a solicitação, expanda uma destas opções:
A resposta contém uma operação de longa duração que representa a solicitação. Para saber como ver o status de uma operação de longa duração, consulte Verificar o status de uma operação de longa duração nesta página.
{
"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
}
Mudar os recursos aos quais a política se aplica
Depois de criar uma vinculação para uma UAP, não é possível mudar o ID da política ou o recurso na vinculação. Como resultado, se você quiser mudar o recurso ao qual uma UAP se aplica, faça uma das seguintes ações:
- Para aplicar a UAP a outro recurso, crie uma nova vinculação que vincule a UAP a esse recurso.
- Para remover uma UAP de um recurso, exclua a vinculação que vincula a UAP ao recurso.
Verificar o status de uma operação de longa duração
Quando você usa a API REST ou as bibliotecas de cliente, qualquer método que altere uma política ou vinculação retorna uma operação de longa duração (LRO, na sigla em inglês). A operação de longa duração rastreia o status da solicitação e indica se a alteração na política ou na vinculação foi concluída.
REST
O método operations.get retorna o status de uma operação de longa duração.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
OPERATION_NAME: o nome completo da operação. Você recebe esse nome na resposta à sua solicitação original.O nome da operação tem o seguinte formato:
RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
Método HTTP e URL:
GET https://iam.googleapis.com/v3/OPERATION_NAME
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{
"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 o campo done da operação não estiver presente, continue monitorando
o status dela recebendo a operação repetidamente. Use a espera exponencial truncada para
introduzir um atraso entre cada solicitação. Quando o campo done estiver definido como true, a operação será concluída e você poderá interromper a operação.