Diese Seite wurde von der Cloud Translation API übersetzt.

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, 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 Konten verwenden, mit dem Endpunkt interagieren können.

Auf dieser Seite werden die erforderlichen Schritte zum Einrichten eines Indexendpunkts mit JSON-Web-Token-Authentifizierung (JWT) und zum Ausführen von Anfragen 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.
Administrator-APIs zum Erstellen, Bereitstellen und Verwalten von Indexen werden durch vordefinierte IAM-Rollen geschützt.

JWT zum Abfragen eines Index erstellen und verwenden

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

Index erstellen

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

Privaten Endpunkt erstellen

Erstellen Sie einen privaten Endpunkt, indem Sie der Anleitung auf einer der folgenden Dokumentationsseiten folgen:

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 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 mit dem Dienstkonto aus Ihrem eigenen Google-Konto (auf Ihrer Workstation) erteilt:
```
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 für den Endpunkt mit JWT-Authentifizierungskonfiguration bereitstellen

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 selbstsignierten JWT abfragen

Auf übergeordneter Ebene sind folgende Schritte erforderlich:

JWT-Payload erstellen
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_jwt der 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 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

Für die 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 werden, sondern auch die folgenden Ansprüche enthalten:

Der Anspruch iss (allowed issuer) 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 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 werden diese Ansprüche 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 iss-Anforderung 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 Roh-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-Anfrage-Payload, indem Sie das JWT in einen String codieren:
```
cat jwt_in.json | jq -Rsa >request.json
```

Signieren Sie das Token, indem Sie die Anfrage-Payload 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 \
   "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.

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 MatchService-Endpunkt 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"

Damit Sie diesen Befehl ausführen können, müssen die folgenden Umgebungsvariablen festgelegt sein:

TARGET_IP ist die IP-Adresse Ihres 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 Ihr signiertes 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 hat ein 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.
Der JWT-Aussteller muss in der Liste der zulässigen Aussteller enthalten sein.	Das Token `iss` ist nicht in den zulässigen Ausstellern von `auth_config` enthalten.
Berechtigungsprüfung für Index „`INDEX_ID`“ fehlgeschlagen	Das Token `aud` oder die Anforderung `sub` ist nicht in `auth_config`-Zielgruppen enthalten.

Nächste Schritte

Weitere Informationen zu JWTs und zur Struktur von Token-Claims finden Sie in 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 für den Endpunkt mit JWT-Authentifizierungskonfiguration 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