要求 API 金鑰來保護 API

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

查看 Apigee Edge 說明文件。

注意：這部影片是使用舊版 Apigee UI 錄製，但概念仍然適用。

影片：歡迎觀看這部短片，瞭解如何保護 API 安全。

課程內容

本教學課程說明如何：

• 建立需要 API 金鑰的 API Proxy。
• 建立 API 產品、開發人員和開發人員應用程式。
• 使用 API 金鑰呼叫 API。

請務必保護 API，防止他人在未經授權的情況下擅自存取。其中一種方式是使用 API 金鑰。

如果應用程式向設定為驗證 API 金鑰的 API Proxy 提出要求，就必須提供有效金鑰。在執行階段，Verify API Key 政策會檢查提供的 API 金鑰是否符合下列條件：

• 有效
• 未遭撤銷
• 與公開所要求資源的 API 產品 API 金鑰相符

如果金鑰有效，系統就會允許要求。如果金鑰無效，要求會導致授權失敗。

注意：如要完成本教學課程，您將建立及部署使用 可擴充政策與標準政策的 Proxy。

建立 API Proxy

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往「Proxy development」>「API proxies」頁面。

   前往 API Proxy

2. 在 Google Cloud 窗格的專案挑選器中選取機構。機構名稱與 Google Cloud 專案名稱相同。
3. 點選「+ 建立」。
4. 在「建立 Proxy」窗格的「Proxy 範本」下方，選取「反向 Proxy (最常見)」。反向 Proxy 會將傳入流量轉送至後端服務。
5. 設定 Proxy 的步驟如下：
   

   名稱	值
   Proxy 名稱	helloworld_apikey
   基本路徑	/helloapikey 專案基本路徑是網址的一部分，用於向 API 代理發出要求。
   說明	hello world protected by API key
   目標 (現有 API)	http://mocktarget.apigee.net 這會定義 Apigee 在對 API Proxy 發出要求時叫用的目標網址。這個目標只會回傳簡單的回應：Hello, Guest!。

6. 點選「下一步」。
7. 部署 (選用)。請將這些欄位留空。
8. 點選「建立」。
9. Apigee 會建立新的 Proxy，並在「Proxy summary」窗格中顯示 Proxy 詳細資料摘要。

傳統版 UI

1. 前往 Apigee UI 並登入。
2. 使用使用者介面左上角的下拉式選單選取機構。

3. 依序點選「Develop」>「API Proxies」，顯示 API Proxy 清單。

4. 按一下「建立新項目」。
   
5. 在「Build a Proxy」精靈中，選取「Reverse proxy (most common)」(反向 Proxy (最常見))。
6. 設定 Proxy 的步驟如下：
   

   在這個欄位中	請按照下列步驟操作
   Proxy 名稱	輸入：helloworld_apikey
   專案基本路徑	變更為：/helloapikey 專案基本路徑是網址的一部分，用於向 API 代理發出要求。
   說明	輸入：hello world protected by API key
   目標 (現有 API)	輸入：http://mocktarget.apigee.net 這會定義 Apigee 在對 API Proxy 發出要求時叫用的目標網址。這個目標只會回傳簡單的回應：Hello, Guest!。

7. 點選「下一步」。
8. 在「通用政策」頁面上，選取「API 金鑰」。 這個選項會自動在 API 代理中新增兩項政策，並建立產生 API 金鑰所需的 API 產品。
9. 點選「下一步」。
10. 在「摘要」頁面中，確認已選取部署環境，然後按一下「建立並部署」。
11. 按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。

查看政策

Cloud 控制台中的 Apigee

1. 在「helloworld_apikey」Proxy 的「Proxy summary」(Proxy 摘要) 窗格中，按一下「Develop」(開發) 分頁標籤。
2. 在「政策」選單中，按一下 「新增政策」。
3. 在「建立政策」窗格中，選取「安全性」下方的「驗證 API 金鑰」。
4. 在「Verify API Key」(驗證 API 金鑰) 窗格中，使用下列值填寫「Name」(名稱) 和「Display name」(顯示名稱) 區段中的必填欄位：
   • 名稱：輸入政策名稱。例如：VerifyAPIKey。
   • 顯示名稱：輸入要在使用者介面中使用的政策名稱。例如：Verify API Key。
