Editar políticas de limite de acesso de 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 editar as políticas de limite de acesso de principal existentes e como editar as vinculações dessas políticas para alterar a quem elas são aplicáveis.

Antes de começar

  • Configure a autenticação.

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

    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.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    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.

Papéis necessários para editar políticas de limite de acesso de principal

Para receber a permissão necessária para editar as 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.update, necessária para excluir 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.

Papéis necessários para editar as vinculações de políticas de limite de acesso de principal

As permissões necessárias para editar vinculações de políticas para políticas de limite de acesso de principal dependem do conjunto de principais vinculado à política.

Para ter as permissões necessárias para editar vinculações de políticas para 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 sua organização
  • Edite as vinculações de políticas para políticas de limite de acesso de principal vinculadas a pools da federação de identidade de colaboradores: Administrador de pool de colaboradores do IAM (roles/iam.workforcePoolAdmin) no pool de identidade de colaboradores de destino
  • Edite as vinculações de políticas para políticas de limite de acesso de principal vinculadas a pools de 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 de identidade de colaboradores de destino
  • Edite vinculações de políticas para políticas de limite de acesso de principal vinculadas a um domínio do Google Workspace: Administrador do IAM do pool do Workspace (roles/iam.workspacePoolAdmin) na organização
  • Edite as vinculações de políticas para políticas de limite de acesso de principal vinculadas ao conjunto de principais de um projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto
  • Edite as vinculações de políticas para políticas de limite de acesso de principal vinculadas ao conjunto principal de uma pasta: Administrador de IAM da pasta (roles/resourcemanager.folderIamAdmin) na pasta
  • Edite as vinculações de políticas para políticas de limite de acesso de principal vinculadas 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 excluir vinculações de políticas para 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 editar vinculações de políticas para políticas de limite de acesso de principal:

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

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

Editar uma política de limite de acesso de principal

Se você quiser adicionar regras a uma política de limite de acesso de principal, remover regras de uma política de limite de acesso de principal ou modificar os metadados de uma política de limite de acesso de principal, edite a política de limite de acesso de principal.

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

Console

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

  2. Selecione a organização que tem a política de limite de acesso de principal que você quer editar.

  3. Clique no ID da política de limite de acesso de principal que você quer editar.

  4. Clique em Editar política.

  5. Para editar as regras da política, faça o seguinte:

    1. Clique na regra que você quer editar.
    2. Edite a descrição da regra ou os recursos incluídos nela.
    3. Clique em Concluído.

  6. Para excluir uma regra da política, clique em Excluir na linha dela.

  7. Para editar o nome de exibição da política, edite o campo Nome de exibição.

  8. Para editar a versão de aplicação da política, clique na lista Versão de aplicação e escolha um novo valor.

  9. Clique em Salvar.

gcloud

O comando gcloud beta iam principal-access-boundary-policies update atualiza uma política de limite de acesso de principal existente.

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

  • PAB_POLICY_ID: o ID da política de limite de acesso de principal que você quer excluir como, por exemplo, example-policy.
  • ORG_ID: o ID da organização proprietária da política de limite de acesso de principal. Os códigos da organização são numéricos, como 123456789012.

  • 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 política por DISPLAY_NAME.
    • --details-enforcement-version=ENFORCEMENT_VERSION: atualize a versão de aplicação da política para ENFORCEMENT_VERSION.

    • --details-rules=RULES_FILE.json: substitua as regras da política de limite de acesso de principal pelas regras em RULES_FILE.json. Para saber como formatar o arquivo de regras, consulte Criar uma política de limite de acesso de principal.

      Se você usar essa flag, não poderá usar a flag --add-details-rules.

    • --add-details-rules=RULES_FILE: adiciona as regras ao final em RULES_FILE.json às regras existentes da política. Para saber como formatar o arquivo de regras, consulte Criar uma política de limite de acesso de principal.

      Se você usar essa flag, não poderá usar a flag --details-rules.

    • --remove-details-rules=RULES_FILE: remova as regras em RULES_FILE.json das regras atuais da política. Para saber como formatar o arquivo de regras, consulte Criar uma política de limite de acesso de principal. Somente as regras que correspondem exatamente a uma das regras em RULES_FILE.json são removidas.

      Se você usar essa flag, não poderá usar a flag --clear-rule-details.

    • --clear-details-rules: limpar todas as regras da política de limite de acesso de principal.

      Se você usar essa flag, não poderá usar a flag --remove-rule-details.

    Para conferir uma lista completa de flags que podem ser usadas para atualizar uma política de limite de acesso de principal, consulte a referência do comando gcloud beta iam principal-access-boundary-policies update.

  • FORMAT: o formato da resposta. Use json ou yaml.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID \
    --organization=ORG_ID --location=global \
    --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows (PowerShell)

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID `
    --organization=ORG_ID --location=global `
    --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows (cmd.exe)

