驗證 APIKey 政策

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

查看 Apigee Edge 說明文件。

總覽

您可以使用「驗證 API 金鑰」政策，在執行階段強制驗證 API 金鑰，只允許具有核准 API 金鑰的應用程式存取 API。這項政策可確保 API 金鑰有效、未遭撤銷，且已獲准使用與 API 產品相關聯的特定資源。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

如需教學課程，瞭解如何建構使用「驗證 API 金鑰」政策的 API Proxy，請參閱「要求 API 金鑰來保護 API 安全」。

範例

查詢參數中的鍵

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

在本例中，政策預期會在名為 request.queryparam.apikey 的流程變數中找到 API 金鑰。變數 request.queryparam.{name} 是標準的 Apigee 流程變數，會填入用戶端要求中傳遞的查詢參數值。

下列 curl 指令會以查詢參數形式傳遞 API 金鑰：

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

雖然允許，但一般來說，在查詢參數中傳遞 API 金鑰並非好做法。這是因為查詢參數可能會出現在瀏覽器記錄和網路記錄中，造成潛在的安全風險。較好的做法是將 API 金鑰放在標頭中，這樣就不會出現在記錄檔中。請參閱下一個分頁中的「KEY IN HEADER」範例。

顯示在頁首

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

在本例中，政策預期會在名為 request.header.x-apikey 的流程變數中找到 API 金鑰。變數 request.header.{name} 是標準的 Apigee 流程變數，其中會填入用戶端要求中傳遞的標頭值。

以下 cURL 顯示如何在標頭中傳遞 API 金鑰：

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

建議您在標頭中傳遞 API 金鑰，而非查詢參數。這是因為標頭不會出現在瀏覽器記錄或網路記錄中，可能造成安全風險。

變數中的鍵

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

政策可以參照任何含有金鑰的變數。本範例中的政策會從名為 requestAPIKey.key 的變數中擷取 API 金鑰。

如何填入該變數則由您決定。舉例來說，您可以使用「擷取變數」政策，從名為 myKey 的查詢參數填入 requestAPIKey.key，如下所示：

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

存取權政策流程變數

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

針對有效的 API 金鑰執行「驗證 API 金鑰」政策時，Apigee 會自動填入一組流程變數。您可以使用這些變數存取應用程式名稱、應用程式 ID，以及註冊應用程式的開發人員或公司資訊。在上述範例中，您可以使用「指派訊息」政策，在執行 Verify API 金鑰後存取開發人員的名字、姓氏和電子郵件地址。

這些變數的前置字元都是：

verifyapikey.{policy_name}

在本例中，「驗證 API 金鑰」政策名稱為「verify-api-key」。因此，您可透過存取變數 verifyapikey.verify-api-key.developer.firstName.，參照提出要求的開發人員名字

學習 Apigee

範例： 邊做邊學！
「使用 API 金鑰保護 Proxy」範例會使用 API 金鑰保護 API Proxy，而「 移除 apikey 查詢參數」則說明如何從要求中移除 API 金鑰，避免將金鑰傳遞至後端目標 (最佳做法)。只要複製存放區，然後按照 README 檔案中的操作說明操作即可。

---

關於「驗證 API 金鑰」政策

開發人員在 Apigee 註冊應用程式時，Apigee 會自動產生消費者金鑰和密碼組合。您可以在 Apigee 使用者介面中查看應用程式的消費者金鑰和密鑰配對，也可以透過 Apigee API 存取這些資訊。

注意：API 金鑰有許多名稱，您可能會看到這些金鑰稱為「API 金鑰」、「應用程式金鑰」和「消費者金鑰」。這些名稱都是同義詞。

註冊應用程式時，開發人員會選取一或多個要與應用程式建立關聯的 API 產品，API 產品是可透過 API 代理項存取的一組資源。然後，開發人員會在與應用程式相關聯的 API 產品中，將 API 金鑰 (消費者金鑰) 做為每個 API 要求的其中一部分傳遞。詳情請參閱「發布總覽」。

API 金鑰可用做驗證權杖，或用來取得 OAuth 存取權杖。在 OAuth 中，API 金鑰稱為「用戶端 ID」。這兩個名稱可以互換使用。 詳情請參閱 OAuth 首頁。