5. 點選「建立」。
6. 按一下 即可新增其他政策。
7. 在「建立政策」窗格的「中介服務」下方，選取「指派訊息」。
8. 在「Assign Message」窗格中，使用下列值填妥「Name」和「Display name」區段中的必填欄位：
   • 名稱：輸入政策名稱。例如：AssignMessage。
   • 顯示名稱：輸入要在使用者介面中使用的政策名稱。例如：Assign Message。
9. 點選「建立」。
10. 下方的 XML 程式碼中的 <APIKey> 元素，會指定傳入要求中 API 金鑰的位置。根據預設，這項政策會從 HTTP 要求中名為 apikey 的查詢參數擷取金鑰。

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

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

11. 將「Assign Message」政策的內容更新為下列內容：
    注意：進行這項編輯後，政策名稱會變更為 Remove Query Param apikey。

<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

12. 新增 VerifyApiKey 和 Remove Query Param apikey 政策。
    1. 在「Proxy endpoints」(Proxy 端點) 選單中，按一下「Preflow」(前置流程)。
    2. 在視覺化編輯器的「要求」窗格中，按一下 「新增政策步驟」。
    3. 在「新增政策步驟」窗格中，選取「驗證 API 金鑰」。
    4. 按一下「新增」。
    5. 在視覺化編輯器的「要求」窗格中，按一下 「新增政策步驟」。
    6. 在「新增政策步驟」窗格中，選取「Remove Query Param apikey」(移除查詢參數 apikey)。
    7. 按一下「新增」。
13. 按一下 [儲存]。
14. 將 Proxy 部署至環境：
    1. 按一下 [Deploy] (部署)。
    2. 選取「修訂版本」和「環境」。
    3. 按一下 [Deploy] (部署)。
15. 如要測試變更，請按照「 嘗試呼叫 API」一節的說明呼叫 API。

傳統版 UI

1. 在 API Proxy 編輯器中，按一下「開發」分頁標籤。您會看到 API 代理的要求流程中新增了兩項政策：
   • 驗證 API 金鑰：檢查 API 呼叫，確保其中含有有效的 API 金鑰 (以查詢參數的形式傳送)。
   • 移除查詢參數 apikey：指派訊息政策會在檢查 API 金鑰後移除該金鑰，避免金鑰在不必要的情況下傳遞及公開。

2. 在流程檢視畫面中，按一下「Verify API Key」政策圖示，然後查看下方程式碼檢視畫面中的政策 XML 設定。<APIKey> 元素會告知政策，在發出呼叫時應從何處尋找 API 金鑰。根據預設，系統會在 HTTP 要求中尋找名為 apikey 的查詢參數做為金鑰：

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

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

嘗試呼叫 API

在本步驟中，您將直接對目標服務發出成功的 API 呼叫，然後對 API 代理發出失敗的呼叫，瞭解政策如何保護 API 代理。

1. 成功

   在網路瀏覽器中前往下列網址，這是 API Proxy 設定要將要求轉送至的目標服務，但您目前會直接存取該服務：

   http://mocktarget.apigee.net

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

2. 失敗

   現在請嘗試呼叫 API Proxy：

   curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

   其中 YOUR ENV_GROUP_HOSTNAME 是環境群組主機名稱。請參閱「 找出環境群組主機名稱」。

   注意： 如果無法呼叫 Proxy，您可能需要新增 Host 標頭，詳情請參閱「部署 Proxy 範例」。

   如果沒有「驗證 API 金鑰」政策，這次呼叫會提供與上次呼叫相同的回應。但在此情況下，您應該會收到下列錯誤回應：

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

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

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

新增 API 產品

Cloud 控制台中的 Apigee

如要使用 Apigee UI 新增 API 產品，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Distribution」>「API products」頁面：

   前往 API 產品

2. 點選「+建立」。
3. 輸入 API 產品的產品詳細資料。
   

   欄位	說明
   名稱	API 產品的內部名稱。名稱中不得包含特殊字元。 注意：API 產品建立完成後，您就無法編輯名稱。
   顯示名稱	API 產品的顯示名稱。顯示名稱會顯示在使用者介面中，而且隨時可以編輯。如未指定，系統會使用「名稱」值。這個欄位會自動填入「名稱」值，您可以編輯或刪除其內容。顯示名稱可以包含特殊字元。
   說明	API 產品的說明。
   環境	API 產品允許存取的環境。例如 test 或 prod。
   存取	選取 Public。
   自動核准存取要求	針對任何應用程式，啟用這項 API 產品的金鑰要求自動核准功能。
   配額	在本教學課程中，請忽略這項錯誤。
   允許的 OAuth 範圍	在本教學課程中，請忽略這項錯誤。

