驗證 APIKey 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件
info

結果

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

範例

查詢參數中的鍵

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

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

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

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

顯示在頁首

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

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

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

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

變數中的鍵

<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 金鑰」政策時,Edge 會自動填入一組流程變數。您可以使用這些變數存取應用程式名稱、應用程式 ID,以及註冊應用程式的開發人員或公司資訊。在上述範例中,您可以使用「指派訊息」政策,在執行 Verify API 金鑰後存取開發人員的名字、姓氏和電子郵件地址。

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

verifyapikey.{policy_name}

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

瞭解 Edge


關於「驗證 API 金鑰」政策

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

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

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

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

元素參照

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

<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"/>
</VerifyAPIKey>

<VerifyAPIKey> 屬性

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

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

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

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素,為政策加上標籤: 管理使用者介面 Proxy 編輯器,使用不同的自然語言名稱。

不適用 必填
continueOnError

如果設為「false」,系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true,即使政策已發生,流程執行作業仍會繼續執行 失敗。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

&lt;DisplayName&gt;元素

name 屬性外,一併使用 管理 UI Proxy 編輯器,使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,政策的 name 屬性值會是

存在必要性 選用
類型 字串

<APIKey> 元素

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

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

屬性

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

屬性 說明 預設 存在必要性
ref

內含 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>

結構定義

流程變數

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

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

  • 一般
  • 應用程式
  • 開發人員
  • 公司
  • Analytics

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

一般流程變數

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

verifyapikey.{policy_name}

例如:verifyapikey.{policy_name}.client_id

可用的變數包括:

變數 說明
client_id 要求應用程式提供的消費者金鑰 (又稱 API 金鑰或應用程式金鑰)。
client_secret 與用戶端金鑰相關聯的用戶端密鑰。
redirection_uris 要求中的任何重新導向 URI。
developer.app.id

提出要求的開發人員應用程式 ID。

developer.app.name 提出要求的開發人員應用程式名稱。
developer.id

註冊為要求應用程式擁有者的開發人員 ID。

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 產品的說明,請參閱「使用 Edge Management API 發布 API」。

應用程式流程變數

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

verifyapikey.{policy_name}.app

例如:

verifyapikey.{policy_name}.app.name

可用的變數包括:

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

開發人員流程變數

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

verifyapikey.{policy_name}.developer

例如:

verifyapikey.{policy_name}.developer.id

可用的變數包括:

變數 說明
id 傳回 {org_name}@@@{developer_id}
userName 開發人員的使用者名稱。
firstName 開發人員的名字。
lastName 開發人員的姓氏。
email 開發人員的電子郵件地址。
status 開發人員的狀態,例如有效、無效或登入鎖定。
apps 與開發人員相關聯的應用程式陣列。
created_at 開發人員的建立日期/時間戳記。
created_by 建立開發人員的使用者電子郵件地址。
last_modified_at 開發人員上次修改的日期/時間戳記。
last_modified_by 修改開發人員的使用者電子郵件地址。
{developer_custom_attributes} 任何自訂開發人員屬性。指定自訂屬性的名稱。
Company 與開發人員相關聯的公司名稱 (如有)。

公司流程變數

下列包含公司資訊的流程變數是由政策填入。這些變數的前置字元都是:

verifyapikey.{policy_name}.company

例如:

verifyapikey.{policy_name}.company.name

可用的變數包括:

變數 說明
name 公司名稱。
displayName 公司顯示名稱。
id

公司 ID。

apps 包含公司應用程式清單的陣列。
appOwnerStatus
應用程式擁有者的狀態,例如有效、無效或登入鎖定。
created_at 公司建立的日期/時間戳記。
created_by 建立公司的使用者電子郵件地址。
last_modified_at 公司上次修改的日期/時間戳記。
last_modified_by 最後修改公司的使用者電子郵件地址。
{company_custom_attributes} 任何自訂公司屬性。指定自訂屬性的名稱。

Analytics 變數

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

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

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

錯誤參考資料

本節說明在這項政策觸發錯誤時,所傳回的錯誤代碼和錯誤訊息,以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊,以便瞭解您是否要擬定錯誤規則, 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤處理方式 發生錯誤

執行階段錯誤

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

錯誤程式碼 HTTP 狀態 原因
keymanagement.service.CompanyStatusNotActive 401 如果與開發人員應用程式相關聯的公司,且擁有您使用的 API 金鑰,則有 停用狀態。公司狀態一旦設為「已停用」,就無法 開發人員或與該公司相關聯的應用程式機構組織管理員可以變更公司狀態 Management API請參閱設定狀態 某公司
keymanagement.service.DeveloperStatusNotActive 401

建立開發人員應用程式,且擁有您所使用的 API 金鑰的開發人員 處於無效狀態。如果應用程式開發人員的狀態設為「已停用」,所有開發人員應用程式 由該開發人員建立。具備適當權限的管理員使用者 (例如機構管理員) 可以在下列位置變更開發人員狀態 方式:

keymanagement.service.invalid_client-app_not_approved 401 與 API 金鑰相關聯的開發人員應用程式已撤銷。已撤銷的應用程式無法 存取任何 API 產品,且無法叫用 Apigee Edge 管理的任何 API。機構管理員可以 使用 Management API 變更開發人員應用程式的狀態。詳情請參閱 核准或撤銷開發人員應用程式
oauth.v2.FailedToResolveAPIKey 401 這項政策預期在政策 &lt;APIKey&gt; 元素 這個錯誤會在預期 變數不存在 (無法解析)。
oauth.v2.InvalidApiKey 401 Edge 收到的 API 金鑰無效。Edge 查詢 資料庫必須與要求中傳送的 完全相符。如果 API 運作正常 請確保該金鑰並未重新產生。如果金鑰重新產生,您會看到 這項錯誤。詳情請參閱「註冊應用程式及管理 API 金鑰
oauth.v2.InvalidApiKeyForGivenResource 401 由 Edge 接收的 API 金鑰有效;不過,不得與 在透過「產品」與您的 API Proxy 相關聯的開發人員應用程式中,取得已核准的金鑰。

部署錯誤

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

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

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。

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

錯誤回應範例

{  
   "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>

相關主題