Autenticazione con token web JSON

La ricerca vettoriale supporta gli endpoint di indice autenticati utilizzando i token JWT (JSON Web Token) autofirmati. Per controllare l'accesso all'endpoint di indice, è configurato in modo da accettare solo i 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 descrive i passaggi necessari per configurare un endpoint di indice con l'autenticazione JWT (JSON Web Token) 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 utilizzando gRPC. Gli esempi 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 di amministrazione per la creazione, il deployment e la gestione degli indici sono protette da utilizzando ruoli IAM predefiniti.

Creare e utilizzare un JWT per eseguire query su un indice

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

Crea 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 Service Account Credentials 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ù su come creare 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 consente di creare JWT utilizzando l'account di servizio da una VM 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 l'account di servizio.

    • Il seguente comando concede l'autorizzazione a creare JWT utilizzando l'account di servizio dal 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 sull'endpoint con la configurazione di 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 di 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. Per le linee guida sul formato, consulta DeployedIndex.id.
    • DEPLOYED_INDEX_NAME: il 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: l' Google Cloud ID progetto.
    • LOCATION: la regione in cui utilizzi Agent Platform.

Esegui query sull'indice con un JWT autofirmato

A livello generale, i passaggi necessari sono i seguenti:

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

Python

Crea e firma il payload JWT

Questo esempio utilizza il metodo sign_jwt della libreria delle credenziali dell'API IAM Python per ottenere un token firmato. Per saperne 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 Vector Search accetta i JWT firmati con un account di servizio preautorizzato, per un pubblico predefinito. Il account di servizio e il pubblico devono essere specificati dal chiamante quando viene eseguito il deployment di un indice su 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 autenticazione nell'intestazione authorization della richiesta gRPC. Oltre a essere firmato dal account di servizio, il JWT deve includere le seguenti attestazioni:

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

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

  • Le attestazioni aud (pubblico) e sub (oggetto) devono essere 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.

  • L'attestazione iat (emessa alle) deve essere impostata sull'ora in cui viene emesso il token. L'attestazione exp (ora di scadenza) deve essere impostata su un breve periodo di tempo (circa un'ora). Questi valori sono espressi in tempo 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 nell'attestazione iss.

Crea il JWT

  1. Assicurati che tu (il chiamante) possa utilizzare il ruolo roles/iam.serviceAccountTokenCreator sull'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: l' Google Cloud ID progetto.
    • 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 jqstrumento, crea il curl payload della richiesta codificando il JWT in una stringa:

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

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

    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: l' Google Cloud ID progetto.

    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 di 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: l' Google Cloud ID progetto.

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 di indice

Python

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

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 gRPC di 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 è 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. Per le linee guida sul formato, consulta DeployedIndex.id.

signedJwt è la variabile di ambiente contenente il JWT firmato.

Risoluzione dei problemi

La tabella seguente elenca alcuni messaggi di errore gRPC comuni.

Messaggio di errore gRPC Motivo
Authorization header not found for index 'INDEX_ID' I metadati gRPC non contengono un'intestazione di autorizzazione
JWT is invalid format Il token non è in un formato corretto e non può essere analizzato correttamente
JWT authentication failed Il token è scaduto o non è firmato dall'account di servizio corretto
JWT issuer should be in the allowed issuers list L'attestazione iss del token non è presente negli emittenti consentiti di auth_config
Permission check fail for index 'INDEX_ID' L'attestazione aud o sub del token non è presente nei pubblici di auth_config

Passaggi successivi