Administra el acceso de los agentes implementados

Existen diferentes tipos de métodos de autenticación disponibles para los distintos modos de acceso:

Caso de uso Método de autenticación Acerca de este método de autenticación
Accede a las fuentes de datos directamente desde un agente. Cuenta de servicio Los agentes implementados tienen acceso a todos los recursos a los que su cuenta de servicio tiene permiso para acceder.
Enviar solicitudes a extremos con claves de API desde un agente Claves de API Verifica que la API que quieras usar admita claves de API antes de usar este método de autenticación.
Administrar las cuentas de usuario, el registro, el acceso o la autorización de los usuarios finales del agente ID de cliente de OAuth Requiere que tu agente solicite y reciba el consentimiento del usuario.

Funciones

Los agentes que implementas en Vertex AI Agent Engine se ejecutan con el agente de servicio de AI Platform Reasoning Engine o tu cuenta de servicio personalizada. Consulta Configura la identidad y los permisos de tu agente para obtener más información.

Agente de servicio de AI Platform Reasoning Engine

La cuenta de servicio del agente de servicio de AI Platform Reasoning Engine usa el formato service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

La cuenta de servicio tiene un rol de agente de servicio de Vertex AI Reasoning Engine (roles/aiplatform.reasoningEngineServiceAgent) que otorga los permisos predeterminados necesarios para los agentes implementados. Puedes ver la lista completa de permisos predeterminados en la documentación de IAM.

Enumera los roles de un agente implementado

Console

  1. Ir a la página IAM.

    Ir a IAM

  2. Selecciona el proyecto que corresponde a tu proyecto Google Cloud .

  3. Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.

  4. Los roles del agente implementado se encuentran en la columna Rol.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

donde

  • PROJECT_ID_OR_NUMBER es el ID o número de tu proyecto.
  • PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.

Para obtener más detalles, consulta la documentación de IAM y la referencia de la CLI.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-api-python-client

Luego, autentícate y ejecuta el siguiente comando para enumerar los roles de un agente implementado:

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

Aquí, el PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.

Otorga roles para un agente implementado

  1. Ir a la página IAM.

    Ir a IAM

  2. Selecciona el proyecto que corresponde a tu proyecto Google Cloud .

  3. Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.

  4. Para agregar los roles necesarios a la principal, haz clic en el botón Editar, agrega los roles y, luego, haz clic en el botón Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

donde

  • PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.
  • ROLE_NAME es el nombre del rol que deseas otorgar. Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

Para obtener más detalles, consulta la documentación de IAM y la referencia de la CLI.

Python

No recomendamos escribir tu propio código de Python para otorgar o revocar roles para los agentes implementados. En su lugar, recomendamos usar Google Cloud console o gcloud para operaciones únicas, o bien Terraform para administrar el control de acceso de IAM de forma programática. Si deseas o necesitas hacerlo en Python, consulta la documentación de la biblioteca cliente de IAM.

Revoca roles de un agente implementado

  1. Ir a la página IAM.

    Ir a IAM

  2. Selecciona el proyecto que corresponde a tu proyecto Google Cloud .

  3. Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.

  4. Para revocar los roles de la principal, haz clic en el botón Editar, quita los roles correspondientes y, luego, haz clic en el botón Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

donde

  • PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.
  • ROLE_NAME es el nombre del rol que deseas revocar. Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

Para obtener más detalles, consulta la documentación de IAM y la referencia de la CLI.

Python

No recomendamos escribir tu propio código de Python para otorgar o revocar roles para los agentes implementados. En su lugar, recomendamos usar Google Cloud console o gcloud para operaciones únicas, o bien Terraform para administrar el control de acceso de IAM de forma programática. Si deseas o necesitas hacerlo en Python, consulta la documentación de la biblioteca cliente de IAM.

Secrets

Un secreto contiene una o más versiones de secretos, junto con metadatos como etiquetas e información de replicación. La carga útil real de un secreto se almacena en una versión del secreto. Los secretos se administran (a través de Secret Manager) a nivel del proyecto y se pueden compartir entre los agentes implementados. Para enumerar los secretos correspondientes a un agente en Secret Manager, puedes agregar etiquetas y usarlas para filtrar.

