使用 Google 驗證

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本主題說明如何設定及部署已設定為使用 Google 驗證機制的 API Proxy。

簡介

Apigee 支援使用 Google OAuth 權杖或 OpenID Connect 權杖，驗證 Google 服務，例如 Cloud Logging 和 Secret Manager，以及在特定產品上執行的客製化服務，例如 Cloud Functions 和 Cloud Run。 Google Cloud

如要使用這項功能，您必須在下列其中一個情境中設定 <Authentication> XML 元素：

  • AssignMessage 政策
  • ServiceCallout 政策
  • ExternalCallout 政策
  • TargetEndpoint 設定

完成一些基本設定步驟 (如本主題所述) 後，Apigee 就會執行權杖產生作業，並為您發出安全呼叫，連線至指定的 Google 服務或自訂代管服務，無須手動設定驗證標頭或以其他方式修改服務要求。從 API 開發人員的角度來看，從正確設定的 API Proxy 中呼叫 Google 服務的程序會順暢處理。

API Proxy 設定選項

本節說明如何使用 <Authentication> XML 元素啟用 Google OAuth 權杖或 OpenID Connect 驗證：

設定選項 說明
AssignMessage 政策 您可以使用 AssignMessage 政策，新增 Google 驗證和權杖插入作業所需的標頭。如需使用方式詳細說明和範例，請參閱「 AssignMessage 政策」。
ServiceCallout 政策 ServiceCallout 政策可讓您透過 API Proxy 呼叫其他內部或外部服務。舉例來說，ServiceCallout 可以呼叫外部 Google 服務或自訂代管服務。如需使用方式詳細說明和範例，請參閱 服務快訊政策。
ExternalCallout policy 您可以使用 ExternalCallout 政策，將 gRPC 要求傳送至 gRPC 伺服器，藉此實作 Apigee 政策不支援的自訂行為。如需使用方式詳細說明和範例，請參閱 外部資訊框政策。
TargetEndpoint 指定 Google 服務或自訂代管服務做為 API Proxy 目標端點。如需用法詳細資訊和範例，請參閱「API Proxy 設定參考資料」。

Google Auth 權杖支援的背景資訊

<Authentication> 元素有兩種子元素設定：<GoogleAccessToken> 或 <GoogleIDToken>。下表列出這些元素支援的內容：

使用於 GoogleAccessToken GoogleIDToken
AssignMessage 政策 支援 支援
ServiceCallout 政策 支援 支援
ExternalCallout 政策 不支援 支援
TargetEndpoint 支援 支援

部署步驟

本節說明如何部署 API 代理程式，以便使用 Google 驗證功能呼叫指定的 Google 服務或自訂代管服務。我們會分別說明 Apigee 和 Apigee Hybrid 的部署步驟。

在 Apigee 上部署

下列步驟說明如何在 Apigee 上部署 API 代理程式，並設定代理程式，以便對 Google 服務或自訂代管服務發出經過驗證的呼叫。這些步驟假設您已建立 Proxy，且 Proxy 在所列的支援的內容中包含 <Authentication> 元素。

  1. 在建立 Apigee 機構的 Google Cloud專案中建立 Google 服務帳戶。當您部署已設定為使用 Google 驗證的 API Proxy 時，必須提供這個服務帳戶的名稱，而產生的 OAuth 權杖將代表該服務帳戶。您可以在 Google Cloud 控制台中建立服務帳戶，也可以使用 gcloud 指令。請參閱「建立及管理服務帳戶」。
  2. 請將服務帳戶的 iam.serviceAccounts.actAs 權限授予將要進行部署的使用者 (部署者)。另請參閱「關於服務帳戶權限」。 
    gcloud iam service-accounts add-iam-policy-binding \
SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member="MEMBER" \
  --role="roles/iam.serviceAccountUser"

    3. 其中：

    • PROJECT_ID：專案 ID。這個 ID 與貴機構名稱相同。
    • SA_NAME：您建立服務帳戶時提供的名稱。
    • MEMBER：要新增繫結的成員。格式應為 user|group|serviceAccount:email 或 domain:domain。
  3. 授予服務帳戶與指定 Google 服務通訊所需的權限。舉例來說，如果您要呼叫 Google 記錄服務，這個服務帳戶必須具備與該服務通訊所需的權限。另請參閱瞭解角色。
  4. 如要部署已設定為使用 Google 驗證機制的 API Proxy，您必須：
    • 您先前建立的服務帳戶名稱。例如： SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • 您必須具備服務帳戶的 iam.serviceAccounts.actAs 權限，才能執行部署作業。請參閱「授予、變更及撤銷資源的存取權」。
  5. 部署含有您實作 Google 驗證設定的 API Proxy。您可以使用 Apigee UI 或 API 部署 Proxy。詳情請參閱「部署 API Proxy」。
    • 如果使用使用者介面，系統會要求您提供服務帳戶名稱。使用您在步驟 1 中建立的proxy 服務帳戶名稱。例如：SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

    • 如果您想使用 Apigee 部署 API 部署 Proxy，請參考以下範例 cURL 指令。請注意，這項指令會將服務帳戶名稱納入查詢參數。這是您在步驟 1 中建立的服務帳戶名稱：
      curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
-H "Content-Type: application/json" -X POST

      其中：

      • TOKEN：您必須取得的 OAuth 權杖，才能換取 Google 憑證。詳情請參閱「取得 OAuth 2.0 存取權杖」。
      • ORG_NAME：您的 Apigee 機構名稱。
      • ENV_NAME：要部署 API Proxy 的環境名稱。
      • SA_NAME：您在建立服務帳戶時提供的名稱。
      • PROJECT_ID：您的 Google Cloud 專案 ID (與機構名稱相同)。
  6. 部署作業完成後，請測試 API 代理程式，確認 Google 服務會傳回預期的回應。

在 Apigee Hybrid 上部署

下列步驟說明如何在 Apigee hybrid 中部署 API 代理程式，並將其設定為對 Google 服務發出經過驗證的呼叫。這些步驟假設您已建立 Proxy，且 Proxy 在所列的支援的內容中包含 <Authentication> 元素。

  1. 使用下列任一方法，為 Apigee hybrid runtime 元件建立服務帳戶和金鑰：
    • 請使用 Apigee hybrid 隨附的 create-service-account 工具建立 apigee-runtime 服務帳戶。這項工具會建立服務帳戶，並傳回服務帳戶金鑰。詳情請參閱 create-service-account。
    • 您可以在 Google Cloud 控制台中建立服務帳戶，也可以使用 gcloud 指令建立。請參閱「建立及管理服務帳戶」。 如要擷取服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。
  2. 開啟 overrides.yaml 檔案，並為每個需要 Google 驗證功能的環境指定服務帳戶金鑰檔案路徑：
    envs:
  - name: "ENVIRONMENT_NAME"
    serviceAccountPaths:
      runtime: "KEY_FILE_PATH"

    例如：

    envs:
  - name: "test"
    serviceAccountPaths:
      runtime: "./service_accounts/my_runtime_sa.json"
  3. 使用 Helm 將覆寫檔案套用至叢集：
    helm upgrade ENV_NAME apigee-env/ \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  --atomic \
  -f overrides.yaml
  4. 建立第二個服務帳戶，我們稱之為proxy 服務帳戶。這個服務帳戶必須位於您用來建立 Apigee 機構的 Google Cloud專案中。當您部署已設定為使用 Google 驗證的 API Proxy 時，必須提供這個服務帳戶的電子郵件地址，而產生的 OAuth 權杖將代表服務帳戶。
  5. 請將服務帳戶的 iam.serviceAccounts.actAs 權限授予將要進行部署的使用者 (部署者)。另請參閱「關於服務帳戶權限」。 
    gcloud iam service-accounts add-iam-policy-binding \
SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member="MEMBER" \
  --role="roles/iam.serviceAccountUser"

    6. 其中：

    • PROJECT_ID：專案 ID。這個 ID 與貴機構名稱相同。
    • SA_NAME：您在建立服務帳戶時提供的名稱。
    • MEMBER：要新增繫結的成員。格式應為 user|group|serviceAccount:email 或 domain:domain。
  6. 授予proxy 服務帳戶與指定 Google 服務通訊所需的權限。舉例來說，如果您要呼叫 Google 記錄服務，這個服務帳戶必須具備與該服務通訊所需的權限。另請參閱瞭解角色。
  7. 請確認執行階段能夠模擬 Proxy 服務帳戶。如要提供這項功能，請將 iam.serviceAccountTokenCreator 角色授予 Proxy Service Account 的執行階段服務帳戶。另請參閱「關於服務帳戶權限」。例如： 
    gcloud iam service-accounts add-iam-policy-binding \
PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator

    其中：

    • PROJECT_ID：專案 ID。這個 ID 與貴機構名稱相同。請注意，您不必使用與貴機構相關聯的專案建立執行階段服務帳戶。請務必在這個指令中使用正確的專案 ID。
    • PROXY_SA_NAME：proxy 服務帳戶的 ID。
    • RUNTIME_SA_NAME：執行階段服務帳戶的 ID。
  8. 如要部署已設定為使用 Google 驗證機制的 API Proxy，您必須：
    • 您先前建立的Proxy 服務帳戶名稱。例如： PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • 您必須是執行部署的使用者，且已具備或已獲授予 Apigee 機構已佈建的 Google Cloud 專案iam.serviceAccounts.actAs 權限。請參閱「 授予、變更及撤銷資源的存取權」。
  9. 部署含有您實作 Google 驗證設定的 API Proxy。您可以使用 Apigee UI 或 API 部署 Proxy。詳情請參閱「部署 API Proxy」。
    • 如果使用使用者介面，系統會要求您提供服務帳戶名稱。使用先前建立的Proxy 服務帳戶名稱。例如：PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

    • 如果您想使用 Apigee 部署 API 部署 Proxy，請參考以下範例 cURL 指令。請注意，這項指令會將服務帳戶名稱納入查詢參數。這是 proxy 服務帳戶的名稱：
      curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
-H "Content-Type: application/json" -X POST

      其中：

      • TOKEN：您必須取得的 OAuth 權杖，才能換取 Google 憑證。詳情請參閱「取得 OAuth 2.0 存取權杖」。
      • ORG_NAME：您的 Apigee 機構名稱。
      • ENV_NAME：要部署 API Proxy 的環境名稱。
      • PROXY_SA_NAME：Proxy 服務帳戶名稱。
      • PROJECT_ID：您的 Google Cloud 專案 ID (與機構名稱相同)。
  10. 部署作業完成後，請測試 API 代理程式，確認 Google 服務會傳回預期的回應。

關於服務帳戶權限

如要設定 API 代理程式以使用 Google 驗證，您必須建立服務帳戶，如下表所述。另請參閱「 建立及管理服務帳戶」。

服務帳戶 必要條件 說明
Proxy Apigee 和 Apigee Hybrid

具備 API 代理程式向指定 Google 服務發出已驗證呼叫所需的權限。

  • 必須在與 Apigee 機構相同的 Google Cloud 專案中建立。
  • 執行部署作業的使用者 (部署者) 必須具備或已獲授權使用 Proxy Service 帳戶的 iam.serviceAccounts.actAs 權限。
  • 必須包含與特定目標 Google 服務通訊所需的權限。舉例來說，如果您要呼叫 Google 記錄服務，這個服務帳戶必須具備與該服務通訊所需的權限。另請參閱瞭解角色。
  • 部署使用 Google 驗證機制的 Proxy 時，必須提供服務帳戶名稱。
執行階段 僅限 Apigee Hybrid

允許 Apigee 執行階段產生符記，以便在 API Proxy 要求的 Google 服務上進行驗證。這個服務帳戶會「模擬」代理程式專屬的服務帳戶，代表該帳戶發出經過驗證的呼叫。

  • 如要模擬代理服務帳戶並建立符記，執行階段服務帳戶必須獲得代理服務帳戶的 roles/iam.serviceAccountTokenCreator 角色。請參閱「管理服務帳戶的存取權」。