Authentifizierung mit JSON Web Token

Vector Search unterstützt authentifizierte Indexendpunkte mit selbstsignierten JSON Web Tokens (JWTs). Um den Zugriff auf den Indexendpunkt zu steuern, werden nur signierte JWTs akzeptiert, die von speziell autorisierten Google-Dienstkonten ausgestellt wurden. Das bedeutet, dass nur Clients, die diese Konten verwenden, mit dem Endpunkt interagieren können.

Auf dieser Seite werden die erforderlichen Schritte zum Einrichten eines Indexendpunkts mit JSON Web Token (JWT)-Authentifizierung und zum Ausführen von Abfragen beschrieben.

Beschränkungen

  • Die JWT-Authentifizierung wird nur für private Endpunkte mit VPC-Peering oder Private Service Connect (PSC) unterstützt.
  • Die JWT-Authentifizierung wird nur für RPC APIs auf Datenebene (z. B. MatchService) unterstützt, die mit gRPC aufgerufen werden. In den RPC-Beispielen auf dieser Seite wird das Open-Source-Tool grpc_cli verwendet, um gRPC-Anfragen an den bereitgestellten Indexserver zu senden.
  • Admin-APIs zum Erstellen, Bereitstellen und Verwalten von Indexen werden mithilfe von vordefinierten IAM-Rollen gesichert.

JWT erstellen und verwenden, um einen Index abzufragen

So erstellen Sie einen Indexendpunkt und fragen ihn mit einem selbstsignierten JWT ab:

Index erstellen

Folgen Sie der Anleitung unter Index erstellen, um einen Vektorsuchindex zu erstellen.

Privaten Endpunkt erstellen

Folgen Sie der Anleitung auf einer der folgenden Dokumentationsseiten, um einen privaten Endpunkt zu erstellen:

Dienstkonto erstellen

Erstellen Sie ein Dienstkonto und weisen Sie ihm die IAM-Rolle Ersteller von Dienstkonto-Tokens zu.

  1. Aktivieren Sie die IAM Service Account Credentials API und erstellen Sie ein Dienstkonto:

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

    Ersetzen Sie die folgenden Werte:

    • PROJECT_ID: Das Projekt, in dem das Dienstkonto erstellt werden soll.
    • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.

    Weitere Informationen zum Erstellen eines Dienstkontos.

  2. Verwenden Sie einen der folgenden Befehle, um Ihrem Dienstkonto die IAM-Rolle iam.serviceAccountTokenCreator zuzuweisen:

    • Mit dem folgenden Befehl erhalten Sie die Berechtigung, JWTs mit dem Dienstkonto einer Compute Engine-VM zu erstellen, an die das Dienstkonto angehängt ist:

      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"

      Ersetzen Sie die folgenden Werte:

      • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
      • PROJECT_ID: Das Projekt, in dem das Dienstkonto erstellt werden soll.

    • Mit dem folgenden Befehl wird die Berechtigung zum Erstellen von JWTs gewährt, indem das Dienstkonto aus Ihrem eigenen Google-Konto (auf Ihrer Workstation) verwendet wird:

      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

      Ersetzen Sie die folgenden Werte:

      • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
      • PROJECT_ID: Das Projekt, in dem das Dienstkonto erstellt werden soll.
      • EMAIL_ADDRESS: Ihre E-Mail-Adresse.

Index mit JWT-Authentifizierungskonfiguration auf dem Endpunkt bereitstellen

  1. Stellen Sie den Index wie im folgenden Beispiel gezeigt für den privaten Endpunkt bereit:

    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

    Ersetzen Sie die folgenden Werte:

    • INDEX_ENDPOINT_ID: Die ID des Indexendpunkts.
    • INDEX_ID: Die ID des Index.
    • DEPLOYED_INDEX_ID: Ein vom Nutzer angegebener String zur eindeutigen Identifizierung des bereitgestellten Index. Er muss mit einem Buchstaben beginnen und darf nur Buchstaben, Zahlen oder Unterstriche enthalten. Formatrichtlinien finden Sie im Artikel zu DeployedIndex.id.
    • DEPLOYED_INDEX_NAME: Der Anzeigename des bereitgestellten Index
    • AUDIENCES: Ein beschreibender String, der die erwartete Zielgruppe für Ihren Dienst, Ihre Arbeitslast oder Ihre Anwendung identifiziert, z. B. "123456-my-app".
    • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
    • PROJECT_ID: Ihre Google Cloud-Projekt-ID.
    • LOCATION: Die Region, in der Sie Vertex AI verwenden.

Index mit einem selbst signierten JWT abfragen

Die erforderlichen Schritte sind im Groben so:

  1. Erstellen Sie eine JWT-Nutzlast.
  2. Signieren Sie das Token mit dem zuvor erstellten Dienstkonto.
  3. Rufen Sie den Index mit einem gRPC-Aufruf ab und geben Sie das Token im Autorisierungsheader an.

Python

JWT-Nutzlast erstellen und signieren

In diesem Beispiel wird die sign_jwt-Methode der Python IAM API Credentials Library verwendet, um ein signiertes Token abzurufen. Weitere Informationen zum Installieren und Verwenden dieser Bibliothek finden Sie in der Dokumentation zu IAM API-Clientbibliotheken.

   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")

Befehlszeile

JWT-Nutzlast erstellen

