Autenticazione con token web JSON

Vector Search supporta gli endpoint indice autenticati tramite token web JSON autofirmati (JWT). Per controllare l'accesso all'endpoint indice, è configurato in modo da accettare solo JWT firmati emessi da account di servizio Google appositamente autorizzati. Ciò significa che solo i clienti che utilizzano questi account designati possono interagire con l'endpoint.

Questa pagina illustra i passaggi necessari per configurare un endpoint indice con autenticazione JSON Web Token (JWT) ed eseguire query su di esso.

Limitazioni

  • L'autenticazione JWT è supportata solo per gli endpoint privati con peering VPC o Private Service Connect (PSC).
  • L'autenticazione JWT è supportata solo per le API RPC del piano dati (ad esempio MatchService) richiamate tramite gRPC. Gli esempi di RPC in questa pagina utilizzano lo strumento open source grpc_cli per inviare richieste gRPC al server di indice di cui è stato eseguito il deployment.
  • Le API amministrative per la creazione, il deployment e la gestione degli indici sono protette da ruoli IAM predefiniti.

Creazione e utilizzo di un JWT per eseguire query su un indice

Segui questi passaggi per creare un endpoint indice ed eseguirvi query con un JWT autofirmato.

Crea un indice

Crea un indice di Vector Search seguendo le istruzioni in Creare un indice.

Crea un endpoint privato

Crea un endpoint privato seguendo le istruzioni in una delle seguenti pagine della documentazione:

Crea un service account

Crea un account di servizio e assegnagli il ruolo IAM Creatore token account di servizio.

  1. Abilita l'API IAM Service Account Credentials e crea un account di servizio:

    gcloud services enable iamcredentials.googleapis.com --project="PROJECT_ID"
gcloud iam service-accounts create SERVICE_ACCOUNT_ID --project="PROJECT_ID"

    Sostituisci i seguenti valori:

    • PROJECT_ID: il progetto in cui creare il tuo account di servizio.
    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.

    Scopri di più sulla creazione di un account di servizio.

  2. Utilizza uno dei seguenti comandi per concedere il ruolo IAM iam.serviceAccountTokenCreator al tuo account di servizio:

    • Il comando seguente ti concede l'autorizzazione per creare JWT utilizzando l'account di servizio di una VM di Compute Engine a cui è collegato l'account di servizio:

      gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project "PROJECT_ID"

      Sostituisci i seguenti valori:

      • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
      • PROJECT_ID: il progetto in cui creare il tuo account di servizio.

    • Il seguente comando concede l'autorizzazione per creare JWT utilizzando l'account di servizio del tuo Account Google (sulla tua workstation):

      gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "user:EMAIL_ADDRESS" \
   --project PROJECT_ID

      Sostituisci i seguenti valori:

      • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
      • PROJECT_ID: il progetto in cui creare il tuo account di servizio.
      • EMAIL_ADDRESS: il tuo indirizzo email.

Esegui il deployment dell'indice nell'endpoint con la configurazione dell'autenticazione JWT

  1. Esegui il deployment dell'indice sull'endpoint privato come mostrato nell'esempio seguente:

    gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
   --index=INDEX_ID \
   --deployed-index-id=DEPLOYED_INDEX_ID \
   --display-name=DEPLOYED_INDEX_NAME \
   --audiences=AUDIENCES \
   --allowed-issuers="SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID \
   --region=LOCATION

    Sostituisci i seguenti valori:

    • INDEX_ENDPOINT_ID: l'ID dell'endpoint indice.
    • INDEX_ID: l'ID dell'indice.
    • DEPLOYED_INDEX_ID: una stringa specificata dall'utente per identificare in modo univoco l'indice di cui è stato eseguito il deployment. Deve iniziare con una lettera e contenere solo lettere, numeri o trattini bassi. Consulta DeployedIndex.id per le linee guida per il formato.
    • DEPLOYED_INDEX_NAME: nome visualizzato dell'indice di cui è stato eseguito il deployment.
    • AUDIENCES: una stringa descrittiva che identifica il segmento di pubblico previsto per il servizio, il carico di lavoro o l'app, ad esempio "123456-my-app".
    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
    • PROJECT_ID: il tuo ID progetto Google Cloud.
    • LOCATION: la regione in cui stai utilizzando Vertex AI.

Query sull'indice con un JWT autofirmato

A livello generale, i passaggi richiesti sono i seguenti:

  1. Creare un payload JWT.
  2. Firma il token utilizzando l'account di servizio creato in precedenza.
  3. Esegui una query sull'indice utilizzando una chiamata gRPC, passando il token nell'intestazione di autorizzazione.

Crea il payload JWT

L'autenticazione di Vector Search accetta i JWT firmati con un account di servizio pre-autorizzato, per un pubblico predefinito. L'account di servizio e il pubblico devono essere specificati dal chiamante quando viene eseguito il deployment di un indice in un endpoint privato. Una volta eseguito il deployment di un indice con queste impostazioni, tutte le richieste API gRPC a quell'endpoint devono includere un'intestazione di autorizzazione contenente un JWT firmato dall'emittente (un account di servizio) e destinato al pubblico fornito. Il JWT firmato viene passato come token di connessione nell'intestazione authorization della richiesta gRPC. Oltre a essere firmato dall'account di servizio, il JWT deve includere le seguenti attestazioni:

  • La rivendicazione iss (emittente consentito) deve essere l'indirizzo email dell'account di servizio, ad esempio:

    "iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"

  • Le rivendicazioni aud (pubblico) e sub (oggetto) devono essere entrambe impostate sullo stesso valore. Si tratta di una stringa descrittiva che identifica il pubblico previsto per il servizio, il carico di lavoro o l'app, ad esempio:

    "aud": "123456-my-app",
