Autentikasi Token Web JSON

Vector Search mendukung endpoint indeks yang diautentikasi menggunakan Token Web JSON (JWT) yang ditandatangani sendiri. Untuk mengontrol akses ke endpoint indeks, endpoint tersebut dikonfigurasi agar hanya menerima JWT yang ditandatangani yang dikeluarkan oleh akun layanan Google yang diotorisasi secara khusus. Artinya, hanya klien yang menggunakan akun yang ditetapkan tersebut yang dapat berinteraksi dengan endpoint.

Halaman ini menguraikan langkah-langkah yang diperlukan untuk menyiapkan endpoint indeks dengan autentikasi Token Web JSON (JWT) dan menjalankan kueri terhadapnya.

Batasan

  • Autentikasi JWT hanya didukung untuk endpoint pribadi dengan peering VPC atau Private Service Connect (PSC).
  • Autentikasi JWT hanya didukung untuk API RPC bidang data (seperti MatchService) yang dipanggil menggunakan gRPC. Contoh RPC di halaman ini menggunakan alat grpc_cli open source untuk mengirim permintaan gRPC ke server indeks yang di-deploy.
  • API admin untuk pembuatan, deployment, dan pengelolaan indeks diamankan dengan menggunakan peran IAM bawaan.

Membuat dan menggunakan JWT untuk membuat kueri indeks

Ikuti langkah-langkah berikut untuk membuat endpoint indeks dan membuat kueri dengan JWT yang ditandatangani sendiri.

Membuat indeks

Buat indeks Vector Search dengan mengikuti petunjuk di Membuat indeks.

Membuat endpoint pribadi

Buat endpoint pribadi dengan mengikuti petunjuk di salah satu halaman dokumentasi berikut:

Membuat akun layanan

Buat akun layanan dan berikan peran IAM Service Account Token Creator kepadanya.

  1. Aktifkan IAM Service Account Credentials API dan buat akun layanan:

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

    Ganti nilai berikut:

    • PROJECT_ID: Project tempat Anda akan membuat akun layanan.
    • SERVICE_ACCOUNT_ID: ID untuk akun layanan.

    Pelajari lebih lanjut cara membuat akun layanan.

  2. Gunakan salah satu perintah berikut untuk memberikan peran IAM iam.serviceAccountTokenCreator ke akun layanan Anda:

    • Perintah berikut memberi Anda izin untuk membuat JWT menggunakan akun layanan dari VM Compute Engine yang memiliki akun layanan yang terpasang:

      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"

      Ganti nilai berikut:

      • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
      • PROJECT_ID: Project tempat Anda akan membuat akun layanan.

    • Perintah berikut memberikan izin untuk membuat JWT menggunakan akun layanan dari Akun Google Anda sendiri (di workstation Anda):

      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

      Ganti nilai berikut:

      • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
      • PROJECT_ID: Project tempat Anda akan membuat akun layanan.
      • EMAIL_ADDRESS: Alamat email Anda.

Men-deploy indeks ke endpoint dengan konfigurasi autentikasi JWT

  1. Deploy indeks ke endpoint pribadi seperti yang ditunjukkan pada contoh berikut:

    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

    Ganti nilai berikut:

    • INDEX_ENDPOINT_ID: ID endpoint indeks.
    • INDEX_ID: ID indeks.
    • DEPLOYED_INDEX_ID: String yang ditentukan pengguna untuk mengidentifikasi indeks yang di-deploy secara unik. Nama ini harus diawali dengan huruf dan hanya berisi huruf, angka, atau garis bawah. Lihat DeployedIndex.id untuk panduan format.
    • DEPLOYED_INDEX_NAME: Nama tampilan indeks yang di-deploy.
    • AUDIENCES: String deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, beban kerja, atau aplikasi Anda, misalnya, "123456-my-app".
    • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
    • PROJECT_ID: project ID Google Cloud Anda.
    • LOCATION: Region tempat Anda menggunakan Vertex AI.

Membuat kueri indeks dengan JWT yang ditandatangani sendiri

Pada tingkat tinggi, langkah-langkah yang diperlukan adalah sebagai berikut:

  1. Buat payload JWT.
  2. Tanda tangani token menggunakan akun layanan yang dibuat sebelumnya.
  3. Buat kueri indeks menggunakan panggilan gRPC, dengan meneruskan token di header otorisasi.

Python

Membuat dan Menandatangani payload JWT

Contoh ini menggunakan metode sign_jwt library Kredensial IAM API Python untuk mendapatkan token yang ditandatangani. Untuk mempelajari lebih lanjut cara menginstal dan menggunakan library ini, lihat dokumentasi Library Klien IAM API.

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

Command-line

Membuat payload JWT

