Esta página foi traduzida pela API Cloud Translation.

Criar e aplicar políticas de limite de acesso principal

As políticas de limite de acesso principal (PAB) permitem limitar os recursos que um conjunto de principais pode acessar. Esta página explica como criar e aplicar políticas de limite de acesso de principal.

Antes de começar

Configure a autenticação.

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST

Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.
Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.
Leia a visão geral das políticas de limite de acesso de principal.

Funções necessárias para criar políticas de limite de acesso principal

Para receber a permissão necessária para criar políticas de limite de acesso de principal, peça ao administrador para conceder a você o papel do IAM de Administrador de limite de acesso de principal (roles/iam.principalAccessBoundaryAdmin) na sua organização. 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 a permissão iam.principalaccessboundarypolicies.create, necessária para criar políticas de limite de acesso de principal.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Funções necessárias para aplicar políticas de limite de acesso principal

As permissões necessárias para aplicar uma política de limite de acesso de principal dependem do conjunto de principais em que você quer aplicar a política.

Para ter as permissões necessárias para aplicar políticas de limite de acesso de principal, peça ao administrador para conceder a você os seguintes papéis do IAM:

Usuário do limite de acesso de principal (roles/iam.principalAccessBoundaryUser) na organização
Aplique políticas de limite de acesso de principal a pools da federação de identidade de colaboradores: Administrador de pool de colaboradores do IAM (roles/iam.workforcePoolAdmin) no pool de federação de identidade de colaboradores de destino
Aplique políticas de limite de acesso principal a pools da federação de identidade da carga de trabalho: Administrador de pool de Identidade da carga de trabalho do IAM (roles/iam.workloadIdentityPoolAdmin) no projeto que é proprietário do pool de federação da identidade de colaboradores de destino
Aplique políticas de limite de acesso de principal a um domínio do Google Workspace: Administrador do IAM do pool do Workspace (roles/iam.workspacePoolAdmin) na organização
Aplique políticas de limite de acesso de principal ao conjunto principal de um projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto
Aplique políticas de limite de acesso de principal ao conjunto principal de uma pasta: Administrador de IAM da pasta (roles/resourcemanager.folderIamAdmin) na pasta
Aplique políticas de limite de acesso de principal a um conjunto principal de uma organização: Administrador da organização (roles/resourcemanager.organizationAdmin) na organização

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para aplicar políticas de limite de acesso de principal. Para conferir 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 aplicar políticas de limite de acesso de principal:

iam.principalaccessboundarypolicies.bind na organização
Aplique políticas de limite de acesso principal a pools da federação de identidade de colaboradores: iam.workforcePools.createPolicyBinding no pool de federação de identidade de colaboradores de destino
Aplique políticas de limite de acesso principal a pools de federação de identidade da carga de trabalho: iam.workloadIdentityPools.createPolicyBinding no projeto que é proprietário do pool de federação de identidade de colaboradores de destino
Aplique as políticas de limite de acesso de principal a um domínio do Google Workspace: iam.workspacePools.createPolicyBinding na organização
Aplique as políticas de limite de acesso de principal ao conjunto principal de um projeto: resourcemanager.projects.createPolicyBinding no projeto
Aplique políticas de limite de acesso de principal ao conjunto principal de uma pasta: resourcemanager.folders.createPolicyBinding na pasta
Aplique políticas de limite de acesso de principal a um conjunto principal de uma organização: resourcemanager.organizations.createPolicyBinding na organização

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Criar uma política de limite de acesso principal

É possível criar uma política de limite de acesso principal usando o console do Google Cloud, a CLI gcloud ou a API REST do IAM.

Console

No console do Google Cloud, acesse a página Políticas de limite de acesso de principal.

Acesse as políticas de limite de acesso de principal
Selecione a organização para a qual você quer criar políticas de limite de acesso de principal.
Clique em Criar política.
Adicione regras de limite de acesso principal à política:
1. Clique em Adicionar regra de limite.
2. No campo Description, adicione uma descrição da regra de política de limite de acesso de principal. A descrição pode ter no máximo 256 caracteres.
3. Na seção Recursos, insira todos os recursos do Resource Manager (projetos, pastas e organizações) que você quer que os principais usuários tenham acesso. Qualquer principal que esteja sujeito a essa política pode acessar esses recursos.
  
  Cada política de limite de acesso de principal pode se referir a no máximo 500 recursos em todas as regras da política.
