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

Esistono diversi tipi di metodi di autenticazione disponibili per le 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 loro account di servizio ha l'autorizzazione di accesso.
Invia richieste agli endpoint utilizzando le chiavi API da un agente. Chiavi API Prima di utilizzare questo metodo di autenticazione, verifica che l'API che vuoi utilizzare supporti le chiavi API.
Gestire gli account utente, la registrazione, l'accesso o l'autorizzazione per gli utenti finali dell'agente. ID client OAuth Richiede che il tuo agente richieda e riceva il consenso dell'utente.

Ruoli

Gli agenti di cui esegui il deployment in Agent Engine vengono eseguiti utilizzando l'account di servizio Agente di servizio del motore di ragionamento della piattaforma AI corrispondente a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Il service account ha un ruolo (roles/aiplatform.reasoningEngineServiceAgent) Vertex AI Reasoning Engine Service Agent 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 e seleziona la casella di controllo "Includi concessioni di ruoli fornite da Google".

    Vai a IAM

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

  3. Trova l'entità principale corrispondente a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  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 gcloud. Quindi, esegui il seguente 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 progetto e
  • PRINCIPAL si basa sull'account di servizio generato quando l'agente viene disegnato in Agent Engine.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento all'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-api-python-client

Quindi esegui l'autenticazione e 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 sull'account di servizio generato quando l'agente viene disegnato in Agent Engine.

Concedi i ruoli per un agente di cui è stato eseguito il deployment

  1. Vai alla pagina IAM e seleziona la casella di controllo "Includi concessioni di ruoli fornite da Google".

    Vai a IAM

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

  3. Trova l'entità principale corrispondente a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Aggiungi i ruoli richiesti all'entità facendo clic sul pulsante di modifica, aggiungendo i ruoli, prima di fare clic sul pulsante Salva.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi, esegui il seguente comando:

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

dove

  • PRINCIPAL si basa sull'account di servizio generato durante il deployment dell'agente in 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 all'interfaccia a riga di comando.

Python

Sconsigliamo di scrivere codice Python personalizzato per concedere o revocare i ruoli per gli agenti di cui è stato eseguito il deployment. Ti consigliamo invece di utilizzare la console Google Cloud o gcloud per operazioni una tantum oppure Terraform per gestire il controllo accessi IAM a livello di programmazione. 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 e seleziona la casella di controllo "Includi concessioni di ruoli fornite da Google".

    Vai a IAM

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

  3. Trova l'entità principale corrispondente a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Revoca i ruoli dall'entità principale facendo clic sul pulsante di modifica, rimuovendo i ruoli corrispondenti, prima di fare clic sul pulsante Salva.

gcloud

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

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

dove

  • PRINCIPAL si basa sull'account di servizio generato quando l'agente viene disegnato in 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 all'interfaccia a riga di comando.

Python

Sconsigliamo di scrivere codice Python personalizzato per concedere o revocare i ruoli per gli agenti di cui è stato eseguito il deployment. Ti consigliamo invece di utilizzare la console Google Cloud o gcloud per operazioni una tantum oppure Terraform per gestire il controllo accessi IAM a livello di programmazione. Se vuoi o devi farlo in Python, consulta la documentazione della libreria client IAM.

Secret

Un secret contiene una o più versioni, oltre 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 filtrare.

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 corrispondente per creare un'etichetta.

  7. Fai clic su Crea secret.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi, esegui i seguenti 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, oppure il riferimento all'interfaccia a riga di comando per la creazione di un secret e di una versione del secret.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi esegui l'autenticazione e poi esegui quanto segue

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 gcloud. Quindi, esegui il seguente comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

dove

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

Per maggiori dettagli, consulta la documentazione di Secret Manager o la documentazione di riferimento dell'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Poi autenticati esegui quanto segue

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 Segreti, 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 dei secret: seleziona un secret per accedere alle sue versioni, quindi utilizza l'opzione Filtra nella tabella Versioni.

gcloud

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

Per elencare tutti i secret di un progetto, esegui il seguente 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 segreto, esegui il seguente comando:

gcloud secrets versions list SECRET_ID

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

Per informazioni dettagliate, 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 rispettivamente i secret e le versioni dei secret.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Quindi autenticati esegui quanto segue

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 gcloud. Quindi, esegui il seguente comando:

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

dove

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

Per maggiori dettagli, consulta la documentazione di Secret Manager o la documentazione di riferimento dell'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Poi autenticati esegui quanto segue

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

Per eliminare una versione del secret, esegui il seguente 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 della chiave o l'identificatore completo della chiave.

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

gcloud secrets delete SECRET_ID

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

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

Python

Innanzitutto, installa la libreria client eseguendo

pip install google-cloud-secret-manager

Poi autenticati esegui quanto segue

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, svolgi i seguenti passaggi:

  1. Crea un client OAuth e le relative credenziali.

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

  3. Accedi al segreto nell'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, consulta 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 Secrets, 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 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 di cui disponi.

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.