要求 API 金鑰來保護 API

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

課程內容

透過本教學課程,您可以瞭解下列主題:

  • 建立需要 API 金鑰的 API Proxy。
  • 新增 API 產品。
  • 新增開發人員並註冊應用程式。
  • 使用 API 金鑰呼叫 API。

請務必妥善保護您的 API,防範未經授權的存取行為。其中一個方法是使用 API 金鑰 (也稱為「公開金鑰」、「用戶端金鑰」或「應用程式金鑰」)。

當應用程式向您的 API 發出要求時,應用程式必須提供有效的金鑰。在執行階段,「Verify API 金鑰」政策會檢查提供的 API 金鑰:

  • 有效
  • 尚未撤銷
  • 針對會公開所要求資源的 API 產品,比對其 API 金鑰

如果金鑰有效,要求即會允許。如果金鑰無效,要求會導致授權失敗。

在這個教學課程中,您會建立需要有效 API 金鑰才能存取的 API Proxy。

軟硬體需求

  • Apigee Edge 帳戶。如果沒有 Apigee Edge 帳戶,可以按照 建立 Apigee Edge 帳戶中的操作說明進行註冊。
  • 進行 API 呼叫的網路瀏覽器。
  • (如需額外的抵免額部分,並非必要) 在您的機器上安裝 cURL,即可透過指令列進行 API 呼叫。

建立 API Proxy

關於「模擬目標」

mocktarget 服務由 Apigee 託管,並傳回簡單資料。不需要 API 金鑰或存取權杖。事實上,您可以透過網路瀏覽器存取。請點選下列按鈕來試用:

http://mocktarget.apigee.net

目標會傳回 Hello, Guest!。使用 /help 資源取得其他可用 API 資源的說明頁面

  1. 前往 https://apigee.com/edge 並登入。
  2. 按一下側邊導覽列頂端的使用者名稱以顯示使用者設定檔選單,然後從清單中選取機構,即可切換至所需機構。

    選取使用者設定檔選單中的機構
  3. 按一下到達網頁中的「API Proxy」,顯示 API Proxy 清單。

    Edge API 選單
  4. 按一下「+ Proxy」
    「建立 Proxy」按鈕
  5. 在「建立 Proxy」頁面上,選取「反向 Proxy (最常用)」
  6. 在「Proxy Details」頁面上,按照下列方式設定 Proxy:
    這個欄位中 採取行動
    Proxy 名稱 輸入:helloworld_apikey
    專案基本路徑

    變更為:/helloapikey

    專案基本路徑是網址的一部分,用於向 API Proxy 提出要求。

    附註:如需 Apigee 的 API 版本管理建議,請參閱《Web API Design: The Missing Link》(網路 API 設計:遺漏的連結) 中的「 版本管理」一節。

    現有 API

    輸入:http://mocktarget.apigee.net

    這會定義 Apigee Edge 針對傳送至 API Proxy 的要求叫用的目標網址。

    說明 輸入:hello world protected by API key
  7. 按一下「Next」
  8. 在「常用政策」頁面的「安全性:授權」部分,選取「API 金鑰」,然後點選「下一步」。這項操作會在您的 API Proxy 中新增兩項政策。
  9. 在「Virtual Hosts」頁面上,選取「default」和「secure」,然後點選「Next」。選取 default 後,您可以使用 http:// 呼叫 API。選取「安全」後,您就能使用 https:// 呼叫 API。
  10. 在「Summary」頁面上,確定已選取「test」部署環境,然後按一下「Create and deploy」
  11. 您會看到通知訊息,確認已成功建立新的 API Proxy 和 API 產品,而且 API Proxy 已部署至測試環境。
  12. 按一下「編輯 Proxy」,顯示 API Proxy 的「總覽」頁面。

查看政策

  1. 在 API Proxy 編輯器中,按一下「Develop」分頁標籤。接著,您會發現以下兩項政策已新增至 API Proxy 的要求流程:
    • 驗證 API 金鑰:檢查 API 呼叫,確認已使用有效的 API 金鑰 (做為查詢參數傳送)。
    • Remove Query Param apikey: AssignMessage 政策會在勾選後移除 API 金鑰,以免在不必要的情況下遭到傳遞及公開。
  2. 按一下流程檢視畫面中的「驗證 API 金鑰」政策圖示,然後在較低的程式碼檢視畫面中查看政策的 XML 設定。<APIKey> 元素會說明政策在發出呼叫時,應在哪個位置尋找 API 金鑰。根據預設,它會在 HTTP 要求中,將金鑰視為名為 apikey 的查詢參數:

    <APIKey ref="request.queryparam.apikey" />
    

    apikey 是任意名稱,可以是包含 API 金鑰的任何屬性。

嘗試呼叫 API

在這個步驟中,您將成功直接對目標服務發出 API 呼叫,接著將成功呼叫 API Proxy,查看政策是否受到政策保護。

  1. 成功

    在網路瀏覽器中,前往下列網址。這是 API Proxy 已設為將要求轉送至這個目標服務,但您暫時將直接點選這項服務:

    http://mocktarget.apigee.net
    

    您應該會收到以下成功回應:Hello, Guest!

  2. 失敗

    現在嘗試呼叫 API Proxy:

    http://ORG_NAME-test.apigee.net/helloapikey
    

    ORG_NAME 替換為 Edge 機構的名稱。

    如果沒有驗證 API 金鑰政策,這項呼叫會給您與先前的呼叫相同的回應。但在這種情況下,您應該會得到下列錯誤回應:

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
    

    這表示您沒有傳送有效的 API 金鑰 (做為查詢參數)。

在後續步驟中,您將新增 API 產品。

新增 API 產品