4. Clique em Concluído.
5. Para adicionar outras regras de política, repita estas etapas. Cada política de limite de acesso de principal pode ter até 500 regras.
Na seção Nome da política, insira um nome para a política. O nome pode ter no máximo 63 caracteres.
Na lista Versão de aplicação, selecione a versão de aplicação da política. A versão da política de limite de acesso principal determina para quais permissões o IAM aplica a política de limite de acesso principal.

Para mais informações sobre as versões de aplicação, consulte Versões de aplicação de limite de acesso de principal.
Clique em Criar.

gcloud

O comando gcloud beta iam principal-access-boundary-policies create cria uma política de limite de acesso principal.

Antes de usar os dados do comando abaixo, faça estas substituições:

ORG_ID: o ID da organização em que você quer criar a política de limite de acesso de principal. Os códigos da organização são numéricos, como 123456789012.
PAB_POLICY_ID: um ID exclusivo para a política de limite de acesso principal, por exemplo, example-policy. :
DISPLAY_NAME: opcional. Uma descrição legível por humanos da política de limite de acesso de principal como, 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 da política de limite de acesso principal. Esse arquivo precisa ter o seguinte formato:
```
{
  "description": DESCRIPTION,
  "resources": [
    RESOURCES
  ],
  "effect": ALLOW
}
    
```
Substitua os seguintes valores:
- DESCRIPTION: opcional. A descrição da regra de política de limite de acesso principal. A descrição pode ter no máximo 256 caracteres.
- RESOURCES: uma lista de recursos do Resource Manager (projetos, pastas e organizações) que você quer que os principais usuários tenham acesso. Qualquer principal que esteja sujeito a essa política pode acessar esses recursos.
  
  Cada política de limite de acesso de principal pode se referir a no máximo 500 recursos em todas as regras da política.
ENFORCEMENT_VERSION: a versão das políticas de limite de acesso de principal que o IAM usa ao aplicar a política. A versão de aplicação determina para quais permissões o IAM aplica a política de limite de acesso de principal.

Os valores aceitos são 1 e latest.

Para mais informações sobre as versões de aplicação, consulte Versões de aplicação de limite de acesso de principal.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta iam principal-access-boundary-policies create PAB_POLICY_ID \
    --organization=ORG_ID --location=global \
    --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json \
    --details-enforcement-version=ENFORCEMENT_VERSION

Windows (PowerShell)