執行「驗證 API 金鑰」政策時，Apigee 會自動填入一組流程變數。 詳情請參閱下方的「流程變數」。

元素參照

您可以在這項政策中設定下列元素和屬性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey> 屬性

以下範例顯示 <VerifyAPIKey> 標記的屬性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
name	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設	不適用 如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性	選用
類型	字串

<APIKey> 元素

這個元素會指定包含 API 金鑰的流程變數。一般來說，用戶端會透過查詢參數、HTTP 標頭或表單參數傳送 API 金鑰。舉例來說，如果金鑰是在名為 x-apikey 的標頭中傳送，則金鑰會位於變數 request.header.x-apikey 中。

預設	不適用
存在必要性	必填
類型	字串

屬性

下表說明 <APIKey> 元素的屬性

屬性	說明	預設	存在必要性
ref	內含 API 金鑰的變數參照。每項政策只能有一個位置。	不適用	必填

建議您在標頭或表單參數中傳遞 API 金鑰，而不是在查詢參數中傳遞。這是因為查詢參數可能會出現在瀏覽器記錄和網路記錄中，可能造成安全風險。

範例

在這些範例中，金鑰會透過參數和名為 x-apikey 的標頭傳遞。

做為查詢參數：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

以 HTTP 標頭的形式：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

做為 HTTP 表單參數：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

<CacheExpiryInSeconds> 元素

這個元素會強制執行快取的存留時間，方便您自訂快取存取權杖的到期時間。支援的範圍為 1 到 180 秒。您可以提供流程變數和預設變數。 如果提供流程變數值，系統會優先採用該值，而非指定的預設值。

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

注意：縮短快取間隔會導致效能下降。

預設	不適用 如果省略這個元素，快取存取權杖的預設到期時間為 180 秒。
存在必要性	選用
類型	整數
有效值	任何正整數，不得為零。以秒為單位指定有效期限。

屬性

下表說明 <CacheExpiryInSeconds> 元素的屬性

屬性	說明	預設	存在必要性
ref	流程變數的參照，其中包含以秒為單位的快取到期值。 如果提供流程變數值，系統會優先採用該值，而非指定的預設值。	不適用	選用

結構定義

範例：如需最新結構定義，請參閱 GitHub 存放區範例。

流程變數

當系統對有效的 API 金鑰強制執行「驗證 API 金鑰」政策時，Apigee 會填入一組流程變數。這些變數可供稍後在流程中執行的政策或程式碼使用，且通常用於根據 API 金鑰的屬性 (例如應用程式名稱、用於授權金鑰的 API 產品，或 API 金鑰的自訂屬性) 執行自訂處理作業。

這項政策會填入多種不同類型的流程變數，包括：

• 一般
• 應用程式
• 開發人員
• Analytics
• 營利

每種流程變數都有不同的前置字元。除非特別指出為陣列，否則所有變數都是純量。

一般流程變數

下表列出「驗證 API 金鑰」政策填入的一般流程變數。這些變數的前置字元都是：

verifyapikey.{policy_name}

例如：verifyapikey.{policy_name}.client_id

可用的變數包括：

變數	說明
client_id	要求應用程式提供的消費者金鑰 (又稱 API 金鑰或應用程式金鑰)。
client_secret	與用戶端金鑰相關聯的用戶端密鑰。
redirection_uris	要求中的任何重新導向 URI。
developer.app.id	提出要求的開發人員或AppGroup應用程式的 ID。 注意：請勿將 developer.app.id 變數用於下列任何用途： 配額政策的 ID 鍵/值對應 (KVM) 鍵 傳送至目標的 ID，用於後端商業邏輯 這個 ID 是由 Apigee 內部產生，無法保證長期維持不變。 舉例來說，Apigee 可能會變更這個變數的格式或長度。
developer.app.name	提出要求的開發人員或「AppGroup」AppGroup應用程式的名稱。
developer.id	開發人員或AppGroup的 ID，註冊為要求應用程式的擁有者。 注意：請勿將 developer.id 變數用於下列任何用途： 配額 ID KVM 鍵 傳送至目標的 ID，用於後端商業邏輯 這個 ID 是由 Apigee 內部產生，無法保證長期維持不變。 舉例來說，Apigee 可能會變更這個變數的格式或長度。
developer.{custom_attrib_name}	從應用程式金鑰設定檔衍生的任何自訂屬性。
DisplayName	政策的 <DisplayName> 屬性值。
failed	如果 API 金鑰驗證失敗，請設為「true」。
{custom_app_attrib}	從應用程式設定檔衍生的任何自訂屬性。指定自訂屬性的名稱。
apiproduct.name*	用於驗證要求的 API 產品名稱。
apiproduct.{custom_attrib_name}*	從 API 產品設定檔衍生的任何自訂屬性。
apiproduct.developer.quota.limit*	API 產品設定的配額限制 (如有)。
apiproduct.developer.quota.interval*	API 產品上設定的配額間隔 (如有)。
apiproduct.developer.quota.timeunit*	API 產品上設定的配額時間單位 (如有)。
* 如果 API 產品已設定有效的環境、Proxy 和資源 (衍生自 proxy.pathsuffix)，系統會自動填入 API 產品變數。如需設定 API 產品的操作說明，請參閱「 管理 API 產品」。