Bei der Vector Search-Authentifizierung werden JWTs akzeptiert, die mit einem vorab autorisierten Dienstkonto für eine vordefinierte Zielgruppe signiert sind. Das Dienstkonto und die Zielgruppe müssen vom Aufrufer angegeben werden, wenn ein Index an einem privaten Endpunkt bereitgestellt wird. Sobald ein Index mit diesen Einstellungen bereitgestellt wird, müssen alle gRPC API-Anfragen an diesen Endpunkt einen Autorisierungsheader enthalten, der ein JWT enthält, das vom Aussteller (einem Dienstkonto) signiert ist und sich an die angegebene Zielgruppe richtet. Das signierte JWT wird als Inhabertoken im Header authorization der gRPC-Anfrage übergeben. Das JWT muss nicht nur vom Dienstkonto signiert sein, sondern auch die folgenden Ansprüche enthalten:

  • Der Anspruch iss (zugelassener Aussteller) sollte die E-Mail-Adresse des Dienstkontos sein, z. B.:

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

  • Die Anforderungen aud (Zielgruppe) und sub (subject) sollten auf denselben Wert festgelegt sein. Dies ist ein beschreibender String, der die erwartete Zielgruppe für Ihren Dienst, Ihre Arbeitslast oder Ihre Anwendung identifiziert, z. B.:

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

    Dieser Wert muss mit dem --audiences-Argument übereinstimmen, das bei der Indexbereitstellung übergeben wurde.

  • Die Anforderung iat (ausgestellt am) sollte auf den Zeitpunkt festgelegt werden, zu dem das Token ausgestellt wird. Die Anforderung exp (Ablaufzeit) sollte auf eine kurze Zeit später (etwa eine Stunde) festgelegt werden. Diese Werte werden in Unix-Epochenzeit ausgedrückt, z. B.:

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

Im folgenden Beispiel sind diese Ansprüche in einer einzelnen JWT-Nutzlast zu sehen:

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

Die JWT-Nutzlast wird mit dem Dienstkonto signiert, das in der iss-Anforderung angegeben ist.

JWT erstellen

  1. Sie (der Aufrufer) müssen die Rolle roles/iam.serviceAccountTokenCreator für das Dienstkonto verwenden können.

  2. Erstelle eine JSON-Datei mit dem Namen jwt_in.json, die das rohe JWT enthält:

    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

    Ersetzen Sie die folgenden Werte:

    • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
    • PROJECT_ID: Ihre Google Cloud-Projekt-ID.
    • AUDIENCES: Ein beschreibender String, der die erwartete Zielgruppe für Ihren Dienst, Ihre Arbeitslast oder Ihre Anwendung identifiziert, z. B. "123456-my-app".

JWT signieren (REST API)

  1. Erstelle mit dem jq-Tool die curl-Anfragen-Nutzlast, indem du das JWT in einen String codierst:

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

  2. Signiere das Token, indem du die Anfragen-Nutzlast an die REST API-Methode signJwt weitergibst.

    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"

    Ersetzen Sie die folgenden Werte:

    • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
    • PROJECT_ID: Ihre Google Cloud-Projekt-ID.

    Speichern Sie den zurückgegebenen signedJwt-Wert in einer Umgebungsvariablen namens signedJwt.

JWT signieren (gcloud CLI)

Alternativ können Sie das JWT signieren, indem Sie die jwt_in.json-Datei direkt an die gcloud CLI-Methode sign-jwt übergeben.

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

Ersetzen Sie die folgenden Werte:

  • SERVICE_ACCOUNT_ID: Die ID für das Dienstkonto.
  • PROJECT_ID: Ihre Google Cloud-Projekt-ID.

Das signierte JWT wird in der Ausgabedatei jwt_out zurückgegeben. Speichern Sie ihn in einer Umgebungsvariablen namens signedJwt.

Das signierte JWT an den Indexendpunkt senden

Python

Informationen zur Installation des Vertex AI SDK for Python finden Sie unter Vertex AI SDK for Python installieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Python 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

Befehlszeile

Rufen Sie von einer Compute Engine-VM im selben VPC-Netzwerk den Endpunkt MatchService gRPC auf und übergeben Sie das signedJwt-Token im authorization-Header, wie im folgenden Beispiel gezeigt:

./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"

Um diesen Befehl auszuführen, müssen die folgenden Umgebungsvariablen festgelegt sein:

  • TARGET_IP ist die IP-Adresse des bereitgestellten Indexservers. Informationen zum Abrufen dieses Werts finden Sie unter Indexe abfragen, um den nächsten Nachbarn abzurufen.
  • DEPLOYED_INDEX_ID: Ein vom Nutzer angegebener String zur eindeutigen Identifizierung des bereitgestellten Index. Er muss mit einem Buchstaben beginnen und darf nur Buchstaben, Zahlen oder Unterstriche enthalten. Formatrichtlinien finden Sie im Artikel zu DeployedIndex.id.

signedJwt ist die Umgebungsvariable, die das signierte JWT enthält.

Fehlerbehebung

In der folgenden Tabelle sind einige häufige gRPC-Fehlermeldungen aufgeführt.

gRPC-Fehlermeldung Grund
Autorisierungsheader für Index „INDEX_ID“ nicht gefunden Die gRPC-Metadaten enthalten keinen Autorisierungs-Header.
JWT ist in einem ungültigen Format Das Token ist fehlerhaft und kann nicht richtig geparst werden
JWT-Authentifizierung fehlgeschlagen Das Token ist abgelaufen oder nicht vom richtigen Dienstkonto signiert.
Der JWT-Aussteller muss in der Liste der zulässigen Aussteller enthalten sein. Das Token iss ist nicht in der Liste der zulässigen Aussteller auth_config enthalten.
Berechtigungsprüfung für Index „INDEX_ID“ fehlgeschlagen Die Tokenanforderung aud oder sub ist nicht in auth_config-Zielgruppen enthalten

Nächste Schritte