gcloud beta iam principal-access-boundary-policies create PAB_POLICY_ID `
    --organization=ORG_ID --location=global `
    --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json `
    --details-enforcement-version=ENFORCEMENT_VERSION

Windows (cmd.exe)

gcloud beta iam principal-access-boundary-policies create PAB_POLICY_ID ^
    --organization=ORG_ID --location=global ^
    --display-name=DISPLAY_NAME --details-rules=FILE_PATH.json ^
    --details-enforcement-version=ENFORCEMENT_VERSION

A resposta contém uma operação de longa duração que representa a solicitação.

Create request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715373988044-6181fa136df85-3b06a30a-4816d25b] to complete...done.
Created principalAccessBoundaryPolicy [example-policy].

REST

O método principalAccessBoundaryPolicies.create cria uma política de limite de acesso de principal.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

ORG_ID: o ID da organização em que você quer criar a política de limite de acesso de principal. Os códigos da organização são numéricos, como 123456789012.
PAB_POLICY_ID: um ID exclusivo para a política de limite de acesso principal, por exemplo, example-policy.
DISPLAY_NAME: opcional. Uma descrição legível por humanos da política de limite de acesso de principal como, por exemplo, Example policy. O nome de exibição pode ter no máximo 63 caracteres.
PAB_RULES: uma lista de regras de limite de acesso de principal, que definem os recursos que os principais afetados podem acessar. Uma política de limite de acesso de principal pode ter até 500 regras. Cada regra tem o seguinte formato:
```
{
"description": "DESCRIPTION",
"resources": [
  RESOURCES
],
"effect": ALLOW
}
```
Substitua os seguintes valores:
- DESCRIPTION: opcional. A descrição da regra de política de limite de acesso de principal. A descrição pode ter no máximo 256 caracteres.
- RESOURCES: uma lista de recursos do Resource Manager (projetos, pastas e organizações) que você quer que os principais usuários tenham acesso. Qualquer principal que esteja sujeito a essa política pode acessar esses recursos.
  
  Cada política de limite de acesso de principal pode se referir a no máximo 500 recursos em todas as regras da política.
ENFORCEMENT_VERSION: a versão das políticas de limite de acesso de principal que o IAM usa ao aplicar a política. A versão de aplicação determina para quais permissões o IAM aplica a política de limite de acesso de principal.

Os valores aceitos são 1 e latest.

Para mais informações sobre as versões de aplicação, consulte Versões de aplicação de limite de acesso de principal.

Método HTTP e URL:

POST https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID

Corpo JSON da solicitação:

{
  "displayName": DISPLAY_NAME,
  "details": {
    "rules": [
      PAB_RULES
    ],
    "effect": ALLOW
    }
  ],
  "enforcementVersion": "ENFORCEMENT_VERSION"
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global?principalAccessBoundaryPolicyId=PAB_POLICY_ID" | Select-Object -Expand Content

A resposta contém uma operação de longa duração que representa a solicitação.

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:00.898809495Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-policy",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

Aplicar uma política de limite de acesso de principal a um conjunto de principais

Para aplicar uma política de limite de acesso de principal a um conjunto de principais, crie um recurso de vinculação de política que vincule a política ao conjunto de principais. Depois de criar uma vinculação de política, a política de limite de acesso de principal na vinculação é aplicada aos principais na vinculação.

É possível criar uma vinculação de política usando o console do Google Cloud, a CLI gcloud ou a API REST do IAM.

Console

No console do Google Cloud, acesse a página Políticas de limite de acesso de principal.

Acesse as políticas de limite de acesso de principal
Selecione a organização que tem a política de limite de acesso de principal para a qual você quer criar uma vinculação.
Clique no ID da política de limite de acesso de principal para a qual você quer criar uma vinculação.
Clique na guia Vinculações e em Adicionar vinculação.
Insira os detalhes da vinculação:
1. Opcional: no campo Nome de exibição, insira um nome de exibição para a vinculação. O nome de exibição pode ter no máximo 63 caracteres.
2. No campo ID da vinculação, insira um nome exclusivo para a vinculação, por exemplo, example-binding.
3. Na seção Target principal set, insira o tipo e o ID do conjunto de principais ao qual você quer vincular a política. Não é possível mudar esse valor depois de criar a vinculação de política.
  
  Para saber mais sobre os principais incluídos em cada conjunto, consulte Conjuntos principais compatíveis.
Opcional: para especificar para quais principais no conjunto a política de limite de acesso principal é aplicada, adicione uma condição à vinculação:
1. Clique em Adicionar condição.
2. No campo Título, insira um breve resumo da finalidade da condição.
3. Opcional: no campo Descrição, insira uma descrição mais longa da condição.
4. No campo Expressão, insira a expressão de condição que usa a sintaxe da Common Expression Language (CEL). A expressão precisa referenciar os atributos principal.type ou principal.subject. Outros atributos não são compatíveis.
5. Clique em Salvar.
Para criar a vinculação, clique em Adicionar.

gcloud

O comando gcloud beta iam policy-bindings create cria uma vinculação de política.

Antes de usar os dados do comando abaixo, faça estas substituições:

BINDING_ID: um nome exclusivo para a vinculação de política, por exemplo, example-binding.
RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) do qual a vinculação de políticas é filha. Use o valor project, folder ou organization

O tipo de recurso depende do principal definido na vinculação de políticas. Para saber qual tipo de recurso usar, consulte Tipos de principais aceitos.
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, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
ORG_ID: o ID da organização proprietária da política de limite de acesso de principal que você quer vincular ao conjunto de principais. Os IDs da organização são numéricos, como 123456789012.
PAB_POLICY_ID: o ID da política de limite de acesso de principal que você quer vincular ao conjunto de principal, por exemplo, example-pab-policy. Não é possível mudar esse valor depois de criar a vinculação de política.
PRINCIPAL_SET: o conjunto principal ao qual você quer vincular a política. Para uma lista de tipos principais válidos, consulte Conjuntos principais aceitos. Não é possível mudar esse valor depois de criar a vinculação de política.
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.
CONDITION_DETAILS: opcional. Uma expressão de condição que especifica para quais principais no conjunto a política de limite de acesso principal é aplicada. Contém os seguintes campos:
- expression: uma expressão de condição que usa a sintaxe Common Expression Language (CEL). A expressão precisa fazer referência aos atributos principal.type ou principal.subject. Outros atributos não são compatíveis.
  
  A expressão pode conter até 10 operadores lógicos (&&, ||, !) e ter até 250 caracteres de comprimento.
- title: opcional. Um breve resumo da finalidade da condição.
- description: opcional. Uma descrição mais longa da condição.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta iam policy-bindings create BINDING_ID \
    --RESOURCE_TYPE=RESOURCE_ID --location=global \
    --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" \
    --target-principal-set=PRINCIPAL_SET_ID \
    --display-name=DISPLAY_NAME \
    CONDITION_DETAILS

Windows (PowerShell)

gcloud beta iam policy-bindings create BINDING_ID `
    --RESOURCE_TYPE=RESOURCE_ID --location=global `
    --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" `
    --target-principal-set=PRINCIPAL_SET_ID `
    --display-name=DISPLAY_NAME `
    CONDITION_DETAILS