應用程式流程變數

政策會填入下列含有應用程式相關資訊的流程變數： 這些變數的前置字元都是：

verifyapikey.{policy_name}.app。

例如：

verifyapikey.{policy_name}.app.name

可用的變數包括：

變數	說明
name	應用程式名稱。
id	應用程式的 ID。
accessType	Apigee 未使用。
callbackUrl	應用程式的回呼網址。通常只用於 OAuth。
DisplayName	應用程式的顯示名稱。
status	應用程式狀態，例如「已核准」或「已撤銷」。
apiproducts	陣列，內含與應用程式相關聯的 API 產品清單。
appFamily	包含該應用程式的任何應用程式系列，或「預設」。
appParentStatus	應用程式父項的狀態，例如「有效」或「無效」
appType	應用程式類型為「開發人員」。
appParentId	父項應用程式的 ID。
created_at	應用程式的建立日期/時間戳記。
created_by	建立應用程式的開發人員電子郵件地址。
last_modified_at	應用程式上次更新的日期/時間戳記。
last_modified_by	上次更新應用程式的開發人員電子郵件地址。
{app_custom_attributes}	任何自訂應用程式屬性。指定自訂屬性的名稱。

AppGroup 流程變數

政策會填入下列含有 AppGroups 相關資訊的流程變數。只有在 verifyapikey.{policy_name}.app.appType 為「AppGroup」時，系統才會填入這些 AppGroup 屬性。

這些變數的前置字元都是：

verifyapikey.{policy_name}.appgroup。

例如：

verifyapikey.{policy_name}.appgroup.name

注意：如果您從 Apigee Edge 遷移，遷移後，公司流程變數會自動顯示在對應的 AppGroup 屬性中。遷移期間，您不需要對套裝組合進行任何變更。

可用的變數包括：

變數	說明
name	AppGroup 的名稱。
id	應用程式群組 ID。 注意：這個 ID 是由 Apigee 內部產生，無法保證長期維持不變。請勿將 appgroup.id 變數用於下列任何用途： 配額 ID KVM 鍵 傳送至目標的 ID，用於後端商業邏輯
displayName	AppGroup 顯示名稱。
appOwnerStatus	應用程式擁有者的狀態：「active」、「inactive」或「login_lock」。
created_at	建立 AppGroup 的日期/時間戳記。
created_by	建立 AppGroup 的開發人員電子郵件地址。
last_modified_at	上次修改 AppGroup 的日期/時間戳記。
last_modified_by	上次修改 AppGroup 的開發人員電子郵件地址。
{appgroup_custom_attributes}	任何自訂 AppGroup 屬性。指定自訂屬性的名稱。

開發人員流程變數

下列含有開發人員資訊的流程變數會由政策填入。這些變數的前置字元都是：

verifyapikey.{policy_name}.developer

例如：

verifyapikey.{policy_name}.developer.id

可用的變數包括：