gcloud beta iam principal-access-boundary-policies update PAB_POLICY_ID ^
    --organization=ORG_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 política de limite de acesso de principal atualizada. 

Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated principalAccessBoundaryPolicy [example-policy].
{
  "name": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-policy",
  "uid": "puid_13364150419245236225",
  "etag": "W/\"Gh/PcTdJD/AWHUhPW45kdw==\"",
  "displayName": "Updated display name",
  "createTime": "2024-05-07T00:05:48.295209Z",
  "updateTime": "2024-05-10T20:50:09.200421Z",
  "details": [
    "rules": {
      [
        "description": "Make principals eligible to access example.com"
        "resources": {
          "//cloudresourcemanager.googleapis.com/organizations/123456789012"
        },
        "effect": ALLOW
      ]
    },
    "enforcementVersion": "1"
  ]
}

REST

O metódo principalAccessBoundaryPolicies.patch atualiza uma política de limite de acesso de principal existente.

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

  • ORG_ID: o ID da organização proprietária da política de limite de acesso de principal. Os códigos 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 excluir como, por exemplo, example-policy.

  • FIELDS_TO_UPDATE: uma lista separada por vírgulas de campos que você quer atualizar. Se você não especificar os campos a serem atualizados, o IAM vai substituir a política atual pelo conteúdo do corpo da solicitação.

    Os valores aceitos são displayName, details, details.rules, details.rules.description, details.rules.resources, details.rules.effect e details.enforcementVersion.

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

PATCH https://iam.googleapis.com/v3beta/organizations/ORG_ID/locations/global/principalAccessBoundaryPolicies/PAB_POLICY_ID?updateMask=FIELDS_TO_UPDATE

Corpo JSON da solicitação:

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

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.

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-13T18:58:43.721277235Z",
    "target": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-policy",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

Mudar para quem uma política de limite de acesso de principal é aplicada

Depois de criar uma vinculação de política para uma política de limite de acesso de principal, não é possível mudar o ID da política ou o principal definido na vinculação. Como resultado, se você quiser mudar para quem uma política de limite de acesso de principal é aplicada, faça uma das seguintes ações:

  • Para refinar o conjunto de principais em que uma política de limite de acesso de principal é aplicada, modifique as condições na vinculação de políticas. Para modificar as condições em uma vinculação, edite a vinculação de política.
  • Para aplicar a política de limite de acesso de principal a outro conjunto de principais, crie uma nova vinculação de política que vincule a política a esse conjunto.
  • Para remover uma política de limite de acesso de principal de um conjunto de principais, exclua a vinculação da política ao conjunto.

Editar as vinculações de políticas atuais para políticas de limite de acesso de principal

Depois de criar uma vinculação de política, você pode editar a vinculação para modificar as condições ou o nome de exibição dela.

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

