Editar políticas de acceso unificado

Las políticas de acceso unificado (UAP) te permiten otorgar y denegar el acceso de las principales a los recursos deGoogle Cloud . En este documento, se explica cómo editar las UAP existentes y modificar los recursos a los que se aplica una UAP.

Antes de comenzar

  1. Configura la autenticación.

    Selecciona la pestaña según cómo planeas usar las muestras de esta página:

    Console

    Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud , no necesitas configurar la autenticación.

    gcloud

    En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

    REST

    Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

      Instala Google Cloud CLI.

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .

  2. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  3. Es opcional. Lee la descripción general de las UAP.

Roles obligatorios

Para obtener los permisos que necesitas para editar las UAP, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de acceso (roles/iam.accessPolicyAdmin) en el proyecto, la carpeta o la organización que posee la UAP que deseas editar . Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para editar las UAP. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para editar las UAP:

  • iam.accesspolicies.update
  • Edita los UAP en la consola de Google Cloud :
    • iam.accesspolicies.get
    • iam.accessPolicies.list

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Edita una Política de acceso unificado existente

Puedes editar una UAP para actualizar su nombre visible o sus reglas.

Puedes editar una UAP con la consola de Google Cloud , gcloud CLI o la API de REST de IAM.

Console

  1. En la consola de Google Cloud , ve a la página Políticas de acceso unificado.

    Ir a Políticas de acceso unificado
  2. Selecciona el proyecto, la carpeta o la organización que posee la UAP que deseas editar.
  3. Haz clic en el ID de la política de acceso de usuario que deseas editar.
  4. Para agregar reglas, haz clic en Agregar regla y, luego, agrega los detalles de la regla. Para guardar la regla, haz clic en Agregar regla.

    Para obtener más información sobre los campos de una regla, consulta Crea una UAP.

  5. Para editar otros campos de la UAP, haz clic en Editar política.
  6. Edita cualquiera de los siguientes campos:

    • Nombre de la política: Ingresa un nombre visible nuevo para la UAP.
    • Reglas: Actualiza, agrega o quita reglas en la UAP.
  7. Cuando termines de editar la UAP, haz clic en Actualizar política.

gcloud

