以 IAM 為基礎的 API 驗證總覽

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

Apigee 支援 API Proxy 的 IAM 驗證和授權。如要使用這項功能，請在 Proxy 的要求流程中加入 VerifyIAM 政策，並設定 API 消費者的使用者 ID (通常是電子郵件地址)，確保他們具備必要的 Google Cloud IAM 角色或權限，可叫用 Apigee API。API 要求應傳遞該使用者的有效 Google Cloud 存取權杖。

管理員可以將授權授予任何Google Cloud 主體，而不僅限於個別使用者。

使用以 IAM 為基礎的存取權控管機制

本節說明設定以 IAM 為基礎的驗證和授權作業的完整流程、存取權設定完成後如何評估要求，以及如何撤銷先前具有存取權的 API 消費者存取權。

新增存取權管理

如要設定 API Proxy 的存取權管理，請按照下列步驟操作：

  1. 將 VerifyIAM 政策新增至 Apigee API Proxy，或新增至要求流程中的 Proxy。
  2. Apigee 專案的 Cloud 管理員：
    1. 授予專案層級的 deploymentInvoker IAM 角色 (或具有 apigee.deployments.invoke IAM 權限的自訂角色) 給 API 消費者的 Google Cloud 主體。API 消費者即可透過這個存取權，叫用相關聯 Apigee 機構中的所有代管 API。

      或

    2. 使用 SetIamPolicy 動作，在特定部署作業中，或在多項部署作業中以疊代方式，將角色或權限授予 API 消費者的 Google Cloud 主體。在部署資源上使用清單作業，即可查看環境中的所有部署項目，包括 API Proxy 和共用流程。部署作業的名稱是 API Proxy 或共用流程的名稱。
  3. 引導 API 消費者產生存取權杖，並在 Apigee API 要求中傳遞該權杖，以進行權限檢查。產生的權杖必須具有 https://www.googleapis.com/auth/cloud-platform 授權範圍。

管理作業

本節列出 API 管理員 (API 製作人) 在管理 IAM 權限時執行的動作。

如要瞭解管理 IAM 存取權時使用的 API 作業，請參閱 organizations.environments 和 organizations.environments.deployments API 參考說明文件，包括 SetIamPolicy、GetIamPolicy、TestIamPermissions 和 GetDeployment 作業。

下表將作業對應至必要權限：

管理員作業 動作 所需 IAM 權限 需要權限的 IAM 資源*
GetDeployment 擷取 Apigee 環境中部署作業的相關資訊 apigee.deployments.get Google Cloud 專案或 Apigee 環境
ListDeployments 列出 Apigee 環境中的部署作業 apigee.deployments.list 專案或 Apigee 環境
SetIamPolicy 在特定 API 部署作業中，為 API 消費者設定叫用存取權 apigee.deployments.setIamPolicy Google Cloud 專案或 Apigee 環境
GetIamPolicy 擷取 API 部署作業的一組叫用存取權設定 apigee.deployments.getIamPolicy Google Cloud 專案或 Apigee 環境
TestIamPermissions 檢查呼叫此 API 的使用者是否具備酬載中提及的權限 不需要 IAM 權限 不適用
* Google Cloud 專案是用於佈建 Apigee 的專案。Apigee 環境層級權限是在環境中，使用 setIAMPolicy 設定。

執行階段存取權檢查

當 API 消費者嘗試透過以 IAM 為主的存取控管機制存取 API 時，系統會檢查他們是否具備必要的存取權杖，以及專案或部署層級的適當角色或權限。如果是，他們就能繼續存取 Proxy。否則會遭到封鎖。

移除存取權限

如要在專案層級移除存取權：如要移除在專案層級管理 API 消費者的存取權，Apigee 專案的 Cloud 管理員須從 API 消費者的 Google Cloud 主體 Google Cloud 撤銷deploymentInvoker IAM 角色 (或具有 apigee.deployments.invoke IAM 權限的自訂角色)。

如果使用 setIamPolicy 為個別部署項目授予存取權，請使用其他 setIamPolicy 作業，從部署項目中移除角色或權限。

以 IAM 為基礎的存取權控管特性和限制