Crea un secreto

Console

  1. Ve a la página de Secret Manager.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en Crear secreto.

  3. En el campo Nombre, ingresa un nombre para el secreto (por ejemplo, my-secret).

  4. Opcional: Para agregar también una versión del secreto cuando creas el secreto inicial, ingresa un valor en el campo Valor del secreto (por ejemplo, abcd1234).

  5. Ve a Etiquetas y, luego, haz clic en Agregar etiqueta.

  6. Ingresa una clave y su valor correspondiente para crear una etiqueta.

  7. Haz clic en Crear secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta los siguientes comandos:

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

donde

  • SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.
  • FILE_PATH es la ruta de acceso completa (incluido el nombre del archivo) al archivo que contiene los detalles de la versión.

Para obtener más información, consulta la documentación de Secret Manager para crear un secreto y una versión del secreto, o bien la referencia de la CLI para crear un secreto y una versión del secreto, respectivamente.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Obtén un secreto

Console

  1. Ve a la página de Secret Manager.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en el nombre de un secreto para describirlo.

  3. En la página Detalles del secreto, se muestra información sobre el secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

donde

  • VERSION_ID es el ID de la versión del secreto.
  • SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto.

Para obtener más información, consulta la documentación de Secret Manager o la referencia de la CLI.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Mostrar lista de secretos

Console

  1. Ve a la página de Secret Manager.

    Ir a Secret Manager

  2. En la tabla Secrets, haz clic en el campo Filter.

  3. Elige una propiedad de filtro y su valor correspondiente, por ejemplo, Location:asia-east1.

  4. La tabla se filtra automáticamente según los valores ingresados.

  5. (Opcional) Para filtrar versiones de secretos, selecciona un secreto para acceder a sus versiones y, luego, usa la opción Filtro en la tabla Versiones.

gcloud

Primero, instala y inicializa la CLI de gcloud.

Para enumerar todos los secretos de un proyecto, ejecuta el siguiente comando:

gcloud secrets list --filter="FILTER"

donde FILTER es una cadena (p.ej., name:asecret OR name:bsecret) o expresiones regulares (p.ej., name ~ "secret_ab.*").

Para enumerar todas las versiones de un secreto, ejecuta el siguiente comando:

gcloud secrets versions list SECRET_ID

Aquí, SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.

Para obtener más detalles, consulta la documentación de Secret Manager para filtrar secretos y listar versiones de secretos, o la referencia de la CLI para listar secretos y versiones de secretos, respectivamente.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Actualiza un secreto

Console

  1. Ve a la página de Secret Manager.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en la casilla de verificación junto al nombre del secreto.

  3. Si el Panel de información está cerrado, haz clic en Mostrar panel de información para mostrarlo.

  4. En el panel de información, haz clic en la pestaña Etiquetas.

  5. Haz clic en Agregar etiqueta y, luego, ingresa una clave y un valor para la etiqueta.

  6. Haz clic en Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

donde

  • SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.
  • KEY es la clave de la etiqueta.
  • VALUE es el valor correspondiente de la etiqueta.

Para obtener más información, consulta la documentación de Secret Manager o la referencia de la CLI.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Borra un secreto

Console

  1. Ve a la página de Secret Manager.

    Ir a Secret Manager

  2. En la página Secret Manager, en la columna Acciones del secreto, haz clic en Ver más.

  3. En el menú, selecciona Borrar.

  4. En el diálogo Borrar secreto, ingresa el nombre del secreto.

  5. Haz clic en el botón Borrar secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud.

Para borrar una versión del secreto, ejecuta el siguiente comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

donde

  • VERSION_ID es el nombre del recurso de la versión del secreto.
  • SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto.

Para borrar un secreto y todas sus versiones, ejecuta el siguiente comando:

gcloud secrets delete SECRET_ID

donde SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto

Para obtener más información, consulta la documentación de Secret Manager sobre cómo borrar un secreto y cómo destruir una versión de un secreto, o la referencia de la CLI para cómo borrar un secreto y cómo destruir una versión de un secreto.

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

