Administra el acceso de los agentes implementados

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

Caso de uso Método de autenticación Informació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.
Envía 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.
Controla 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 Agent Engine se ejecutan con la cuenta de servicio del agente de servicio de AI Platform Reasoning Engine que coincide con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

Cómo mostrar los roles de un agente implementado

Console

  1. Ve a la página IAM y marca la casilla de verificación “Incluir asignaciones de roles proporcionados por Google”.

    Ir a IAM

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

  3. Busca el principal que coincida con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Los roles del agente implementado se pueden encontrar 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 generó cuando se implementó el agente en Agent Engine.

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

Python

Primero, instala la biblioteca cliente ejecutando

pip install google-api-python-client

Luego, autentícate y ejecuta el siguiente comando para obtener una lista de 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)

En la que PRINCIPAL se basa en la cuenta de servicio que se generó cuando se implementó el agente en Agent Engine.

Otorga roles a un agente implementado

  1. Ve a la página IAM y marca la casilla de verificación “Incluir asignaciones de roles proporcionados por Google”.

    Ir a IAM

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

  3. Busca el principal que coincida con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  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 generó cuando se implementó el agente en 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 información, 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 a los agentes implementados. En su lugar, te recomendamos que uses la consola de Google Cloud o gcloud para operaciones únicas, o Terraform para administrar el control de acceso de IAM de forma programática. Si quieres o necesitas hacerlo en Python, consulta la documentación de la biblioteca cliente de IAM.

Cómo revocar roles de un agente implementado

  1. Ve a la página IAM y marca la casilla de verificación “Incluir asignaciones de roles proporcionados por Google”.

    Ir a IAM

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

  3. Busca el principal que coincida con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  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 generó cuando se implementó el agente en 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 información, 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 a los agentes implementados. En su lugar, te recomendamos que uses la consola de Google Cloud o gcloud para operaciones únicas, o Terraform para administrar el control de acceso de IAM de forma programática. Si quieres 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 de 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 para el secreto (por ejemplo, abcd1234) en el campo Valor del secreto.

  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 de secreto, o la referencia de la CLI para crear un secreto y una versión de secreto, respectivamente.

Python

Primero, instala la biblioteca cliente ejecutando

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

Cómo obtener 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 Secret, 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 del 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

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 Secretos, haz clic en el campo Filtro.

  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 Filtrar 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"

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

Para obtener una lista de todas las versiones de un secreto, ejecuta el siguiente comando:

gcloud secrets versions list SECRET_ID

En el ejemplo anterior, SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.

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

Python

Primero, instala la biblioteca cliente ejecutando

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

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

Cómo borrar 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 cuadro de 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 secreta, 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 Secret.
  • SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.

Para borrar un Secret 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 del secreto

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

Python

Primero, instala la biblioteca cliente ejecutando

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 para los servidores de OAuth de Google. Si tu agente se ejecuta en varias plataformas, cada una necesitará su propio ID de cliente. En un nivel alto, para integrar un agente basado en OAuth, sigue estos pasos:

  1. Crea un cliente y una credencial de OAuth.

  2. Almacena el ID de cliente y el secreto en Secret Manager. (consulta Cómo crear 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 > Clientes.

    Ve a Google Auth Platform > Clientes.

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

  3. Haz clic en Crear cliente.

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

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

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

  7. En Secretos del cliente, haz clic en el botón para "descargar JSON". Se descargará un archivo client_secret.json que tendrá 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 de cliente y el secreto 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 > Clientes.

    Ve a Google Auth Platform > Clientes.

  2. Se mostrará una lista de 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 > Clientes.

    Ve a Google Auth Platform > Clientes.

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