Gestione dell'accesso per gli agenti di cui è stato eseguito il deployment

Esistono diversi tipi di metodi di autenticazione disponibili per diverse modalità di accesso:

Caso d'uso Metodo di autenticazione Informazioni su questo metodo di autenticazione
Accedi alle origini dati direttamente da un agente. Service account Gli agenti di cui è stato eseguito il deployment hanno accesso a tutte le risorse a cui il service account ha l'autorizzazione di accedere.
Invia richieste agli endpoint utilizzando le chiavi API dall'interno di un agente. Chiavi API Prima di utilizzare questo metodo di autenticazione, verifica che l'API che vuoi utilizzare supporti le chiavi API.
Gestire account utente, registrazione, accesso o autorizzazione per gli utenti finali dell'agente. ID client OAuth Richiede all'agente di richiedere e ricevere il consenso dell'utente.

Ruoli

Gli agenti di cui esegui il deployment su Vertex AI Agent Engine vengono eseguiti utilizzando l'agente di servizio AI Platform Reasoning Engine o il tuo account di servizio personalizzato. Per ulteriori informazioni, consulta Configurare l'identità e le autorizzazioni per l'agente.

Agente di servizio AI Platform Reasoning Engine

Il account di servizio AI Platform Reasoning Engine Service Agent utilizza il formato service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Il account di servizio ha un ruolo agente di servizio Vertex AI Reasoning Engine (roles/aiplatform.reasoningEngineServiceAgent) che concede le autorizzazioni predefinite richieste per gli agenti di cui è stato eseguito il deployment. Puoi visualizzare l'elenco completo delle autorizzazioni predefinite nella documentazione IAM.

Elenca i ruoli di un agente di cui è stato eseguito il deployment

Console

  1. Vai alla pagina IAM.

    Vai a IAM

  2. Seleziona il progetto corrispondente al tuo progetto Google Cloud .

  3. Trova l'entità che corrisponde all'account di servizio utilizzato come identità dell'agente.

  4. I ruoli dell'agente di cui è stato eseguito il deployment sono disponibili nella colonna Ruolo.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questo comando:

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

dove

  • PROJECT_ID_OR_NUMBER è l'ID o il numero del tuo progetto e
  • PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Vertex AI Agent Engine.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento della CLI.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-api-python-client

poi autenticati ed esegui il seguente comando per elencare i ruoli di un agente di cui è stato eseguito il deployment:

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)

dove PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Vertex AI Agent Engine.

Concedere ruoli per un agente di cui è stato eseguito il deployment

  1. Vai alla pagina IAM.

    Vai a IAM

  2. Seleziona il progetto corrispondente al tuo progetto Google Cloud .

  3. Trova l'entità che corrisponde all'account di servizio utilizzato come identità dell'agente.

  4. Aggiungi i ruoli richiesti all'entità facendo clic sul pulsante di modifica, aggiungendo i ruoli e poi facendo clic sul pulsante di salvataggio.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questo comando:

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

dove

  • PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Vertex AI Agent Engine.
  • ROLE_NAME è il nome del ruolo che vuoi concedere. Per un elenco dei ruoli predefiniti, consulta Informazioni sui ruoli.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento della CLI.

Python

Non è consigliabile scrivere codice Python personalizzato per concedere o revocare ruoli per gli agenti di cui è stato eseguito il deployment. Ti consigliamo invece di utilizzare la Google Cloud console o gcloud per operazioni una tantum oppure Terraform per gestire l'controllo dell'accesso IAM in modo programmatico. Se vuoi o devi farlo in Python, consulta la documentazione della libreria client IAM.

Revocare i ruoli da un agente di cui è stato eseguito il deployment

  1. Vai alla pagina IAM.

    Vai a IAM

  2. Seleziona il progetto corrispondente al tuo progetto Google Cloud .

  3. Trova l'entità che corrisponde all'account di servizio utilizzato come identità dell'agente.

  4. Revoca i ruoli dall'entità facendo clic sul pulsante di modifica, rimuovendo i ruoli corrispondenti e poi facendo clic sul pulsante Salva.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questo comando:

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

dove

  • PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Vertex AI Agent Engine.
  • ROLE_NAME è il nome del ruolo che vuoi revocare. Per un elenco dei ruoli predefiniti, consulta Informazioni sui ruoli.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento della CLI.

Python