變數	說明
id	傳回 {org_name}@@@{developer_id}
userName	開發人員的使用者名稱。
firstName	開發人員的名字。
lastName	開發人員的姓氏。
email	開發人員的電子郵件地址。
status	開發人員的狀態，例如有效、無效或登入鎖定。
apps	與開發人員相關聯的應用程式陣列。 注意：如果應用程式數量超過 10 個，存取這個變數會導致延遲時間較長。
created_at	開發人員的建立日期/時間戳記。
created_by	建立開發人員的使用者電子郵件地址。
last_modified_at	開發人員上次修改的日期/時間戳記。
last_modified_by	修改開發人員的使用者電子郵件地址。
{developer_custom_attributes}	任何自訂開發人員屬性。指定自訂屬性的名稱。

Analytics 變數

針對有效的 API 金鑰強制執行「驗證 API 金鑰」政策時，系統會自動在 Analytics 中填入下列變數。這些變數只會由「驗證 API 金鑰」政策和 OAuth 政策填入。

變數和值可用做維度，建立 Analytics 報表，瞭解開發人員和應用程式的用量模式。

• apiproduct.name
• developer.app.name
• client_id
• developer.id

營利流程變數

驗證使用者後，VerifyAPIKey 政策會檢查所有已發布的費率方案，根據啟用和到期時間判斷哪些方案有效。如果系統找到已發布的有效房價方案，就會填入下列流程變數：

變數	說明
mint.mintng_is_apiproduct_monetized	true (如果找到已發布的有效房價方案)。
mint.mintng_rate_plan_id	房價方案 ID。
mint.rateplan_end_time_ms	費率方案的到期時間。例如：1619433556408
mint.rateplan_start_time_ms	房價方案的啟用時間。例如：1618433956209

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼	HTTP 狀態	原因
keymanagement.service.consumer_key_missing_api_product_association	400	應用程式憑證缺少 API 產品關聯。請將金鑰的應用程式與 API 產品建立關聯。請注意，這項規定適用於所有應用程式類型，例如開發人員應用程式和 AppGroup 應用程式。
keymanagement.service.DeveloperStatusNotActive	401	建立含有您使用的 API 金鑰的開發人員應用程式的開發人員處於停用狀態。當應用程式開發人員的狀態設為停用時，該開發人員所建立的任何開發人員應用程式都會停用。具備適當權限的管理員使用者 (例如機構管理員)，可以透過下列方式變更開發人員的狀態： Apigee API： 設定開發人員狀態 Apigee UI：請參閱「註冊應用程式開發人員」中的操作說明，瞭解如何停用 (和啟用) 開發人員。
keymanagement.service.invalid_client-app_not_approved	401	與 API 金鑰相關聯的開發人員應用程式已遭到撤銷。已遭撤銷的應用程式無法存取任何 API 產品，也無法叫用任何由 Apigee 管理的 API。機構管理員可以使用 Apigee API 變更開發人員應用程式的狀態。請參閱「 產生金鑰組或更新開發人員應用程式狀態」一文。
oauth.v2.FailedToResolveAPIKey	401	政策會在政策的 <APIKey> 元素中指定的變數中尋找 API 金鑰。 如果預期的變數不存在 (無法解析)，就會發生此錯誤。
oauth.v2.InvalidApiKey	401	Apigee 已收到 API 金鑰，但該金鑰無效。Apigee 在資料庫中查詢金鑰時，該金鑰必須與要求中傳送的金鑰完全相符。如果 API 先前運作正常，請確認金鑰並未重新產生。如果金鑰已重新產生，嘗試使用舊金鑰時就會看到這則錯誤訊息。詳情請參閱「 註冊應用程式來控管 API 存取權」。
oauth.v2.InvalidApiKeyForGivenResource	401	Apigee 已收到有效的 API 金鑰，但該金鑰與透過產品與 API Proxy 相關聯的開發人員應用程式中核准的金鑰不符。

注意：目前 Apigee 無法準確回報 ApiKeyNotApproved 錯誤。相反地，如果金鑰未獲核准 (其狀態設為 revoked 或 pending)，您會收到 FailedToResolveAPIKey 錯誤。如需更多資訊和可能的解決方法，請參閱「 驗證 API 金鑰未回報 API 金鑰未獲核准」一文。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因
SpecifyValueOrRefApiKey	<APIKey> 元素未指定值或鍵。

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
fault.name="fault_name"	fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。	fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed	policy_name 是擲回錯誤的政策的使用者指定名稱。	oauthV2.VK-VerifyAPIKey.failed = true

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

錯誤規則範例

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>