設定服務的自訂目標對象

本頁說明如何使用授權的自訂目標對象。

呼叫受 Identity and Access Management 保護的 Cloud Run 服務時，用戶端必須提供有效的 ID 權杖，其中包含與接收服務的 *.run.app URL 相符的對象聲明。如果客戶不知道這個網址，可以使用自訂目標對象值。

瞭解自訂目標對象

Cloud Run 提供「調用者」角色 (roles/run.invoker)，支援透過 IAM 控管存取權。IAM 存取權控管會使用 Google 簽署的 ID 權杖，這些權杖會封裝為 JSON Web Token (JWT)。這些權杖的內容符合 OIDC 標準。

權杖中會編碼目標對象欄位，指定可使用權杖的預期目標。這樣一來，如果有人攔截到原本要用於某項服務的權杖，就無法將該權杖用於其他服務，降低重播攻擊的風險。

按照慣例，目標對象是目標服務的完整網址。在 Cloud Run 中，這預設是 Google 為服務產生的網址，結尾為 run.app。

不過，Cloud Run 服務可能位於預設產生的網址以外的網址後方，例如在下列情況中：

  • 使用自訂網域連線至服務時，用戶端不知道 Google 產生的網址。
  • 在負載平衡器後方部署多項服務時，用戶端無法預期要求會連線到哪個區域服務。即使服務名稱相同，Google 產生的服務網址也會因區域而異。

在這些情況下，您必須設定服務來接受自訂目標對象值，允許用戶端已知的其他目標。系統產生的預設網址一律會保留為可接受的目標對象值。

設定及更新自訂目標對象

為 Cloud Run 設定自訂目標對象時，您會在服務層級進行設定，並套用至所有提供服務的修訂版本，與 IAM 授權成員資格類似。

您可以設定多個自訂目標對象，只要以字串清單形式進行 JSON 編碼的目標對象不超過 32,768 個字元即可。

變更任何設定都會建立新的修訂版本。除非您明確做出更新，變更這項設定，否則後續的修訂版本也會自動取得這個設定。

gcloud

您可以使用下列指令，在服務上設定自訂目標對象：

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

取代

  • SERVICE 改為 Cloud Run 服務名稱
  • AUDIENCE，並提供要支援的自訂目標對象字串，例如 myservice 或 https://myservice.example.com

您可以使用下列指令，從服務中移除所有自訂目標對象：

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

YAML

  1. 如要建立新服務，請略過這個步驟。 如要更新現有服務，請下載其 YAML 設定：

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

  2. 在 Service 中繼資料上設定 run.googleapis.com/custom-audiences 註解 (不是在 template 中繼資料上)：

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE"]'
spec:
  template:
    ...

    取代

    • SERVICE 改為 Cloud Run 服務名稱
    • AUDIENCE，並提供要支援的自訂目標對象字串，例如 myservice 或 https://myservice.example.com

    請注意，屬性的值是加上引號的 JSON 字串陣列，因此必須同時使用雙引號和單引號。

  3. 使用下列指令，將服務替換為新設定：

    gcloud run services replace service.yaml

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

在 Terraform 設定中，將下列項目新增至 google_cloud_run_v2_service 資源：

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"

  custom_audiences = ["AUDIENCE"]
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

取代：

  • SERVICE 改為您的 Cloud Run 服務名稱。
  • REGION 替換成 Google Cloud 地區。例如：europe-west1。
  • AUDIENCE，並提供要支援的自訂目標對象字串，例如 myservice。

驗證自訂目標對象

  1. 取得服務帳戶的 ID 權杖，該服務帳戶具有叫用服務的 IAM 權限。請注意，這裡使用的是自訂目標對象 AUDIENCE。

    export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')

    取代：

    • SERVICE_ACCOUNT_EMAIL 服務帳戶的電子郵件地址。結尾為 .iam.gserviceaccount.com。
    • AUDIENCE，這是您在服務中設定的自訂目標對象值。

  2. 使用該 ID 權杖呼叫服務的端點

    curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT

    將 ENDPOINT 替換為服務的端點，例如自訂網域或 .run.app 網址。

  3. 確認要求已獲得授權，且服務會傳回預期回應。