Autentikasi Token Web JSON

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

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

Batasan

  • Autentikasi JWT hanya didukung untuk endpoint pribadi dengan peering VPC atau Private Service Connect (PSC).
  • Autentikasi JWT hanya didukung untuk RPC API 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.
  • Admin API untuk pembuatan, deployment, dan pengelolaan indeks diamankan dengan menggunakan peran IAM yang telah ditetapkan.

Membuat dan menggunakan JWT untuk membuat kueri indeks

Ikuti langkah-langkah berikut untuk membuat endpoint indeks dan mengkuerinya 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.

  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 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 ini memberi Anda izin untuk membuat JWT menggunakan akun layanan dari VM Compute Engine yang menyertakan akun layanan:

      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 membuat akun layanan.

    • Perintah berikut memberikan izin untuk membuat JWT dengan 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 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 dalam 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, workload, atau aplikasi Anda, misalnya, "123456-my-app".
    • SERVICE_ACCOUNT_ID: ID untuk akun layanan.
    • PROJECT_ID: ID project Google Cloud Anda.
    • LOCATION: Region tempat Anda menggunakan Vertex AI.

Mengkueri 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.

Membuat payload JWT

Autentikasi Vector Search 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 ke audiens yang disediakan. JWT yang ditandatangani diteruskan sebagai token pemilik di header authorization dari 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, workload, 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 (diterbitkan pada) harus ditetapkan ke saat token dikeluarkan. Klaim exp (waktu habis masa berlaku) harus ditetapkan tidak lama kemudian (sekitar satu jam). Nilai ini dinyatakan dalam waktu Unix epoch, misalnya:

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

Contoh berikut menunjukkan klaim tersebut 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. Ini dienkode dengan base64 untuk transmisi sebagai token pemilik menggunakan metadata gRPC, seperti ditunjukkan dalam contoh berikut, dengan signedJwt adalah variabel lingkungan yang berisi JWT yang ditandatangani:

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

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: ID project Google Cloud Anda.
    • AUDIENCES: String deskriptif yang mengidentifikasi audiens yang diharapkan untuk layanan, workload, atau aplikasi Anda, misalnya, "123456-my-app".

Menandatangani JWT (REST API)

  1. Dengan menggunakan alat jq, buat payload permintaan curl dengan mengenkode JWT ke dalam 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: ID project 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: ID project 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

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

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

  • DEPLOYED_INDEX_SERVER_IP adalah alamat IP untuk server indeks yang di-deploy. Untuk mempelajari cara mengambil nilai ini, baca 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 diurai dengan benar
Autentikasi JWT gagal Masa berlaku token telah habis atau tidak ditandatangani oleh akun layanan yang benar
Penerbit JWT harus berada dalam daftar penerbit yang diizinkan Token iss tidak ada di auth_config penerbit yang diizinkan
Pemeriksaan izin gagal untuk indeks 'INDEX_ID' Klaim token aud atau sub tidak ada dalam audiens auth_config

Langkah selanjutnya