使用 Google 驗證

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本主題說明如何設定及部署 API Proxy，並將其設定為使用 Google 驗證。

簡介

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

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

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

完成一些基本設定步驟 (如本主題所述) 後，Apigee 會為您產生權杖，並安全地呼叫目標 Google 服務或自訂代管服務，您不必手動設定驗證標頭，也不必修改服務要求。從 API 開發人員的角度來看，在正確設定的 API Proxy 中呼叫 Google 服務的程序，會順暢無礙地完成。

API Proxy 設定選項

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

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

支援 Google Auth 權杖的環境

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

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

部署步驟

本節說明如何部署 API Proxy，透過 Google 驗證呼叫目標 Google 服務或自訂代管服務。我們會分別說明 Apigee 和 Apigee Hybrid 的部署步驟。

在 Apigee 上部署

下列步驟說明如何在 Apigee 上部署 API Proxy，並將 Proxy 設為對 Google 服務或自訂代管服務發出經過驗證的呼叫。這些步驟假設您已建立 Proxy，且 Proxy 在其中一個支援的環境中包含 <Authentication> 元素。

  1. 在建立 Apigee 機構的專案中，建立 Google 服務帳戶。 Google Cloud部署設定為使用 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 Logging 服務，這個服務帳戶必須包含與該服務通訊所需的權限。另請參閱「瞭解角色」。
  4. 部署設定為使用 Google 驗證的 API Proxy 前，請先完成下列事項：
    • 您先前建立的服務帳戶名稱。例如： SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • 身為執行部署作業的使用者 (部署者)，您必須已具備或獲授服務帳戶的 iam.serviceAccounts.actAs 權限。請參閱「授予、變更及撤銷資源的存取權」。
  5. 部署您實作的 API Proxy，其中包含 Google 驗證設定。您可以使用 Apigee 使用者介面或 API 部署 Proxy。詳情請參閱「部署 API 代理」。
    • 如果使用 UI，系統會要求您提供服務帳戶名稱。使用您在步驟 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：您必須以 Google 憑證換取的 OAuth 權杖。詳情請參閱「取得 OAuth 2.0 存取權杖」。
      • ORG_NAME：您的 Apigee 機構名稱。
      • ENV_NAME：要將 API Proxy 部署至的環境名稱。
      • SA_NAME：建立服務帳戶時提供的名稱。
      • PROJECT_ID：您的 Google Cloud 專案 ID (與機構名稱相同)。
  6. 部署完成後，請測試 API Proxy，確認 Google 服務傳回預期回應。

在 Apigee Hybrid 上部署

下列步驟說明如何將 API Proxy 部署至 Apigee Hybrid，並設定該 Proxy 向 Google 服務發出已驗證的呼叫。這些步驟假設您已建立 Proxy，且 Proxy 在其中一個支援的環境中包含 <Authentication> 元素。

  1. 使用下列其中一種方法，為 Apigee Hybrid 執行階段元件建立服務帳戶和金鑰：
    • 使用 Apigee Hybrid 隨附的 create-service-account 工具建立 apigee-runtime 服務帳戶。這項工具會建立服務帳戶，並傳回服務帳戶金鑰。詳情請參閱「create-service-account」。
    • 在 Google Cloud 控制台中建立服務帳戶，或使用 gcloud 指令。請參閱「建立及管理服務帳戶」。 如要擷取服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。
    Google Cloud
  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 Logging 服務，這個服務帳戶必須包含與該服務通訊所需的權限。另請參閱「瞭解角色」。
  7. 請確保執行階段可以模擬 Proxy 服務帳戶。如要提供這項功能，請在 Proxy 服務帳戶中，將 iam.serviceAccountTokenCreator 角色授予執行階段服務帳戶。另請參閱服務帳戶權限簡介。例如： 
    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. 部署您實作的 API Proxy，其中包含 Google 驗證設定。您可以使用 Apigee 使用者介面或 API 部署 Proxy。詳情請參閱「部署 API 代理」。
    • 如果使用 UI，系統會要求您提供服務帳戶名稱。使用您先前建立的 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：您必須以 Google 憑證換取的 OAuth 權杖。詳情請參閱「取得 OAuth 2.0 存取權杖」。
      • ORG_NAME：您的 Apigee 機構名稱。
      • ENV_NAME：要將 API Proxy 部署至的環境名稱。
      • PROXY_SA_NAME：Proxy 服務帳戶的名稱。
      • PROJECT_ID：您的 Google Cloud 專案 ID (與機構名稱相同)。
  10. 部署完成後，請測試 API Proxy，確認 Google 服務傳回預期回應。

關於服務帳戶權限

如要設定 API 代理程式以使用 Google 驗證，請按照下表說明建立服務帳戶。 另請參閱「 建立及管理服務帳戶」。

服務帳戶 適用於 說明
Proxy Apigee 和 Apigee Hybrid

具備 API Proxy 向目標 Google 服務發出已驗證呼叫所需的權限。

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

允許 Apigee 執行階段產生權杖，以驗證 API Proxy 所要求的 Google 服務。這個服務帳戶會「模擬」Proxy 專屬服務帳戶，代表該帳戶發出經過驗證的呼叫。

  • 如要模擬 proxy 服務帳戶並建立權杖，必須在 proxy 服務帳戶上授予 runtime 服務帳戶 roles/iam.serviceAccountTokenCreator 角色。 請參閱「管理服務帳戶的存取權」。