Autenticazione con token web JSON

Ricerca vettoriale supporta gli endpoint dell'indice autenticati che utilizzano token web JSON (JWT) 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 client che utilizzano questi account designati possono interagire con l'endpoint.

Questa pagina illustra i passaggi necessari per configurare un endpoint dell'indice con autenticazione JWT (token web JSON) 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 (come MatchService) 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 di amministrazione per la creazione, il deployment e la gestione degli indici sono protette tramite l'utilizzo di 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.

Creare 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. Attiva l'API Service Account Credentials di IAM 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 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 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 l'account di servizio.
      • EMAIL_ADDRESS: il tuo indirizzo email.

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

  1. Esegui il deployment dell'indice nell'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 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

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.

Python

Crea e firma il payload JWT

Questo esempio utilizza il metodo sign_jwt della libreria delle credenziali dell'API IAM per Python per ottenere un token firmato. Per scoprire di più su come installare e utilizzare questa libreria, consulta la documentazione delle librerie client dell'API IAM.

   from google.cloud import iam_credentials_v1
   from datetime import datetime, timezone
   import json

   def sign_jwt(issuer: str, audience: str):
      client = iam_credentials_v1.IAMCredentialsClient()
      payload = {
            'aud': audience,
            'sub': audience,
            'iss': issuer,
            'iat': int(datetime.now(timezone.utc).timestamp()),
            'exp': int(datetime.now(timezone.utc).timestamp()) + 600,
      }
      response = client.sign_jwt(name="projects/-/serviceAccounts/" + issuer,
                                 payload=json.dumps(payload))
      return response.signed_jwt

   sign_jwt("SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
            "AUDIENCES")

Riga di comando

Crea il payload JWT

L'autenticazione di Ricerca vettoriale accetta JWT firmati con un account di servizio preautorizzato per un segmento di pubblico predefinito. L'account di servizio e il segmento di pubblico devono essere specificati dall'utente chiamante quando un indice viene disegnato in un endpoint privato. Una volta disegnato un indice con queste impostazioni, tutte le richieste dell'API gRPC a quell'endpoint devono includere un'intestazione di autorizzazione contenente un JWT firmato dall'emittente (un account di servizio) e indirizzato al segmento di pubblico fornito. Il JWT firmato viene passato come token bearer nell'authorization intestazione della richiesta gRPC. Oltre ad essere firmato dall'account di servizio, il JWT deve includere i seguenti claim:

  • L'attributo 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 (pubblico) e sub (soggetto) devono essere impostati entrambi sullo stesso valore. Si tratta di una stringa descrittiva che identifica il pubblico previsto per il tuo servizio, carico di lavoro o 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.

  • L'attributo iat (issued at) deve essere impostato sul momento in cui viene emesso il token. L'attributo exp (ora di scadenza) deve essere impostato su un'ora successiva (circa un'ora). Questi valori sono espressi in ora dell'epoca di 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.

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 contenente 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 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 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 (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. Memorizzalo in una variabile di ambiente denominata signedJwt.

Invia il JWT firmato all'endpoint indice

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

def vector_search_match_jwt(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    signed_jwt: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.
        signed_jwt (str): Required. The signed JWT token for the private
        endpoint. The endpoint must be configured to accept tokens from JWT's
        issuer and encoded audience.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        signed_jwt=signed_jwt,
    )
    return resp

Riga di comando

Da una VM 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, 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

La seguente tabella elenca alcuni messaggi di errore gRPC comuni.

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 account di servizio corretto
L'emittente JWT deve essere presente nell'elenco degli emittenti consentiti Il token iss non è tra gli emittenti consentiti auth_config
Controllo delle autorizzazioni non riuscito per l'indice "INDEX_ID" L'affermazione del token aud o sub non è presente nei segmenti di pubblico auth_config

Passaggi successivi