Authentifizierung mit JSON Web Token

Die Vektorsuche unterstützt authentifizierte Indexendpunkte mithilfe von selbstsignierten JSON Web Tokens (JWTs). Zur Steuerung des Zugriffs auf den Indexendpunkt ist er so konfiguriert, dass er nur signierte JWTs akzeptiert, die von speziell autorisierten Google-Dienstkonten ausgegeben wurden. Das bedeutet, dass nur Clients, die die entsprechenden Konten verwenden, mit dem Endpunkt interagieren können.

Auf dieser Seite werden die erforderlichen Schritte zum Einrichten eines Indexendpunkts mit der JSON Web Token-Authentifizierung (JWT) und zum Ausführen von Abfragen dafür 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. Die RPC-Beispiele auf dieser Seite verwenden das Open-Source-Tool grpc_cli, 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 zum Abfragen eines Index erstellen und verwenden

Führen Sie die folgenden Schritte aus, um einen Indexendpunkt zu erstellen und mit einem selbst signierten JWT abzufragen.

Index erstellen

Erstellen Sie einen Vektorsuchindex. Folgen Sie dazu der Anleitung unter Index erstellen.

Privaten Endpunkt erstellen

Erstellen Sie einen privaten Endpunkt. Folgen Sie dazu der Anleitung auf einer der folgenden Dokumentationsseiten:

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 können Sie JWTs erstellen. Dazu verwenden Sie das Dienstkonto einer Compute Engine-VM, 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.

    • Der folgende Befehl gewährt die Berechtigung zum Erstellen von JWTs mithilfe des Dienstkontos aus Ihrem eigenen Google-Konto (auf Ihrer 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

      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 für den privaten Endpunkt bereit, wie im folgenden Beispiel gezeigt:

    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

Auf übergeordneter Ebene sind folgende Schritte erforderlich:

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

JWT-Nutzlast erstellen

Die Authentifizierung der Vektorsuche akzeptiert JWTs, die mit einem vorautorisierten Dienstkonto für eine vordefinierte Zielgruppe signiert wurden. Das Dienstkonto und die Zielgruppe müssen vom Aufrufer angegeben werden, wenn ein Index auf 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 Anforderungen enthalten:

  • Die Anforderung iss (zugelassener Aussteller) sollte die E-Mail-Adresse des Dienstkontos sein. Beispiel:

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

  • Die Anforderungen aud (audience) 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. Beispiel:

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

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

  • Die Anforderung iat (issued at) sollte auf den Zeitpunkt festgelegt werden, zu dem das Token ausgestellt wird. Die Anforderung exp (expiration time) sollte auf eine kurze Zeit später (etwa eine Stunde) festgelegt werden. Diese Werte werden in Unix-Epochen-Zeit ausgedrückt. Beispiel:

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

Das folgende Beispiel zeigt diese Anforderungen in einer einzelnen JWT-Nutzlast:

{
   "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 Anforderung iss angegeben ist. Es ist für die Übertragung als Inhabertoken mithilfe der gRPC-Metadaten base64-codiert, wie im folgenden Beispiel gezeigt. Dabei ist signedJwt eine Umgebungsvariable, die ein signiertes JWT enthält:

./grpc_cli call ... --metadata "authorization: Bearer $signedJwt"

JWT erstellen

  1. Achten Sie darauf, dass Sie (der Aufrufer) die Rolle roles/iam.serviceAccountTokenCreator für das Dienstkonto verwenden können.

  2. Erstellen Sie eine JSON-Datei mit dem Namen jwt_in.json, die das RAW-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. Erstellen Sie mit dem jq-Tool die Anfragenutzlast curl. Codieren Sie dazu das JWT in einen String:

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

  2. Signieren Sie das Token, indem Sie die Anfragenutzlast an die REST API-Methode signJwt übergeben.

    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"

    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 Datei jwt_in.json direkt an die Methode sign-jwt der gcloud CLI ü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 diese in einer Umgebungsvariable namens signedJwt.

Signiertes JWT an den Indexendpunkt senden

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

./grpc_cli call ${DEPLOYED_INDEX_SERVER_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match \
   '{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}' \
   --metadata "authorization: Bearer $signedJwt"

Zum Ausführen dieses Befehls müssen die folgenden Umgebungsvariablen festgelegt werden:

  • DEPLOYED_INDEX_SERVER_IP ist die IP-Adresse für den bereitgestellten Indexserver. Informationen zum Abrufen dieses Werts finden Sie unter Indexabfrage zur Ermittlung nächster Nachbarn.
  • 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äufig auftretende gRPC-Fehlermeldungen aufgeführt.

gRPC-Fehlermeldung Begründung
Autorisierungsheader für Index „INDEX_ID“ nicht gefunden Die gRPC-Metadaten enthalten keinen Autorisierungsheader.
JWT hat ungültiges Format Das Token ist fehlerhaft und kann nicht richtig geparst werden
JWT-Authentifizierung fehlgeschlagen Das Token ist abgelaufen oder wurde nicht vom richtigen Dienstkonto signiert.
JWT-Aussteller muss in der Liste der zulässigen Aussteller enthalten sein Das Token iss befindet sich nicht in auth_config zulässigen Ausstellern
Berechtigungsprüfung für Index "INDEX_ID" schlägt fehl Die Token-Anforderung aud oder sub befindet sich nicht in auth_config-Zielgruppen.

Nächste Schritte