驗證 APIKey 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

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

這些變數的前置字串如下:

verifyapikey.{policy_name}

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

瞭解邊緣


關於驗證 API 金鑰政策

當開發人員在 Edge 上註冊應用程式時,Edge 會自動產生用戶端金鑰和密鑰配對。您可以在 Edge UI 中查看應用程式的用戶端金鑰和密鑰配對,或是透過 Edge API 存取這些項目。

開發人員在註冊應用程式時,會選取一或多個要與應用程式建立關聯的 API 產品,API 產品是可透過 API Proxy 存取的一系列資源。接著,開發人員會將 API 金鑰 (用戶端金鑰) 當做與應用程式相關聯的 API 產品中,每項要求的一部分傳送至 API。詳情請參閱「發布總覽」。

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

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

元素參照

以下是您可以為這項政策設定的元素和屬性:

<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> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

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

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

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

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<APIKey> 元素

這個元素會指定包含 API 金鑰的流程變數。用戶端通常會透過查詢參數、HTTP 標頭或表單參數傳送 API 金鑰。舉例來說,如果鍵是在名為 x-apikey 的標頭中傳送,那麼索引鍵會存放在變數中:request.header.x-apikey

預設 NA
存在必要性 需要
類型 字串

屬性

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

屬性 說明 預設 存在必要性
參考資料

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

結構定義

流程變數

如果針對有效的 API 金鑰強制執行驗證 API 金鑰政策,Edge 會填入一組流程變數。這些變數可用於政策或稍後在流程中執行的程式碼,且通常用於根據 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 任何含有該應用程式的應用程式系列,或稱「預設」。
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 開發人員的狀態,包括有效、已停用或 login_lock。
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
應用程式擁有者的狀態,包括「active」、「active」或「login_lock」。
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 這項政策預期會在政策 <APIKey> 元素指定的變數中找到 API 金鑰。 當預期的變數不存在時,就會發生這個錯誤 (無法解決)。
oauth.v2.InvalidApiKey 401 Edge 已接收到無效的 API 金鑰。Edge 在資料庫中查詢金鑰時,必須與要求中傳送的 完全相符。如果 API 之前可以運作,請確認金鑰並未重新產生。如果重新產生金鑰,如果您嘗試使用舊金鑰,就會看到這則錯誤訊息。詳情請參閱「註冊應用程式及管理 API 金鑰」。
oauth.v2.InvalidApiKeyForGivenResource 401 Edge 收到且有效的 API 金鑰,但該金鑰與您在某項產品的 API Proxy 中連結至您的 API Proxy 的開發人員應用程式中的核准金鑰不同。

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

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

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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>

相關主題