使用以 IAM 為主的驗證和授權時，請注意下列特性和限制：

  • 一般來說，使用 VerifyIAM 執行政策需要 10 到 50 毫秒。不過，部分通話可能會出現較長的延遲時間。舉例來說，在 asia-east2 區域，平均延遲時間可能會增加至 50 毫秒，部分呼叫可能需要約 100 毫秒才能完成。

    請注意，這些延遲數據僅供參考，我們不對此數據做任何保證。

  • 納入 Proxy 的 VerifyIAM 政策僅為已驗證/未驗證檢查；API 消費者的特定角色和權限不會在要求或回應流程的後續程序中考量。
  • 由於系統只會在執行 VerifyIAM 政策時進行授權檢查，因此在要求流程中，VerifyIAM 應是第一個政策，僅次於流量管理政策。
  • 如果權限驗證成功，或 API 產生器已將 VerifyIAM 政策標示為在發生錯誤時繼續執行，要求流程會繼續執行其他政策 (如有)，最終抵達目標伺服器。如果權限檢查失敗，且 API 生產者未將政策標示為在發生錯誤時繼續執行，使用者就會收到錯誤訊息。
  • 在環境層級新增叫用存取權 (apigee.deployments.invoke)，不會將叫用存取權傳達至環境中的所有 API 部署作業。
  • 部署資源不支援 IAM 條件，因此無法用來控管叫用存取權。詳情請參閱「在政策中新增 Apigee IAM 條件」。
  • 以 IAM 為主的存取權控管在單一政策中最多支援 1,500 個角色繫結，且有其他限制。請參閱 IAM 配額與限制。
  • 以 IAM 為基礎的存取權控管會受到 IAM 傳播延遲影響。
  • 嘗試管理其他 apigee.deployments 作業 (例如透過部署層級的 setIAMPolicy apigee.deployments.delete)，不會生效，但也不會傳回錯誤。只有 apigee.deployements.invoke 會生效。
  • 從環境中取消部署或刪除對應的 Proxy 時，系統會刪除部署作業的存取權；重新部署時，必須重新新增存取權。
  • 目前混合式環境不支援以 IAM 為基礎的驗證和授權。

範例

本節提供授予及撤銷 API 的 IAM 存取權範例。這些範例都假設 VerifyIAM 已新增至適當的 API 代理項目。

在這些範例中，請使用 Cloud 控制台或 gcloud (如下所示)，在 API 消費者的 Google Cloud 主體上管理角色或權限。

授予及撤銷使用者在 Apigee 機構中呼叫所有 API 的權限

如要新增存取權，請新增 deploymentInvoker 角色：

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

如要撤銷存取權，請移除 deploymentInvoker 角色：

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

授予及撤銷使用者對環境中特定部署作業的存取權

如要為特定部署作業的單一使用者新增呼叫者角色，請按照下列步驟操作：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
          "user:'"$USER"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

成功的回應應如下所示：

{
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user-email@example.com"
        ]
      }
    ]
  }

如要為多位使用者新增特定部署作業的呼叫者角色，請執行下列操作：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

如要查詢先前設定的政策物件：

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

您應該會看到如上所示的成功回應。

使用者可以驗證是否能存取指定部署作業 (使用者是否在指定部署作業中設定 apigee.deployments.invoke 權限)，而不必直接叫用已部署的 API。如要這麼做，使用者可以 使用產生的存取權杖提交這項要求：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

回應應包含使用者的 apigee.deployments.invoke 權限。

如要撤銷單一使用者對特定部署作業的存取權，請移除該使用者的 deploymentInvoker 角色。如要這麼做，請先取得目前與部署作業相關聯的政策物件： 

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

成功的回應應如下所示。

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

如要移除單一使用者的繫結，請使用 setIamPolicy，並在酬載中指定應繼續擁有存取權的使用者，就像為這些使用者設定初始存取權時一樣。以上述範例為例，如要移除 USER1 的存取權，但保留 USER2 和 USER3 的存取權，請使用下列指令：

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

如要移除特定部署作業中所有使用者的繫結，請指定空白酬載：

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{}'

如要確認繫結已移除，請確保部署作業中沒有使用者的apigee.deployments.invoke權限：

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

這項作業應會傳回適當的回應，例如如果沒有任何使用者具備呼叫 API 的權限，則傳回空白輸出內容。