As políticas de acesso unificadas (UAPs) permitem conceder e negar aos principais o acesso aos recursos doGoogle Cloud . Neste documento, explicamos como criar e aplicar UAPs.
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 dos UAPs.
Papéis necessários para criar Políticas de Acesso Unificadas
Para receber as permissões necessárias para criar 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 em que você quer criar a política.
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 criar 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 criar UAPs:
-
iam.accesspolicies.create -
Crie UAPs no console do Google Cloud :
iam.accesspolicies.list
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Papéis necessários para aplicar políticas de acesso unificadas
Para receber as permissões necessárias para vincular um UAP a um recurso, peça ao administrador para conceder a você os seguintes papéis do IAM:
- Administrador de políticas de acesso (
roles/iam.accessPolicyAdmin) no recurso que possui a UAP. Esse papel contém a permissãoiam.accesspolicies.bind, que é necessária para criar vinculações. Um papel que inclui a permissão
SERVICE.RESOURCE.createPolicyBinding, em queRESOURCEé o tipo de recurso ao qual você quer vincular a política eSERVICEé o serviço que possui o recurso.Para encontrar um papel que inclua a permissão necessária, pesquise a permissão na referência de papéis e permissões, clique no nome da permissão e analise os papéis que a incluem.
Você precisa desse papel no recurso ou em um dos ancestrais dele.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Criar uma Política de Acesso Unificada
É possível criar UAPs 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 em que você quer criar a UAP. Para orientações sobre onde criar uma UAP, consulte Onde criar UAPs.
- Clique em Criar política.
-
No campo Nome da política, insira um nome para a
UAP, por exemplo,
Example policy. O nome pode ter no máximo 63 caracteres. - Opcional: no campo ID da política, personalize o ID da UAP.
-
Adicione regras à política. Para cada regra, faça o seguinte:
- Opcional: no campo Descrição, insira uma descrição para a regra.
- No campo Principais, insira os principais que você quer incluir na regra.
- Opcional: no campo Principais excluídos, insira os principais que você não quer incluir na regra. Esses principais não serão incluídos, mesmo que façam parte de um grupo no campo Principais.
-
Selecione o efeito que você quer que a regra tenha:
- Para conceder as permissões especificadas aos principais especificados, selecione o efeito Permitir.
- Para impedir que os principais especificados usem as permissões especificadas, selecione o efeito Negar.
-
Selecione as permissões que serão incluídas na regra:
- Para regras com o efeito Permitir, é possível especificar papéis e permissões para incluir ou excluir da regra. Para mais informações sobre os papéis e as permissões que podem ser incluídos, consulte Papéis e permissões em regras de UAP.
- Para regras com o efeito Negar, especifique as permissões que você quer incluir ou excluir da regra. Para mais informações sobre as permissões que podem ser incluídas, consulte Papéis e permissões em regras de UAP.
-
Opcional: adicione condições para a aplicação da regra. Para saber mais sobre os atributos de condição compatíveis, consulte Condições em UAPs.
- Quando terminar de editar a regra, clique em Concluído.
- Para adicionar outra regra, clique em Adicionar regra e insira os detalhes dela.
- Quando terminar de adicionar regras, clique em Criar política.
gcloud
O comando
gcloud iam access-policies create
cria um UAP.
Antes de usar os dados do comando abaixo, faça estas substituições:
-
UAP_ID: um ID exclusivo para o UAP, por exemplo,example-policy. -
UAP_PARENT_RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) em que você quer criar a UAP. Use o valorproject,folderouorganization. -
UAP_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização em que você quer criar o UAP. Os IDs do projeto são strings alfanuméricas, comomy-project. Os IDs de pastas e organizações são numéricos, como123456789012. 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.-
FILE_PATH: o caminho para um arquivo JSON que contém os detalhes da regra de UAP. Cada regra 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.
-
-
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud iam access-policies create UAP_ID \ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \ --location=global --display-name=DISPLAY_NAME \ --details-rules=FILE_PATH
Windows (PowerShell)
gcloud iam access-policies create UAP_ID ` --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ` --location=global --display-name=DISPLAY_NAME ` --details-rules=FILE_PATH
Windows (cmd.exe)
gcloud iam access-policies create UAP_ID ^ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^ --location=global --display-name=DISPLAY_NAME ^ --details-rules=FILE_PATH
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.
Create request issued for: [example-policy] Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715373988044-6181fa136df85-3b06a30a-4816d25b] to complete...done. Created accessPolicy [example-policy].
REST
O método accessPolicies.create cria uma UAP.
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) em que você quer criar a UAP. Use o valorprojects,foldersouorganizations. -
UAP_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização em que você quer criar o UAP. 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: um ID exclusivo para o UAP, 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:
POST https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies?accessPolicyId=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-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-10T20:32:00.898809495Z",
"target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
Aplicar uma política de acesso unificada a um recurso
Para aplicar uma UAP a um recurso, crie uma vinculação. Depois de criar uma vinculação para uma política, as regras dela entram em vigor para o recurso atribuído e qualquer um de seus descendentes.
Antes de criar uma vinculação, verifique se a
restrição de política da organização
iam.managed.disableAccessPolicyBinding está desativada. Para saber como
ativar ou desativar essa restrição, consulte Como usar restrições gerenciadas em uma
política da organização.
É possível aplicar UAPs a projetos, pastas e organizações usando o Google Cloud console, a CLI gcloud ou a API REST do IAM. Para aplicar UAPs a outros recursos, use 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 aplicar.
- Clique no ID da UAP que você quer aplicar.
- Selecione a guia Vinculações e clique em Adicionar vinculação.
-
No painel Adicionar vinculação, edite os detalhes da vinculação:
- No menu Local de vinculação, selecione o recurso ao qual você quer aplicar a UAP.
-
Opcional: no campo Nome de exibição da vinculação, insira uma
descrição legível por humanos da vinculação, por exemplo,
Example binding. O nome de exibição pode ter no máximo 63 caracteres. -
No campo ID da vinculação, insira um nome exclusivo para a vinculação, por exemplo,
example-binding.
- Clique em Adicionar vinculação.
gcloud
O comando
gcloud iam policy-bindings create
cria uma vinculação.
Antes de usar os dados do comando abaixo, faça estas substituições:
-
BINDING_ID: um nome exclusivo para a vinculação, por exemplo,example-binding. -
BINDING_PARENT_RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) do qual a vinculação é filha. Use o valorproject,folderouorganization.O recurso pai da vinculação depende do recurso de destino na vinculação. Consulte Recursos suportados para saber mais.
-
BINDING_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização de que a vinculação de políticas é filha. Os IDs do projeto são strings alfanuméricas, comomy-project. Os IDs de pastas e organizações são numéricos, como123456789012. -
POLICY_PARENT_RESOURCE: o recurso em que o UAP foi criado, no formatoRESOURCE_TYPE/RESOURCE_ID. Por exemplo,organizations/0123456789012. As UAPs podem ser criadas em projetos, pastas ou organizações. Os IDs de pastas e organizações precisam ser numéricos. Os IDs de projeto podem ser numéricos ou alfanuméricos. -
UAP_ID: o ID da UAP que você quer vincular ao recurso, por exemplo,example-uap. Não é possível alterar esse valor depois de criar a vinculação. -
TARGET_RESOURCE: o recurso ao qual você quer vincular a UAP. Para ver uma lista de recursos válidos, consulte Recursos compatíveis. Não é possível alterar esse valor depois de criar a vinculação. DISPLAY_NAME: opcional. Uma descrição legível por humanos da vinculação, por exemplo,Example binding. O nome de exibição pode ter no máximo 63 caracteres.
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud iam policy-bindings create BINDING_ID \ --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global \ --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" \ --target-resource=TARGET_RESOURCE \ --display-name=DISPLAY_NAME
Windows (PowerShell)
gcloud iam policy-bindings create BINDING_ID ` --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global ` --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" ` --target-resource=TARGET_RESOURCE ` --display-name=DISPLAY_NAME
Windows (cmd.exe)
gcloud iam policy-bindings create BINDING_ID ^ --BINDING_PARENT_RESOURCE_TYPE=BINDING_PARENT_RESOURCE_ID --location=global ^ --policy="POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID" ^ --target-resource=TARGET_RESOURCE ^ --display-name=DISPLAY_NAME
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.
Create request issued for: [example-binding] Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374545618-6181fc272c6f9-55ff07f4-97d0ac76] to complete...done. Created policyBinding [example-binding].
REST
O método policyBindings.create cria uma vinculação.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
BINDING_PARENT_RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) do qual a vinculação é filha. Use o valorprojects,foldersouorganizations.O recurso pai da vinculação depende do recurso de destino na vinculação. Consulte Recursos suportados para saber mais.
-
BINDING_PARENT_RESOURCE_ID: o ID do projeto, da pasta ou da organização de que a vinculação de políticas é filha. Os IDs do projeto são strings alfanuméricas, comomy-project. Os IDs de pastas e organizações são numéricos, como123456789012. -
BINDING_ID: um nome exclusivo para a vinculação, por exemplo,example-binding. DISPLAY_NAME: opcional. Uma descrição legível por humanos da vinculação, por exemplo,Example binding. O nome de exibição pode ter no máximo 63 caracteres.-
TARGET_RESOURCE: o recurso ao qual você quer vincular a UAP. Para ver uma lista de recursos válidos, consulte Recursos compatíveis. Não é possível alterar esse valor depois de criar a vinculação. -
POLICY_PARENT_RESOURCE: o recurso em que o UAP foi criado, no formatoRESOURCE_TYPE/RESOURCE_ID. Por exemplo,organizations/0123456789012. As UAPs podem ser criadas em projetos, pastas ou organizações. Os IDs de pastas e organizações precisam ser numéricos. Os IDs de projeto podem ser numéricos ou alfanuméricos. -
UAP_ID: o ID da UAP que você quer vincular ao recurso, por exemplo,example-uap. Não é possível alterar esse valor depois de criar a vinculação.
Método HTTP e URL:
POST https://iam.googleapis.com/v3/BINDING_PARENT_RESOURCE_TYPE/BINDING_PARENT_RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID
Corpo JSON da solicitação:
{
"displayName": "DISPLAY_NAME",
"target": {
"resource": "TARGET_RESOURCE"
},
"policyKind": "ACCESS",
"policy": "POLICY_PARENT_RESOURCE/locations/global/accessPolicies/UAP_ID"
}
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-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-10T20:32:00.898809495Z",
"target": "organizations/123456789012/locations/global/policyBindings/example-binding",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
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.