如要透過 Apigee UI 新增 API 產品,請按照下列步驟操作:

  1. 依序選取「發布」>「API 產品」
  2. 按一下「+API 產品」
  3. 輸入 API 產品的「產品詳細資料」

    欄位 說明
    名稱 API 產品的內部名稱。請勿在名稱中指定特殊字元。
    注意:API 產品建立後,就無法再編輯名稱。例如:helloworld_apikey-Product
    顯示名稱 API 產品的顯示名稱。UI 會使用這個顯示名稱,您隨時可以編輯。如未指定,系統會使用「Name」值。這個欄位會自動填入「名稱」值,您可以編輯或刪除其中的內容。顯示名稱可包含特殊字元。例如:helloworld_apikey-Product
    說明 API 產品的說明。例如 Test product for tutorial
    環境 API 產品允許存取的環境。 例如 testprod
    存取權 選取「公開」
    自動核准存取要求 啟用自動核准從任何應用程式對這個 API 產品提出的金鑰要求。
    配額 略過本教學課程。
    允許的 OAuth 範圍 略過本教學課程。
  4. 在 API 資源專區中,選取您剛建立的 API Proxy。例如 helloworld_apikey
  5. 按一下 [新增]。
  6. 在「Paths」區段中,新增路徑「/」。
  7. 按一下 [新增]。
  8. 點按「儲存」

在後續步驟中,您會取得必要的 API 金鑰。

在貴機構中新增開發人員和應用程式

接著,我們要模擬開發人員申請使用您的 API 時的工作流程。開發人員會有一或多個呼叫您的 API 的應用程式,每個應用程式都會獲得專屬的 API 金鑰。如此一來,API 供應商就能更精細地控管 API 存取權,並針對每個應用程式製作更精細的 API 流量報表。

建立開發人員

如何建立開發人員:

  1. 在選單中依序選取「發布」>「開發人員」
  2. 按一下「+ 開發人員」
  3. 在「New Developer」視窗中輸入以下內容:

    這個欄位中 輸入
    名字 Keyser
    姓氏 Soze
    使用者名稱 keyser
    電子郵件 keyser@example.com
  4. 點選「建立」

註冊應用程式

如何註冊開發人員應用程式:

  1. 依序選取「發布」>「應用程式」
  2. 按一下「+ 應用程式」
  3. 在「New App」視窗中輸入以下內容:

    p 鍵
    這個欄位中 採取行動
    名稱顯示名稱 輸入:keyser_app
    公司 / 開發人員 選取:Developer
    開發人員 選取:Keyser Soze (keyser@example.com)
    回呼網址備註 留空
  4. 在「Credentials」區段中,從「Expiry」選單中選取「Never」。這個應用程式的憑證永遠不會過期。
  5. 按一下「產品」下方的「新增產品」
  6. 選取「helloworld_apikey-Product」
  7. 按一下 [新增]。
  8. 按一下「App Details」部分右側的「Create」即可儲存工作。

取得 API 金鑰

取得 API 金鑰的方法如下:

  1. 在「應用程式」頁面 (依序點選「發布」>「應用程式」) 上,按一下 keyser_app
  2. 在「keyser_app」keyser_app頁面的「Credentials」keyser_app區段中,按一下「Key」keyser_app旁邊的「Show」keyser_app。在「產品」區段中,留意金鑰與 helloworld_apikey 相關聯

    .
  3. 選取並複製金鑰。您將在下一個步驟中使用。

使用金鑰呼叫 API

您已取得 API 金鑰,可以用來呼叫 API Proxy。請在網路瀏覽器中輸入以下內容。請將 ORG_NAME 和下方的 API_KEY 替換成您的 Edge 機構名稱。請確認查詢參數中沒有任何多餘的空格。

http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY

現在當您呼叫 API Proxy 時,應該會收到以下回應:Hello, Guest!

恭喜!您建立了 API Proxy,並要求在呼叫中加入有效的 API 金鑰,藉此保護該 Proxy。

請注意,一般來說,最好不要將 API 金鑰做為查詢參數傳遞。建議您 改為透過 HTTP 標頭傳遞

最佳做法:將金鑰傳入 HTTP 標頭

在這個步驟中,您將修改 Proxy,以便在名為 x-apikey 的標頭中尋找 API 金鑰。

  1. 編輯 API Proxy。依序選取「Develop」>「API Proxies」>「helloworld_apikey」,然後前往「Develop」(開發) 檢視畫面。
  2. 選取「Verify API Key」(驗證 API 金鑰) 政策,然後修改政策 XML,讓政策在 header 中尋找,而不是在 queryparam

    <APIKey ref="request.header.x-apikey"/>
    
  3. 儲存 API Proxy 以部署變更。
  4. 使用 cURL 進行下列 API 呼叫,將 API 金鑰做為名為 x-apikey 的標頭傳遞。別忘了替換貴機構名稱。

    curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
    

請注意,為了完全完成變更,您也必須設定 AssignMessage 政策來移除標頭,而不是查詢參數。 例如:

<Remove>
<Headers>
    <Header name="x-apikey"/>
</Headers>
</Remove>

相關主題

以下是與本教學課程直接相關的幾個主題:

更深入地說,使用 API 金鑰保護 API 只是故事的一部分。API 保護往往需要額外的安全防護,例如 OAuth。

「OAuth」OAuth是一種開放式通訊協定,可在整個殼層中交換存取權杖的憑證 (例如使用者名稱和密碼)。存取權杖是冗長的隨機字串,即使是在應用程式之間傳遞,也能在訊息管道中傳遞,而且不會影響原始憑證。存取權杖通常效期有限,因此一律會產生新的權杖。