4. 在「作業」部分中，按一下「新增作業」。
5. 在「API Proxy」欄位中，選取您剛建立的 API Proxy。
6. 在「路徑」欄位中輸入「/」。忽略其他欄位。
7. 按一下「儲存」儲存作業。
8. 按一下「儲存」，儲存 API 產品。

如要進一步瞭解如何新增 API 產品，請參閱「 建立 API 產品」。

傳統版 UI

如要使用 Apigee UI 新增 API 產品，請按照下列步驟操作：

1. 依序選取「發布」>「API 產品」。
2. 點選「+建立」。
3. 輸入 API 產品的產品詳細資料。
   

   欄位	說明
   名稱	API 產品的內部名稱。名稱中不得包含特殊字元。 注意：API 產品建立完成後，您就無法編輯名稱。
   顯示名稱	API 產品的顯示名稱。顯示名稱會顯示在使用者介面中，且隨時可以編輯。如未指定，系統會使用「名稱」值。系統會使用「名稱」值自動填入這個欄位，您可以編輯或刪除其內容。顯示名稱可以包含特殊字元。
   說明	API 產品的說明。
   環境	API 產品允許存取的環境。例如 test 或 prod。
   存取	選取 Public。
   自動核准存取要求	針對任何應用程式，啟用這項 API 產品的金鑰要求自動核准功能。
   配額	在本教學課程中，請忽略這項錯誤。
   允許的 OAuth 範圍	在本教學課程中，請忽略這項錯誤。

4. 在「Operations」部分中，按一下「ADD AN OPERATION」。
5. 在「API Proxy」欄位中，選取您剛建立的 API Proxy。
6. 在「路徑」欄位中輸入「/」，並忽略其他欄位。
7. 按一下「儲存」儲存作業。
8. 按一下「儲存」，儲存 API 產品。

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

接下來，我們要模擬開發人員註冊使用您 API 的工作流程。開發人員會有一或多個呼叫您 API 的應用程式，每個應用程式都會取得專屬 API 金鑰。API 供應商可以藉此更精細地控管 API 存取權，並取得更精細的應用程式 API 流量報表。

建立開發人員

Cloud 控制台中的 Apigee

如要建立開發人員：

1. 在 Google Cloud 控制台中，依序前往「發布」>「開發人員」頁面：

   前往「開發人員」

2. 點選「+ 建立」。
3. 在「新增開發人員」視窗中輸入下列資訊：
   

   欄位	值
   名字	Keyser
   姓氏	Soze
   電子郵件	[e-mail]
   使用者名稱	keyser

4. 按一下「新增」。

如要進一步瞭解如何建立開發人員，請參閱「 註冊應用程式開發人員」。

傳統版 UI

如要建立開發人員：

1. 在選單中依序選取「發布」>「開發人員」。
   注意：如果仍停留在「開發」畫面，請按一下「DEVELOP」旁的「<」，顯示選單並選取「發布」>「開發人員」。
2. 按一下「+ 開發人員」。
3. 在「New Developer」(新開發人員) 視窗中輸入下列資訊：
   

   在這個欄位中	Enter 鍵
   名字	Keyser
   姓氏	Soze
   使用者名稱	keyser
   電子郵件	[e-mail]

4. 點選「建立」。

註冊應用程式

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往「Distribution」>「Apps」頁面：

   前往「應用程式」

2. 點選「+ 建立」。
3. 在「建立應用程式」視窗中輸入下列資訊：
   

   欄位	值
   應用程式名稱	輸入：keyser_app
   顯示名稱	輸入：keyser_app
   開發人員	選取：Keyser Soze ([e-mail])
   回呼網址	留空
   附註	留空

4. 在「憑證」部分中，按一下「新增憑證」。
5. 選取「永不」。這個應用程式的憑證永不過期。
6. 按一下「新增產品」。
7. 選取剛建立好的產品。
8. 按一下「新增」。
9. 點選「建立」。

如要進一步瞭解如何註冊應用程式，請參閱「 註冊應用程式」。

傳統版 UI

如要註冊開發人員應用程式，請按照下列步驟操作：