Console

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

  2. Selecione a organização que tem a política de limite de acesso de principal que você quer editar.

  3. Clique no ID da política de limite de acesso de principal com as vinculações que você quer editar.

  4. Clique na guia Vinculações.

  5. Encontre o ID da vinculação que você quer editar. Na linha da vinculação, clique em Ações e, em seguida, em Editar vinculação.

  6. Para atualizar o nome de exibição da política, edite o campo Nome de exibição.

  7. Para adicionar uma condição à vinculação, faça o seguinte:

    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.

  8. Para atualizar uma condição existente, faça o seguinte:

    1. Clique em Editar condição ao lado do nome da condição.
    2. Atualize o título, a descrição ou a expressão da condição.
    3. Clique em Salvar.

  9. Para salvar as alterações, clique em Save.

gcloud

O comando gcloud beta iam policy-bindings update atualiza uma vinculação de política existente.

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

  • BINDING_ID: o ID da vinculação de política que você quer atualizar como, 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.

  • 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 em uma vinculação de política:

    • --display-name=DISPLAY_NAME: substitua o nome de exibição da política por DISPLAY_NAME.
    • --condition-description=CONDITION_DESCRIPTION: se a vinculação tiver uma condição, substitua a descrição dela por CONDITION_DESCRIPTION. Caso contrário, adicione uma nova condição à vinculação com a descrição especificada. Se você usar essa flag para atualizar uma vinculação que não tem uma condição, também precisará definir a flag --condition-expression.
    • --condition-expression=CONDITION_EXPRESSION: se a vinculação tiver uma condição, substitua a expressão da condição por CONDITION_EXPRESSION. Caso contrário, adicione uma nova condição à vinculação com a expressão especificada.
    • --condition-title=CONDITION_TITLE: se a vinculação tiver uma condição, substitua o título da condição por CONDITION_TITLE. Caso contrário, adicione uma nova condição à vinculação com o título especificado. Se você usar essa flag para atualizar uma vinculação que não tem uma condição, também precisará definir a flag --condition-expression.

    Para uma lista completa de campos que podem ser atualizados, consulte a referência do comando gcloud beta iam policy-bindings update.

  • FORMAT: o formato da resposta. Use json ou yaml.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta iam policy-bindings update BINDING_ID \
    --RESOURCE_TYPE=RESOURCE_ID --location=global \
    --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows (PowerShell)

gcloud beta iam policy-bindings update BINDING_ID `
    --RESOURCE_TYPE=RESOURCE_ID --location=global `
    --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows (cmd.exe)

gcloud beta iam policy-bindings update BINDING_ID ^
    --RESOURCE_TYPE=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.

Update request issued for: [my-binding]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374545618-6181fc272c6f9-55ff07f4-97d0ac76] to complete...done.
Updated policyBinding [my-binding].
{
  "createTime": "2024-05-06T18:08:24.729843Z",
  "displayName": "Updated display name",
  "etag": "W/\"xkdnPfTxoxyVqOwhQSJbMg==\"",
  "name": "organizations/123456789012/locations/global/policyBindings/example-binding",
  "policy": "organizations/123456789012/locations/global/principalAccessBoundaryPolicies/example-pab-policy",
  "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
  "policyUid": "puid_9519202237377675265",
  "target": {
    "principalSet": "//cloudresourcemanager.googleapis.com/organizations/123456789012"
  },
  "uid": "buid_9904260005517852673", 
  "updateTime": "2024-05-06T18:11:16.798841Z"
}

REST

O método policyBindings.patch atualiza uma vinculação de política existente.

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: o ID da vinculação de política que você quer atualizar como, por exemplo, example-binding.

  • FIELDS_TO_UPDATE: uma lista separada por vírgulas de campos que você quer atualizar. Se você não especificar os campos a serem atualizados, o IAM vai substituir a vinculação atual pelo conteúdo do corpo da solicitação.

    Os valores aceitos são displayName, condition, condition.expression, condition.title e condition.description.

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

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "displayName": DISPLAY_NAME,
  "condition": {
    CONDITION_DETAILS
  }
}

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.

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715373159010-6181f6fcccfa7-dcd0055c-00c22cad",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3beta.OperationMetadata",
    "createTime": "2024-05-10T20:32:39.254910121Z",
    "target": "organizations/123456789012/locations/global/policyBindings/example-binding",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v3beta"
  },
  "done": false
}

A seguir