Autenticazione con token web JSON

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

Questa pagina descrive i passaggi necessari per configurare un endpoint indice con autenticazione JSON Web Token (JWT) e per 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, che vengono richiamate utilizzando 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 tramite 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.

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 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ù 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 consente di creare JWT utilizzando l'account di servizio di una VM di 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 l'account di servizio del 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 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 sul 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

In linea 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 preautorizzato 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. Dopo 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 indirizzato al pubblico fornito. Il JWT firmato viene passato come token di connessione nell'intestazione authorization della richiesta gRPC. Oltre ad essere firmato dall'account di servizio, il JWT deve includere le seguenti attestazioni:

  • La rivendicazione iss (emittente consentita) 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 impostate sullo stesso valore. Questa è 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.

  • La rivendicazione iat (emessa alle ore) deve essere impostata sul momento in cui viene emesso il token. La rivendicazione exp (scadenza) deve essere impostata a breve (circa un'ora). Questi valori sono espressi nel fuso orario Unix epoch, 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 attestazioni 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"

Crea il JWT

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

  2. Crea un file JSON denominato jwt_in.json che contenga il file 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 pubblico previsto per il servizio, il carico di lavoro o l'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 dell'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 \
   "http://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 dell'interfaccia a riga di comando 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 chiamata signedJwt.

Invia il JWT firmato all'endpoint indice

Da una VM Compute Engine nella stessa rete VPC, chiama l'endpoint gRPC MatchService, 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 indice di cui hai 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 relativi a 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 autorizzati Il token iss non è in auth_config emittente consentito
Controllo delle autorizzazioni non riuscito per l'indice "INDEX_ID" L'attestazione del token aud o sub non è presente in auth_config segmenti di pubblico

Passaggi successivi