Autentikasi Penelusuran Vektor menerima JWT yang ditandatangani dengan akun layanan yang telah diotorisasi sebelumnya, untuk audiens yang telah ditentukan. Akun layanan dan audiens harus ditentukan oleh pemanggil saat indeks di-deploy ke endpoint pribadi. Setelah indeks di-deploy dengan setelan ini, semua permintaan gRPC API ke endpoint tersebut harus menyertakan header otorisasi yang berisi JWT yang ditandatangani oleh penerbit (akun layanan) dan ditargetkan untuk audiens yang disediakan. JWT yang ditandatangani diteruskan sebagai token pembawa di header authorization permintaan gRPC. Selain ditandatangani oleh akun layanan, JWT harus menyertakan klaim berikut:

  • Klaim iss (penerbit yang diizinkan) harus berupa alamat email akun layanan, misalnya:

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

  • Klaim aud (audiens) dan sub (subjek) harus ditetapkan ke nilai yang sama. Ini adalah string deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, beban kerja, atau aplikasi Anda, misalnya:

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

    Nilai ini harus cocok dengan argumen --audiences yang diteruskan pada waktu deployment indeks.

  • Klaim iat (issued at) harus ditetapkan ke waktu token diterbitkan. Klaim exp (waktu habis masa berlaku) harus ditetapkan ke waktu yang singkat (sekitar satu jam). Nilai ini dinyatakan dalam waktu epoch Unix, misalnya:

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

Contoh berikut menunjukkan klaim ini dalam satu payload JWT:

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

Payload JWT ditandatangani menggunakan akun layanan yang ditentukan dalam klaim iss.

Membuat JWT

  1. Pastikan Anda (pemanggil) dapat menggunakan peran roles/iam.serviceAccountTokenCreator di akun layanan.

  2. Buat file JSON bernama jwt_in.json yang berisi JWT mentah:

    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

    Ganti nilai berikut:

    • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
    • PROJECT_ID: project ID Google Cloud Anda.
    • AUDIENCES: String deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, beban kerja, atau aplikasi Anda, misalnya, "123456-my-app".

Menandatangani JWT (REST API)

  1. Dengan menggunakan alat jq, buat payload permintaan curl dengan mengenkode JWT menjadi string:

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

  2. Tanda tangani token dengan meneruskan payload permintaan ke metode REST API signJwt.

    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"

    Ganti nilai berikut:

    • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
    • PROJECT_ID: project ID Google Cloud Anda.

    Simpan nilai signedJwt yang ditampilkan ke dalam variabel lingkungan yang disebut signedJwt.

Menandatangani JWT (gcloud CLI)

Atau, Anda dapat menandatangani JWT dengan meneruskan file jwt_in.json langsung ke metode sign-jwt gcloud CLI.

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

Ganti nilai berikut:

  • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
  • PROJECT_ID: project ID Google Cloud Anda.

JWT yang ditandatangani ditampilkan dalam file output jwt_out. Simpan ke dalam variabel lingkungan yang disebut signedJwt.

Mengirim JWT yang ditandatangani ke endpoint indeks

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi 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

Command-line

Dari VM Compute Engine di jaringan VPC yang sama, panggil endpoint MatchService gRPC, dengan meneruskan token signedJwt di header authorization, seperti yang ditunjukkan dalam contoh berikut:

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

Untuk menjalankan perintah ini, Anda harus menetapkan variabel lingkungan berikut:

  • TARGET_IP adalah alamat IP untuk server indeks yang di-deploy. Untuk mempelajari cara mengambil nilai ini, lihat Indeks kueri untuk mendapatkan tetangga terdekat.
  • DEPLOYED_INDEX_ID: String yang ditentukan pengguna untuk mengidentifikasi indeks yang di-deploy secara unik. Nama ini harus diawali dengan huruf dan hanya berisi huruf, angka, atau garis bawah. Lihat DeployedIndex.id untuk panduan format.

signedJwt adalah variabel lingkungan yang berisi JWT yang ditandatangani.

Pemecahan masalah

Tabel berikut mencantumkan beberapa pesan error gRPC umum.

Pesan Error gRPC Alasan
Header otorisasi tidak ditemukan untuk indeks 'INDEX_ID' Metadata gRPC tidak berisi header otorisasi
Format JWT tidak valid Format token salah dan tidak dapat diuraikan dengan benar
Autentikasi JWT gagal Masa berlaku token telah berakhir atau tidak ditandatangani oleh akun layanan yang benar
Penerbit JWT harus berada dalam daftar penerbit yang diizinkan Token iss tidak ada dalam penerbit yang diizinkan auth_config
Pemeriksaan izin gagal untuk indeks 'INDEX_ID' Klaim token aud atau sub tidak ada di audiens auth_config

Langkah selanjutnya