Clientes y credenciales de OAuth

Un ID de cliente se usa para identificar un solo agente en los servidores de OAuth de Google. Si tu agente se ejecuta en varias plataformas, cada una necesitará su propio ID de cliente. En términos generales, para integrar un agente basado en OAuth, sigue estos pasos:

  1. Crea un cliente y una credencial de OAuth.

  2. Almacena el ID y el secreto del cliente en Secret Manager. (Consulta Crea un secreto).

  3. Accede al secreto en tu agente durante el desarrollo.

Crea una credencial de cliente de OAuth

  1. En la consola de Google Cloud , ve a la página Google Auth Platform > Clients.

    Ve a Google Auth Platform > Clients

  2. Si es necesario, y si la pantalla muestra el mensaje "Aún no se configuró Google Auth Platform", haz clic en Comenzar y completa la sección Configuraciones del proyecto. (Se pueden actualizar más adelante). Para obtener detalles sobre la preparación para la producción, visita Cumplimiento de la política de OAuth 2.0.

  3. Haz clic en Crear cliente.

  4. Configura Tipo de aplicación como Web application.

  5. Establece el nombre del cliente de OAuth en OAUTH_CLIENT_DISPLAY_NAME.

  6. En URIs de redireccionamiento autorizados, agrega el URI de REDIRECT_URI.

  7. En Client Secrets, haz clic en el botón "Descargar JSON". Se descargará un archivo client_secret.json con el siguiente contenido:

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}
  1. Almacena el ID y el secreto del cliente en Secret Manager, por ejemplo:
from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

Mostrar clientes de OAuth

  1. En la consola de Google Cloud , ve a la página Google Auth Platform > Clients.

    Ve a Google Auth Platform > Clients

  2. Se mostrarán las credenciales de cliente de OAuth que tienes.

Borra un cliente de OAuth

  1. En la consola de Google Cloud , ve a la página Google Auth Platform > Clients.

    Ve a Google Auth Platform > Clients

  2. Selecciona las credenciales de cliente de OAuth que deseas borrar y haz clic en Borrar.

Claves de encriptación administradas por el cliente (CMEK)

De forma predeterminada, Google Cloud encripta los datos automáticamente cuando están en reposo con claves de encriptación administradas por Google. Si tienes requisitos normativos o de cumplimiento específicos relacionados con las claves que protegen los datos, puedes usar claves de encriptación administradas por el cliente (CMEK) para los agentes implementados.

Consulta la documentación sobre la CMEK para Vertex AI para conocer los requisitos generales y obtener orientación sobre el uso de CMEK con Vertex AI, incluidos los siguientes temas:

  • Configuración del proyecto (facturación y APIs habilitadas)
  • Creación de llaveros de claves y claves
  • Permisos requeridos

Para habilitar la CMEK en tu agente, debes especificar encryption_spec con tu clave de Cloud KMS cuando crees una instancia de Agent Engine. Consulta Configura las claves de encriptación administradas por el cliente para ver muestras de código.

Limitaciones

Las siguientes limitaciones se aplican cuando se usa la CMEK con Vertex AI Agent Engine:

  • No se permiten las claves multirregionales: Solo se admiten las claves de una sola región. La región del llavero de claves y la clave debe ser la misma que la de tu instancia de Agent Engine.

  • Las instancias de CMEK implementadas no se pueden actualizar: Una vez que se implementa un agente con una clave de CMEK, la instancia no se puede actualizar ni cambiar para esa implementación. Para usar una especificación de Agent Engine diferente (para una clave nueva o para otras configuraciones), debes implementar una instancia nueva de Agent Engine.

  • Ciertos metadatos y datos operativos no están encriptados: La CMEK encripta los datos principales del agente en reposo. Sin embargo, ciertos metadatos y datos operativos de tiempo de ejecución no se encriptan. Esto incluye lo siguiente:

    • Metadatos del agente:
      • Los nombres visibles
      • Descripciones
    • Datos operativos del entorno de ejecución:
      • Correos electrónicos de la cuenta de servicio
      • Nombres de métodos de clase de objetos del agente
      • Variables de entorno