Windows (cmd.exe)

gcloud beta iam policy-bindings create BINDING_ID ^
    --RESOURCE_TYPE=RESOURCE_ID --location=global ^
    --policy="organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID" ^
    --target-principal-set=PRINCIPAL_SET_ID ^
    --display-name=DISPLAY_NAME ^
    CONDITION_DETAILS

A resposta contém uma operação de longa duração que representa a solicitação.

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 de política.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

RESOURCE_TYPE: o tipo de recurso do Resource Manager (projeto, pasta ou organização) do qual a vinculação de políticas é filha. Use o valor projects, folders ou organizations

O tipo de recurso depende do principal definido na vinculação de políticas. Para saber qual tipo de recurso usar, consulte Tipos de principais aceitos.
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, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
BINDING_ID: um nome exclusivo para a vinculação de política, 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.
PRINCIPAL_SET: o conjunto principal ao qual você quer vincular a política. Para uma lista de tipos principais válidos, consulte Conjuntos principais aceitos. Não é possível mudar esse valor depois de criar a vinculação de política.
ORG_ID: o ID da organização proprietária da política de limite de acesso de principal que você quer vincular ao conjunto de principais. Os IDs da organização são numéricos, como 123456789012.
PAB_POLICY_ID: o ID da política de limite de acesso de principal que você quer vincular ao conjunto de principal, por exemplo, example-pab-policy. Não é possível mudar esse valor depois de criar a vinculação de política.
CONDITION_DETAILS: opcional. Uma expressão de condição que especifica para quais principais no conjunto a política de limite de acesso principal é aplicada. Contém os seguintes campos:
- expression: uma expressão de condição que usa a sintaxe Common Expression Language (CEL). A expressão precisa fazer referência aos atributos principal.type ou principal.subject. Outros atributos não são compatíveis.
  
  A expressão pode conter até 10 operadores lógicos (&&, ||, !) e ter até 250 caracteres de comprimento.
- title: opcional. Um breve resumo da finalidade da condição.
- description: opcional. Uma descrição mais longa da condição.

Método HTTP e URL:

POST https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID

Corpo JSON da solicitação:

{
  "displayName": DISPLAY_NAME,
  "target": {
    "principalSet": PRINCIPAL_SET
  },
  "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
  "policy": "organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID",
  "condition": {
    CONDITION_DETAILS
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v3beta/RESOURCE_TYPE/RESOURCE_ID/locations/global/policyBindings?policyBindingId=BINDING_ID" | Select-Object -Expand Content

A resposta contém uma operação de longa duração que representa a solicitação.

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373120647-6181f6d8371d2-83309b71-2b8a7532",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:00.898809495Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-binding",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

Criar e aplicar políticas de limite de acesso principal

Antes de começar

Console

gcloud

REST

Funções necessárias para criar políticas de limite de acesso principal

Funções necessárias para aplicar políticas de limite de acesso principal

Permissões necessárias

Criar uma política de limite de acesso principal

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Aplicar uma política de limite de acesso de principal a um conjunto de principais

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

A seguir