以 IAM 為基礎的 API 驗證總覽

本頁面適用於 Apigee，但不適用於 Apigee Hybrid。

Apigee 支援 API Proxy 的 IAM 驗證和授權機制。如要使用這項功能，請在 Proxy 的要求流程中加入 VerifyIAM 政策，並設定 API 使用者的使用者 ID (通常是電子郵件地址)，讓他們擁有呼叫 Apigee API 所需的 Google Cloud IAM 角色或權限。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 principle。您可以使用部署資源的清單作業，查看環境中的所有部署作業，包括 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 的專案。使用 setIAMPolicy 時，Apigee 會在環境中設定環境層級權限。

執行階段存取權檢查

API 使用者嘗試存取採用 IAM 存取控管機制的 API 時，系統會執行檢查，確認他們是否在專案或部署層級具備必要的存取權杖，以及適當的角色或權限。如果是，則可繼續存取 Proxy。否則會遭到封鎖。

移除存取權限

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

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

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

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

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

    請注意，我們不保證這些延遲時間數據。

  • 在 Proxy 中加入 VerifyIAM 政策，只會進行已驗證/未驗證檢查；在要求或回應流程中的後續程序中，不會考量 API 使用者的特定角色和權限。
  • 由於只有在執行 VerifyIAM 政策時才會執行授權檢查，因此 VerifyIAM 應是要求流程中的第一個政策，僅在流量管理政策之後。
  • 如果權限驗證成功，或是 API 製作者已將 VerifyIAM 政策標示為在發生錯誤時繼續執行，要求流程就會繼續執行其他政策 (如有)，最終會傳送至目標伺服器。如果權限檢查失敗，且 API 供應者未將政策標示為在發生錯誤時繼續執行，使用者就會收到錯誤訊息。
  • 在環境層級新增叫用權限 (apigee.deployments.invoke) 不會傳達環境中所有 API 部署的叫用權限。
  • 部署資源不支援身分與存取權管理條件，因此無法用於控制叫用存取權。詳情請參閱「在政策中加入 Apigee IAM 限制條件」。
  • 以 IAM 為主的存取權控管最多可在單一政策中繫結 1,500 個角色，並設有其他限制。請參閱身分與存取權管理配額與限制。
  • 以 IAM 為基礎的存取權控管會受到 IAM 傳播延遲的影響。
  • 嘗試透過部署層級的 setIAMPolicy 管理其他 apigee.deployments 作業 (例如 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 的權限，則會傳回空白的輸出內容。