Autenticazione con token web JSON

Vector Search supporta gli endpoint indice autenticati utilizzando JWT (JSON Web Token) autofirmati. Per controllare l'accesso all'endpoint dell'indice, è configurato per accettare solo JWT firmati emessi da account di servizio Google specificamente autorizzati. Ciò significa che solo i clienti che utilizzano questi account designati possono interagire con l'endpoint.

Questa pagina descrive i passaggi necessari per configurare un endpoint indice con JSON Autenticazione JWT (Web Token) ed esecuzione di query su questo token.

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) richiamati tramite gRPC. Gli esempi RPC in questa pagina utilizzano lo strumento open source grpc_cli per inviare richieste gRPC al server di indicizzazione di cui è stato eseguito il deployment.
  • Le API amministrative per la creazione, il deployment e la gestione degli indici sono protette da utilizzando i ruoli IAM predefiniti.

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

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

Creare un indice

Crea un indice di ricerca vettoriale seguendo le istruzioni riportate in Creare un indice.

Crea un endpoint privato

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

Crea un account di servizio

Crea un account di servizio e concedigli 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 l'account di servizio.
    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.

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

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

    • Il seguente comando ti concede l'autorizzazione per creare JWT utilizzando l'account di servizio da una VM Compute Engine a cui è associato 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 l'account di servizio.

    • Il comando seguente concede l'autorizzazione per creare JWT utilizzando il metodo account di servizio dal tuo Account Google (sulla 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 l'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 dell'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 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 utilizzi Vertex AI.

Esegui una query sull'indice con un JWT autofirmato

A livello generale, i passaggi richiesti sono i seguenti:

  1. Crea 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'header di autorizzazione.

Crea il payload JWT

L'autenticazione Vector Search accetta i JWT firmati con un account di servizio pre-autorizzato per un segmento di pubblico predefinito. Account di servizio e il segmento di pubblico deve essere specificato dal chiamante quando viene eseguito il deployment di un indice endpoint privato. Una volta eseguito il deployment di un indice con queste impostazioni, Le richieste API gRPC a quell'endpoint devono includere un'etichetta intestazione di autorizzazione contenente un JWT firmato dall'emittente (un account di servizio) e indirizzato ai pubblico fornito. Il JWT firmato viene passato come token bearer nell'authorization intestazione della richiesta gRPC. Oltre ad essere firmato da l'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"

  • I claim aud (segmento di pubblico) e sub (soggetto) devono essere impostati entrambi sullo stesso valore. Si tratta di una stringa descrittiva che identifica il numero pubblico specifico 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 rivendicazione exp (tempo di scadenza) deve essere impostata su un periodo di tempo breve (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 questi claim 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 nel claim iss. È codificato in base64 per la trasmissione come token di accesso 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"

Crea il JWT

  1. Assicurati di poter 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 valore previsto pubblico specifico per il tuo servizio, carico di lavoro o app, ad esempio "123456-my-app".

Firma il JWT (API REST)

  1. Utilizzando lo strumento jq, crea il payload della 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.

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

Firma il JWT (interfaccia a riga di comando gcloud)

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

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. Memorizzalo 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 MatchService Endpoint 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, devi impostare le seguenti variabili di ambiente:

  • TARGET_IP è l'indirizzo IP del server di indicizzazione di cui è stato eseguito il deployment. Per scoprire come recuperare questo valore, consulta Eseguire query sugli indici per ottenere i vicini più prossimi.
  • 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 sul 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 è nel formato corretto e non può essere analizzato correttamente
Autenticazione JWT non riuscita Il token è scaduto o non è firmato dal service account 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