1. 依序選取「發布」>「應用程式」。
2. 按一下「+ 應用程式」。
3. 在「New Developer App」(新增開發人員應用程式) 視窗中輸入下列資訊：
   

   欄位	值
   名稱和顯示名稱	輸入：keyser_app
   開發人員	選取：Keyser Soze ([e-mail])
   回呼網址和附註	留空

4. 在「憑證」部分中，選取「永不」。 這個應用程式的憑證永不過期。
5. 按一下「新增產品」。
6. 選取剛建立好的產品。
7. 點選「建立」。

取得 API 金鑰

Cloud 控制台中的 Apigee

如要取得 API 金鑰，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Distribution」>「Apps」頁面。

   前往「應用程式」

2. 從應用程式清單中選取所需應用程式。
3. 在「查看應用程式」頁面的「憑證」下方，點選「金鑰」欄位旁的 。請注意，金鑰會與您建立的產品建立關聯。
4. 按一下 「複製」。 您會在下一個步驟中使用這組金鑰。

傳統版 UI

如要取得 API 金鑰，請按照下列步驟操作：

1. 在「應用程式」頁面 (依序點選「發布」>「應用程式」)，按一下「keyser_app」keyser_app。
2. 在「keyser_app」keyser_app頁面中，按一下「憑證」部分中「金鑰」旁的「顯示」。請注意，金鑰會與您建立的產品建立關聯。
   
3. 選取並複製金鑰。您會在下一個步驟中使用此項目。

使用金鑰呼叫 API

現在您已取得 API 金鑰，可以呼叫 API Proxy。如畫面所示，將 API 金鑰貼到查詢參數中。確認查詢參數中沒有多餘的空格。

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=YOUR_API_KEY

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

恭喜！您已建立 API Proxy，並要求在呼叫中加入有效的 API 金鑰，藉此保護 API Proxy。

請注意，一般而言，不建議將 API 金鑰做為查詢參數傳遞。建議您改為在 HTTP 標頭中傳遞。

最佳做法：在 HTTP 標頭中傳遞金鑰

注意：建議您在標頭中傳遞 API 金鑰，而非查詢參數。查詢參數會顯示在瀏覽器記錄和網路記錄中，可能造成安全風險。標頭不會顯示在瀏覽器記錄和網路記錄中。

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

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往「Proxy development」>「API proxies」頁面。

前往 API Proxy

2. 從 Proxy 清單中選取所需 Proxy。
3. 在「Proxy details」(Proxy 詳細資料) 頁面中，按一下「Develop」(開發)。
4. 修改政策 XML，讓政策在標頭中尋找，而不是在查詢參數中尋找：

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

5. 按一下「儲存」儲存變更。
6. 按一下 [Deploy] (部署)。
7. 選取「修訂版本」和「環境」。
8. 按一下 [Deploy] (部署)。

9. 使用 cURL 進行下列 API 呼叫，將 API 金鑰做為名為 x-apikey 的標頭傳遞。別忘了代入貴機構名稱。

   curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

請注意，如要完全完成變更，您也需要設定「指派訊息」政策，移除標頭而非查詢參數。例如：

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

注意：您也可以將 API 金鑰做為表單參數傳遞。如果這麼做，系統會將「驗證 API 金鑰」政策設定如下：

<APIKey ref="request.formparam.YOUR_API_KEY"/>

傳統版 UI

1. 編輯 API Proxy。依序選取「Develop」>「API Proxies」>「helloworld_apikey」，然後前往「Develop」檢視畫面。

2. 選取「Verify API Key」政策，並修改政策 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_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

請注意，如要完全完成變更，您也需要設定「指派訊息」政策，移除標頭而非查詢參數。例如：

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

注意：您也可以將 API 金鑰做為表單參數傳遞。如果這麼做，系統會將「驗證 API 金鑰」政策設定如下：

<APIKey ref="request.formparam.YOUR_API_KEY"/>

相關主題

以下是與 API 產品和金鑰相關的主題：

• 管理 API 產品
• API 金鑰
• 註冊應用程式開發人員
• 註冊應用程式及管理 API 金鑰
• 驗證 API 金鑰政策

API 保護機制通常會採用額外的安全防護措施，例如 OAuth。這項開放通訊協定會將憑證 (例如使用者名稱和密碼) 換成存取權杖。存取權杖是隨機產生的長字串，可透過訊息管道傳遞，包括從一個應用程式傳遞至另一個應用程式，不會洩漏原始憑證。

如要瞭解安全性相關主題，請參閱「保護 Proxy 安全」。