Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Authentifizierung mit JSON Web Token

Die Vektorsuche unterstützt authentifizierte Indexendpunkte mit selbstsignierten JSON Web Tokens (JWTs). Um den Zugriff auf den Indexendpunkt zu steuern, ist er so konfiguriert, dass nur signierte JWTs akzeptiert werden, die von speziell autorisierten Google-Dienstkonten ausgestellt wurden. Das bedeutet, dass nur Clients, die diese angegebenen 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 grpc_cli Tool verwendet, um gRPC-Anfragen an den bereitgestellten Indexserver zu senden.
Admin-APIs zum Erstellen, Bereitstellen und Verwalten von Indexen werden mit vordefinierten IAM-Rollen geschützt.

JWT zum Abfragen eines Index erstellen und verwenden

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

Index erstellen

Erstellen Sie einen Vektorsuchindex gemäß der Anleitung unter Index erstellen.

Privaten Endpunkt erstellen

Erstellen Sie einen privaten Endpunkt gemäß 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.

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.
Verwenden Sie einen der folgenden Befehle, um Ihrem Dienstkonto die IAM-Rolle iam.serviceAccountTokenCreator zuzuweisen:
- Mit dem folgenden Befehl haben Sie die Berechtigung, JWTs mit dem Dienstkonto von einer Compute Engine-VM aus 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 erteilt, JWTs mit dem Dienstkonto von Ihrem eigenen Google-Konto aus (auf Ihrer Workstation) zu erstellen:
```
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 für den Endpunkt bereitstellen

Stellen Sie den Index wie im folgenden Beispiel 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 die Agent Platform verwenden.

Index mit einem selbstsignierten JWT abfragen

Auf übergeordneter Ebene sind die folgenden Schritte erforderlich:

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

Python

JWT-Nutzlast erstellen und signieren

In diesem Beispiel wird die Methode sign_jwtder Python IAM API Credentials-Bibliothek verwendet, um ein signiertes Token abzurufen. Weitere Informationen zum Installieren und Verwenden dieser Bibliothek finden Sie in der Dokumentation zu den 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

Die Vektorsuchauthentifizierung 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 für einen 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 Bearertoken im authorization-Header der gRPC-Anfrage übergeben. Das JWT muss nicht nur vom Dienstkonto signiert sein, sondern auch die folgenden Anforderungen enthalten:

Die Anforderung iss (zulässiger 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 Argument --audiences ü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 der 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 Anforderungen in einer einzelnen JWT-Nutzlast dargestellt:

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

JWT erstellen

Achten Sie darauf, dass Sie (der Aufrufer) die Rolle roles/iam.serviceAccountTokenCreator für das Dienstkonto verwenden können.
Erstellen Sie eine JSON-Datei mit dem Namen jwt_in.json, die das unformatierte 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)

Erstellen Sie mit dem jq Tool die curl Anfragenutzlast, indem Sie das JWT in einen String codieren:
```
cat jwt_in.json | jq -Rsa >request.json
```

Signieren Sie das Token, indem Sie die Anfragenutzlast an die signJwt REST API-Methode ü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 \
   "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 Wert signedJwt 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 gcloud CLI sign-jwt Methode ü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 es in einer Umgebungsvariablen namens signedJwt.

Signiertes 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 Python API-Referenzdokumentation.

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 gRPC-Endpunkt MatchService auf und übergeben Sie das Token signedJwt im Header authorization, 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"

Damit dieser Befehl ausgeführt werden kann, müssen die folgenden Umgebungsvariablen festgelegt sein:

TARGET_IP ist die IP-Adresse für Ihren bereitgestellten Index server. 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 Ihr signiertes JWT enthält.

Fehlerbehebung

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

gRPC-Fehlermeldung	Grund
Authorization header not found for index '`INDEX_ID`'	Die gRPC-Metadaten enthalten keinen Autorisierungsheader.
JWT is invalid format	Das Token ist fehlerhaft und kann nicht richtig geparst werden.
JWT authentication failed	Das Token ist abgelaufen oder wurde nicht vom richtigen Dienstkonto signiert.
JWT issuer should be in the allowed issuers list	Der Token `iss` ist nicht in den zulässigen Ausstellern von `auth_config` enthalten.
Permission check fail for index '`INDEX_ID`'	Die Tokenanforderung `aud` oder `sub` ist nicht in den Zielgruppen von `auth_config` enthalten.

Nächste Schritte

Weitere Informationen zu JWTs und zur Struktur von Tokenanforderungen finden Sie unter RFC 7519.
Weitere Informationen zum Erstellen eines selbstsignierten JSON Web Tokens (JWT)
Index aktualisieren und neu erstellen
Index beobachten

Authentifizierung mit JSON Web Token Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Beschränkungen

JWT zum Abfragen eines Index erstellen und verwenden

Index erstellen

Privaten Endpunkt erstellen

Dienstkonto erstellen

Index mit JWT-Authentifizierungskonfiguration für den Endpunkt bereitstellen

Index mit einem selbstsignierten JWT abfragen

Python

JWT-Nutzlast erstellen und signieren

Befehlszeile

JWT-Nutzlast erstellen

JWT erstellen

JWT signieren (REST API)

JWT signieren (gcloud CLI)

Signiertes JWT an den Indexendpunkt senden

Python

Befehlszeile

Fehlerbehebung

Nächste Schritte

Authentifizierung mit JSON Web Token