Non è consigliabile scrivere codice Python personalizzato per concedere o revocare ruoli per gli agenti di cui è stato eseguito il deployment. Ti consigliamo invece di utilizzare la Google Cloud console o gcloud per operazioni una tantum oppure Terraform per gestire l'controllo dell'accesso IAM in modo programmatico. Se vuoi o devi farlo in Python, consulta la documentazione della libreria client IAM.

Secret

Un secret contiene una o più versioni del secret, insieme a metadati come etichette e informazioni sulla replica. Il payload effettivo di un secret è archiviato in una versione del secret. I secret vengono gestiti (tramite Secret Manager) a livello di progetto e possono essere condivisi tra gli agenti di cui è stato eseguito il deployment. Per elencare i secret corrispondenti a un agente in Secret Manager, puoi aggiungere etichette e utilizzarle per il filtraggio.

Crea un secret

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic su Crea secret.

  3. Nel campo Nome, inserisci un nome per il secret (ad esempio, my-secret).

  4. (Facoltativo) Per aggiungere anche una versione del secret durante la creazione del secret iniziale, inserisci un valore per il secret nel campo Valore secret, ad esempio abcd1234.

  5. Vai a Etichette e fai clic su Aggiungi etichetta.

  6. Inserisci una chiave e il relativo valore per creare un'etichetta.

  7. Fai clic su Crea secret.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questi comandi:

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

dove

  • SECRET_ID è l'ID del secret o l'identificatore completo del secret.
  • FILE_PATH è il percorso completo (incluso il nome del file) del file contenente i dettagli della versione.

Per informazioni dettagliate, consulta la documentazione di Secret Manager per la creazione di un secret e di una versione del secret o il riferimento della CLI per la creazione di un secret e di una versione del secret rispettivamente.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente

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

Recuperare un secret

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic sul nome di un secret da descrivere.

  3. La pagina Dettagli secret elenca le informazioni sul secret.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questo comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

dove

  • VERSION_ID è l'ID della versione del secret e
  • SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per maggiori dettagli, consulta la documentazione di Secret Manager o il riferimento della CLI.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente

from google.cloud import secretmanager

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

Elenco secret

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella tabella Secrets, fai clic sul campo Filtro.

  3. Scegli una proprietà filtro e il relativo valore, ad esempio Location:asia-east1.

  4. La tabella viene filtrata automaticamente in base ai valori inseriti.

  5. (Facoltativo) Per filtrare le versioni del secret: seleziona un secret per accedere alle relative versioni, quindi utilizza l'opzione Filtra nella tabella Versioni.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud.

Per elencare tutti i secret di un progetto, esegui questo comando:

gcloud secrets list --filter="FILTER"

dove FILTER è una stringa (ad es. name:asecret OR name:bsecret) o espressioni regolari (ad es. name ~ "secret_ab.*").

Per elencare tutte le versioni di un secret, esegui questo comando:

gcloud secrets versions list SECRET_ID

dove SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per maggiori dettagli, consulta la documentazione di Secret Manager per filtrare i secret e elencare le versioni dei secret oppure la documentazione di riferimento della CLI per elencare i secret e le versioni dei secret rispettivamente.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente

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

Aggiornare un secret

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic sulla casella di controllo accanto al nome del secret.

  3. Se il riquadro Informazioni è chiuso, fai clic su Mostra riquadro Informazioni per visualizzarlo.

  4. Nel riquadro Informazioni, seleziona la scheda Etichette.

  5. Fai clic su Aggiungi etichetta e inserisci una chiave e un valore per l'etichetta.

  6. Fai clic su Salva.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud. Quindi esegui questo comando:

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

dove

  • SECRET_ID è l'ID del secret o l'identificatore completo del secret.
  • KEY è la chiave dell'etichetta e
  • VALUE è il valore corrispondente dell'etichetta.

Per maggiori dettagli, consulta la documentazione di Secret Manager o il riferimento CLI.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente

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

Eliminare un secret

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic su Mostra altro nella colonna Azioni del secret.

  3. Nel menu, seleziona Elimina.

  4. Nella finestra di dialogo Elimina secret, inserisci il nome del secret.

  5. Fai clic sul pulsante Elimina secret.

gcloud

Per prima cosa, installa e inizializza l'interfaccia a riga di comando di gcloud.

Per eliminare una versione del secret, esegui questo comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

dove

  • VERSION_ID è il nome della risorsa della versione del secret e
  • SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per eliminare un secret e tutte le relative versioni, esegui questo comando:

gcloud secrets delete SECRET_ID

dove SECRET_ID è l'ID del secret o l'identificatore completo del secret

Per maggiori dettagli, consulta la documentazione di Secret Manager per eliminare un secret e eliminare una versione del secret oppure la documentazione di riferimento della CLI per eliminare un secret e eliminare una versione del secret.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente

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

Client e credenziali OAuth

L'ID client viene utilizzato per identificare un singolo agente nei server OAuth di Google. Se il tuo agente viene eseguito su più piattaforme, ognuna dovrà avere il proprio ID client. A livello generale, per integrare un agente basato su OAuth, devi:

  1. Crea un client e una credenziale OAuth.

  2. Archivia l'ID client e il secret in Secret Manager. (vedi Creare un secret).

  3. Accedi al segreto nel tuo agente durante lo sviluppo.

Creare una credenziale client OAuth

  1. Nella console Google Cloud , vai alla pagina Google Auth Platform > Client.

    Vai a Google Auth Platform > Client

  2. (Se necessario) Se nella schermata viene visualizzato il messaggio "Google Auth Platform non ancora configurata", fai clic su Inizia e compila le Configurazioni del progetto. Possono essere aggiornati in un secondo momento. Per informazioni dettagliate sulla preparazione alla produzione, visita la pagina Conformità alle norme OAuth 2.0.

  3. Fai clic su Crea cliente.

  4. Imposta Tipo di applicazione su Web application.

  5. Imposta il nome del client OAuth su OAUTH_CLIENT_DISPLAY_NAME.

  6. In URI di reindirizzamento autorizzati, aggiungi l'URI per REDIRECT_URI.

  7. In Client secret, fai clic sul pulsante "Scarica JSON". Verrà scaricato un file client_secret.json con i seguenti contenuti:

{'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. Archivia l'ID client e il client secret in Secret Manager, ad esempio:
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),
    },
})

Elenca client OAuth

  1. Nella console Google Cloud , vai alla pagina Google Auth Platform > Client.

    Vai a Google Auth Platform > Client

  2. Verranno elencate le credenziali client OAuth che hai.

Eliminare un client OAuth

  1. Nella console Google Cloud , vai alla pagina Google Auth Platform > Client.

    Vai a Google Auth Platform > Client

  2. Seleziona le credenziali client OAuth da eliminare e fai clic su Elimina.

Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Google Cloud cripta automaticamente i dati quando sono inattivi utilizzando chiavi di crittografia gestite da Google. Se hai requisiti di conformità o normativi specifici relativi alle chiavi che proteggono i tuoi dati, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per gli agenti di cui è stato eseguito il deployment.

Consulta la documentazione relativa a CMEK per Vertex AI per i requisiti generali e le indicazioni sull'utilizzo di CMEK con Vertex AI, tra cui:

  • Configurazione del progetto (fatturazione e API abilitate)
  • Creazione di chiavi automatizzate e chiavi
  • Concessioni delle autorizzazioni obbligatorie

Per attivare CMEK per l'agente, devi specificare encryption_spec con la chiave Cloud KMS durante la creazione di un'istanza di Agent Engine. Per esempi di codice, consulta Configurare le chiavi di crittografia gestite dal cliente.

Limitazioni

Quando utilizzi CMEK con Vertex AI Agent Engine, si applicano le seguenti limitazioni:

  • Non sono consentite chiavi multiregionali: sono supportate solo chiavi a regione singola. La regione del portachiavi e della chiave deve corrispondere a quella dell'istanza di Agent Engine.

  • Le istanze CMEK di cui è stato eseguito il deployment non possono essere aggiornate: una volta eseguito il deployment di un agente con una chiave CMEK, l'istanza non può essere aggiornata o modificata per quel deployment. Per utilizzare una specifica di Agent Engine diversa (per una nuova chiave o per altre configurazioni), devi eseguire il deployment di una nuova istanza di Agent Engine.

  • Alcuni metadati e dati operativi non criptati:CMEK cripta i dati principali dell'agente a riposo. Tuttavia, alcuni metadati e dati operativi di runtime non sono criptati. È incluso quanto segue:

    • Metadati dell'agente:
      • Nomi visualizzati
      • Descrizioni
    • Dati operativi del runtime:
      • Email dei service account
      • Nomi dei metodi della classe dell'oggetto agente
      • Variabili di ambiente