El comando gcloud iam access-policies update actualiza una UAP existente.

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • UAP_ID: Es el ID de la UAP que deseas actualizar, por ejemplo, example-policy.
  • UAP_PARENT_RESOURCE_TYPE: Es el tipo de recurso de Resource Manager (proyecto, carpeta u organización) que posee la UAP que deseas actualizar. Usa el valor project, folder o organization.
  • UAP_PARENT_RESOURCE_ID: Es el ID del proyecto, la carpeta o la organización que posee la UAP que deseas actualizar. Los ID de proyecto son strings alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
  • FIELD_TO_UPDATE=UPDATED_VALUE: Los campos que deseas actualizar y el valor actualizado correspondiente.

    Los siguientes son ejemplos de marcas que puedes usar para actualizar los campos de la política:

    • --display-name=DISPLAY_NAME: Reemplaza el nombre visible de la UAP por el nombre especificado.
    • --details-rules=RULES_FILE: Reemplaza las reglas de UAP por las reglas del archivo especificado. Cada regla del archivo debe tener el siguiente formato:

      {
        "description": "DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          INCLUDED_PRINCIPALS
        ],
        "excludedPrincipals": [
          EXCLUDED_PRINCIPALS
        ],
        "operation": {
          "permissions": [
            INCLUDED_PERMISSIONS
          ],
          "excludedPermissions": [
            EXCLUDED_PERMISSIONS
          ]
        },
        CONDITIONS
      }

      Reemplaza los siguientes valores:

      • DESCRIPTION: Es una descripción legible por humanos para la regla.
      • EFFECT: Indica cómo afecta la regla al acceso. Los valores admitidos son ALLOW y DENY:

        • ALLOW: Otorga los permisos especificados a las principales especificadas.
        • DENY: Impide que las principales especificadas usen los permisos especificados.
      • Reemplaza los siguientes valores para especificar las principales incluidas en la regla:

        • INCLUDED_PRINCIPALS: Son las principales que se incluirán en la regla.
        • EXCLUDED_PRINCIPALS: Opcional Son las principales que se excluirán de la regla, incluso si están en la lista de principales incluidas. Por ejemplo, puedes agregar un Grupo de Google a la lista de principales incluidos y, luego, excluir a usuarios específicos que pertenecen a ese grupo.

        Para obtener una lista de los identificadores de principal compatibles, consulta Tipos de principales para UAP.

      • Reemplaza los siguientes valores para especificar los permisos que se incluirán en la regla:

        • INCLUDED_PERMISSIONS: Son los permisos que se incluirán en la regla.
        • EXCLUDED_PERMISSIONS: Opcional Son los permisos que se excluirán de la regla, incluso si están en la lista de permisos incluidos. Por ejemplo, puedes agregar un rol a la lista de permisos incluidos y, luego, excluir permisos específicos de ese rol.

        Cuando crees estas listas de permisos, puedes hacer referencia a los nombres de los permisos, los nombres de los roles y los grupos de permisos. Para obtener más información, consulta Roles y permisos en las reglas de UAP.

      • CONDITIONS: Opcional Son las condiciones en las que se aplica la regla. Usa el siguiente formato:

        "conditions": {
          "SERVICE": {
            "title": "CONDITION_TITLE",
            "description": "CONDITION_DESCRIPTION",
            "expression": "CONDITION_EXPRESSION"
          }
        }
            

        Reemplaza los siguientes valores:

        • SERVICE: Es el servicio que proporciona los atributos que se usan en la expresión de condición.
        • CONDITION_TITLE: Opcional Es un breve resumen del propósito de la condición.
        • CONDITION_DESCRIPTION: Opcional Es una descripción más larga de la condición.
        • CONDITION_EXPRESSION: Es una expresión booleana que hace referencia a los atributos del intento de acceso, como las etiquetas adjuntas al recurso en el intento de acceso. Si la expresión se evalúa como true, la regla se aplica al intento de acceso. Si se evalúa como false, la regla no se aplica al intento de acceso.

        Para obtener una lista de los atributos admitidos y sus servicios, consulta Atributos de condición admitidos.

    • --add-details-rules=RULES_FILE: Agrega las reglas del archivo especificado a las reglas existentes en la UAP.

    • --remove-details-rules=RULES_FILE: Quita las reglas del archivo especificado de las reglas existentes en la UAP. Solo se quitan las reglas que coinciden exactamente con una de las reglas del archivo especificado.

    • --clear-details-rules: Borra todas las reglas de la UAP.

    Para obtener una lista completa de las marcas que puedes usar para actualizar una UAP, consulta la referencia del comando gcloud iam access-policies update. Algunas marcas son mutuamente excluyentes.

  • FORMAT: Es el formato de la respuesta. Usa json o yaml.

Ejecuta el siguiente 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 respuesta contiene una operación de larga duración que representa tu solicitud. Una vez que se completa la operación, la respuesta imprime la UAP actualizada.

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

