Audiens khusus (layanan)

Halaman ini menjelaskan cara menggunakan audiens kustom untuk otorisasi.

Klien yang memanggil layanan Cloud Run yang dilindungi Identity and Access Management harus memberikan token ID valid yang menyertakan klaim audiens yang cocok dengan URL *.run.app layanan penerima. Untuk klien yang tidak mengetahui URL ini, Anda dapat menggunakan nilai audiens kustom.

Memahami audiens kustom

Cloud Run memberikan peran Invoker (roles/run.invoker) untuk mendukung kontrol akses dengan IAM. Kontrol akses IAM menggunakan token ID yang ditandatangani Google, yang dikemas sebagai Token Web JSON (JWT). Isi token ini sesuai dengan standar OIDC.

Kolom audience dienkode dalam token untuk menentukan target yang dimaksud dan dapat menggunakan token tersebut. Hal ini membatasi risiko serangan replay, yaitu saat token yang disadap yang dimaksudkan untuk digunakan dengan satu layanan akan di-replay ke layanan lain.

Berdasarkan konvensi, audiens adalah URL lengkap layanan target. Secara default di Cloud Run, URL ini adalah URL yang dibuat Google untuk layanan yang diakhiri dengan run.app.

Namun, layanan Cloud Run mungkin berada di belakang URL selain URL yang dibuat default, seperti dalam skenario berikut:

Saat menggunakan domain kustom untuk menjangkau layanan yang klien tidak mengetahui URL yang dibuat Google.
Saat men-deploy beberapa layanan di balik load balancer, klien tidak dapat mengantisipasi layanan regional yang dijangkau permintaan. URL yang dibuat Google untuk layanan bersifat spesifik per wilayah, meskipun nama layanannya sama.

Dalam skenario ini, Anda harus mengonfigurasi layanan untuk menerima nilai audiens kustom yang mengizinkan target tambahan yang diketahui oleh klien. URL default yang dibuat Google selalu tetap sebagai nilai audiens yang diterima.

Menetapkan dan memperbarui audiens kustom

Penetapan audiens kustom untuk Cloud Run dilakukan di tingkat layanan dan berlaku untuk semua revisi penayangan, mirip dengan keanggotaan otorisasi IAM.

Anda dapat menetapkan beberapa audiens kustom, selama encoding JSON untuk audiens sebagai daftar string tidak melebihi 32.768 karakter.

Setiap perubahan konfigurasi akan menghasilkan revisi baru. Revisi berikutnya juga akan otomatis mendapatkan setelan konfigurasi ini, kecuali jika Anda melakukan pembaruan eksplisit untuk mengubahnya.

Command line

Anda dapat menetapkan audiens kustom pada layanan menggunakan perintah berikut:

gcloud run services update SERVICE --add-custom-audiences=AUDIENCE

Ganti

SERVICE dengan nama layanan Cloud Run Anda
AUDIENCE dengan string untuk audiens kustom yang ingin Anda dukung, misalnya, myservice atau https://myservice.example.com

Anda dapat menghapus semua audiens kustom dari layanan menggunakan perintah berikut:

gcloud run services update SERVICE --clear-custom-audiences

YAML

Anda dapat mendownload dan melihat konfigurasi layanan yang ada menggunakan perintah gcloud run services describe --format export, yang memberikan hasil yang telah diolah dalam format YAML. Kemudian, Anda dapat mengubah kolom yang dijelaskan di bawah ini dan mengunggah YAML yang telah dimodifikasi menggunakan perintah gcloud run services replace. Pastikan Anda hanya mengubah kolom seperti yang didokumentasikan.

Untuk melihat dan mengunduh konfigurasi:

gcloud run services describe SERVICE --format export > service.yaml

Tetapkan anotasi run.googleapis.com/custom-audiences pada metadata Layanan (tidak di metadata template):googledata/devsite/site-cloud/en/run/docs/authenticating/service-to-service.md
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE"]'
spec:
  template:
    ...
```
Ganti
- SERVICE dengan nama layanan Cloud Run Anda
- AUDIENCE dengan string untuk audiens kustom yang ingin Anda dukung, misalnya, myservice atau https://myservice.example.com
Perhatikan bahwa nilai atribut adalah array JSON yang dikutip dari string, yang memerlukan penggunaan tanda kutip ganda dan tunggal.
Ganti layanan dengan konfigurasi barunya menggunakan perintah berikut:
```
gcloud run services replace service.yaml
```

Memverifikasi audiens kustom

Mendapatkan token ID untuk akun layanan yang memiliki izin IAM untuk memanggil layanan. Perhatikan penggunaan audiens kustom AUDIENCE.
```
export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')
```
Replace:
- SERVICE_ACCOUNT_EMAIL dengan email akun layanan. Di akhiri dengan .iam.gserviceaccount.com.
- AUDIENCE dengan nilai audiens kustom yang Anda tetapkan pada layanan.
Memanggil endpoint layanan dengan token ID tersebut
```
curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT
```
Ganti ENDPOINT dengan endpoint untuk menjangkau layanan Anda, misalnya, domain kustomnya atau URL .run.app.
Konfirmasi bahwa permintaan tersebut sah dan Anda melihat respons yang diharapkan dari layanan.