"sub": "123456-my-app"

    Questo valore deve corrispondere all'argomento --audiences passato al momento del deployment dell'indice.

  • Il reclamo iat (emesso alle) deve essere impostato sul momento dell'emissione del token. La richiesta di exp (tempo di scadenza) deve essere impostata su un breve periodo di tempo successivo (circa un'ora). Questi valori sono espressi nel tempo dell'epoca Unix, ad esempio:

    "iat": 1698966927, // unix time since epoch eg via date +%s
"exp": 1698967527 // iat + a few mins (eg 600 seconds)

L'esempio seguente mostra queste dichiarazioni in un singolo payload JWT:

{
   "iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
   "aud": "123456-my-app",
   "sub": "123456-my-app",
   "iat": 1698956084,
   "exp": 1698960084
}

Il payload JWT viene firmato utilizzando l'account di servizio specificato nella richiesta iss. È codificato in base64 per la trasmissione come token di connessione utilizzando i metadati gRPC, come mostrato nell'esempio seguente, dove signedJwt è una variabile di ambiente contenente un JWT firmato:

./grpc_cli call ... --metadata "authorization: Bearer $signedJwt"

Creare il JWT

  1. Assicurati che tu (il chiamante) possa utilizzare il ruolo roles/iam.serviceAccountTokenCreator nell'account di servizio.

  2. Crea un file JSON denominato jwt_in.json che contiene il JWT non elaborato:

    SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
cat << EOF > jwt_in.json
{
  "aud": "AUDIENCES",
  "sub": "AUDIENCES",
  "iss": "${SA}",
  "iat": $(date +%s),
  "exp": $(expr $(date +%s) + 600)
}
EOF

    Sostituisci i seguenti valori:

    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
    • PROJECT_ID: il tuo ID progetto Google Cloud.
    • AUDIENCES: una stringa descrittiva che identifica il segmento di pubblico previsto per il servizio, il carico di lavoro o l'app, ad esempio "123456-my-app".

Firma JWT (API REST)

  1. Con lo strumento jq, crea il payload di richiesta curl codificando il JWT in una stringa:

    cat jwt_in.json | jq -Rsa >request.json

  2. Firma il token passando il payload della richiesta al metodo API REST signJwt.

    SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SA:signJwt"

    Sostituisci i seguenti valori:

    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
    • PROJECT_ID: il tuo ID progetto Google Cloud.

    Archivia il valore signedJwt restituito in una variabile di ambiente denominata signedJwt.

Firma JWT (gcloud CLI)

In alternativa, puoi firmare il JWT passando il file jwt_in.json direttamente al metodo sign-jwt gcloud CLI.

gcloud iam service-accounts sign-jwt jwt_in.json jwt_out \
   --iam-account=SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com

Sostituisci i seguenti valori:

  • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
  • PROJECT_ID: il tuo ID progetto Google Cloud.

Il JWT firmato viene restituito nel file di output jwt_out. Archivialo in una variabile di ambiente denominata signedJwt.

Invia il JWT firmato all'endpoint indice

Da una VM di Compute Engine nella stessa rete VPC, chiama l'endpoint MatchService gRPC, passando il token signedJwt nell'intestazione authorization, come mostrato nell'esempio seguente:

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match \
   '{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}' \
   --metadata "authorization: Bearer $signedJwt"

Per eseguire questo comando, è necessario impostare le seguenti variabili di ambiente:

  • TARGET_IP è l'indirizzo IP del server di indice di cui è stato eseguito il deployment. Per informazioni su come recuperare questo valore, consulta Eseguire query sugli indici per ottenere i vicini più vicini.
  • DEPLOYED_INDEX_ID: una stringa specificata dall'utente per identificare in modo univoco l'indice di cui è stato eseguito il deployment. Deve iniziare con una lettera e contenere solo lettere, numeri o trattini bassi. Consulta DeployedIndex.id per le linee guida per il formato.

signedJwt è la variabile di ambiente contenente il JWT firmato.

Risoluzione dei problemi

Nella tabella seguente sono elencati alcuni messaggi di errore comuni di gRPC.

Messaggio di errore gRPC Motivo
Intestazione di autorizzazione non trovata per l'indice "INDEX_ID" I metadati gRPC non contengono un'intestazione di autorizzazione
Il formato JWT non è valido Il token non è valido e non può essere analizzato correttamente
Autenticazione JWT non riuscita Il token è scaduto o non è firmato dall'account di servizio corretto
L'emittente JWT deve essere nell'elenco degli emittenti consentiti Il token iss non fa parte di auth_config emittenti consentiti
Controllo delle autorizzazioni per l'indice "INDEX_ID" non riuscito La rivendicazione del token aud o sub non fa parte di auth_config segmenti di pubblico

Passaggi successivi