El método accessPolicies.patch actualiza una UAP existente.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • UAP_PARENT_RESOURCE_TYPE: Es el tipo de recurso de Resource Manager (proyecto, carpeta u organización) que posee la UAP que deseas actualizar. Usa el valor projects, folders o organizations.
  • UAP_PARENT_RESOURCE_ID: Es el ID del proyecto, la carpeta o la organización que posee la UAP que deseas actualizar. Los ID de proyecto son strings alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
  • UAP_ID: Es el ID de la UAP que deseas actualizar, por ejemplo, example-policy.
  • DISPLAY_NAME: Opcional Es una descripción legible por humanos de la UAP, por ejemplo, Example policy. El nombre visible puede tener un máximo de 63 caracteres.
  • UAP_RULES: Es una lista de reglas de UAP que definen el acceso que se otorgará o denegará, y las principales a las que se otorgará o denegará el acceso. Una UAP puede tener hasta 100 reglas. Cada regla tiene el siguiente formato:

    {
      "description": "DESCRIPTION",
      "effect": "EFFECT",
      "principals": [
        INCLUDED_PRINCIPALS
      ],
      "excludedPrincipals": [
        EXCLUDED_PRINCIPALS
      ],
      "operation": {
        "permissions": [
          INCLUDED_PERMISSIONS
        ],
        "excludedPermissions": [
          EXCLUDED_PERMISSIONS
        ]
      },
      CONDITIONS
    }

    Reemplaza los siguientes valores:

    • DESCRIPTION: Es una descripción legible por humanos para la regla.
    • EFFECT: Indica cómo afecta la regla al acceso. Los valores admitidos son ALLOW y DENY:

      • ALLOW: Otorga los permisos especificados a las principales especificadas.
      • DENY: Impide que las principales especificadas usen los permisos especificados.
    • Reemplaza los siguientes valores para especificar las principales incluidas en la regla:

      • INCLUDED_PRINCIPALS: Son las principales que se incluirán en la regla.
      • EXCLUDED_PRINCIPALS: Opcional Son las principales que se excluirán de la regla, incluso si están en la lista de principales incluidas. Por ejemplo, puedes agregar un Grupo de Google a la lista de principales incluidos y, luego, excluir a usuarios específicos que pertenecen a ese grupo.

      Para obtener una lista de los identificadores de principal compatibles, consulta Tipos de principales para UAP.

    • Reemplaza los siguientes valores para especificar los permisos que se incluirán en la regla:

      • INCLUDED_PERMISSIONS: Son los permisos que se incluirán en la regla.
      • EXCLUDED_PERMISSIONS: Opcional Son los permisos que se excluirán de la regla, incluso si están en la lista de permisos incluidos. Por ejemplo, puedes agregar un rol a la lista de permisos incluidos y, luego, excluir permisos específicos de ese rol.

      Cuando crees estas listas de permisos, puedes hacer referencia a los nombres de los permisos, los nombres de los roles y los grupos de permisos. Para obtener más información, consulta Roles y permisos en las reglas de UAP.

    • CONDITIONS: Opcional Son las condiciones en las que se aplica la regla. Usa el siguiente formato:

      "conditions": {
        "SERVICE": {
          "title": "CONDITION_TITLE",
          "description": "CONDITION_DESCRIPTION",
          "expression": "CONDITION_EXPRESSION"
        }
      }
          

      Reemplaza los siguientes valores:

      • SERVICE: Es el servicio que proporciona los atributos que se usan en la expresión de condición.
      • CONDITION_TITLE: Opcional Es un breve resumen del propósito de la condición.
      • CONDITION_DESCRIPTION: Opcional Es una descripción más larga de la condición.
      • CONDITION_EXPRESSION: Es una expresión booleana que hace referencia a los atributos del intento de acceso, como las etiquetas adjuntas al recurso en el intento de acceso. Si la expresión se evalúa como true, la regla se aplica al intento de acceso. Si se evalúa como false, la regla no se aplica al intento de acceso.

      Para obtener una lista de los atributos admitidos y sus servicios, consulta Atributos de condición admitidos.

Método HTTP y URL:

PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID

Cuerpo JSON de la solicitud:

{
  "displayName": "DISPLAY_NAME",
  "details": {
    "rules": [
      UAP_RULES
    ]
  }
}

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene una operación de larga duración que representa tu solicitud. Para aprender a obtener el estado de una operación de larga duración, consulta Verifica el estado de una operación de larga duración en esta 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
}

Cambia los recursos a los que se aplica la política

Después de crear una vinculación para una UAP, no puedes cambiar el ID de la política ni el recurso en la vinculación. Como resultado, si quieres cambiar el recurso al que se aplica una UAP, debes realizar una de las siguientes acciones:

Revisa el estado de una operación de larga duración

Cuando usas la API de REST o las bibliotecas cliente, cualquier método que cambie una política o vinculación devuelve una operación de larga duración (LRO). La operación de larga duración realiza un seguimiento del estado de la solicitud y también indica si se completó el cambio en la política o la vinculación.

REST

El método operations.get muestra el estado de una operación de larga duración.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • OPERATION_NAME: Es el nombre completo de la operación. Recibirás este nombre en la respuesta a tu solicitud original.

    El nombre de la operación tiene el siguiente formato:

    RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
        

Método HTTP y URL:

GET https://iam.googleapis.com/v3/OPERATION_NAME

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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
  }
}

Si el campo done de la operación no está presente, sigue supervisando su estado obteniendo la operación de forma repetida. Usa la retirada exponencial truncada para introducir un retraso entre cada solicitud. Cuando el campo done se establece como true, la operación está completa, y puedes dejar de obtener la operación.

¿Qué sigue?