使用 OAuth 保護 API

本教學課程說明如何使用 OAuth 2.0 保護 API。

OAuth 是一種授權通訊協定，可讓應用程式代表使用者存取資訊，使用者不必透露使用者名稱和密碼。

OAuth 會將安全憑證 (例如使用者名稱/密碼或金鑰/密鑰) 換成存取權杖。例如：

joe:joes_password (username:password) 或
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (key:secret)

會變成類似下列內容：

b0uiYwjRZLEo4lEu7ky2GGxHkanN

存取權杖是隨機字串，而且是暫時性的 (應在相對較短的時間後失效)，因此在應用程式工作流程中傳遞存取權杖來驗證使用者，比傳遞實際憑證安全得多。

OAuth 2.0 規格定義了不同的機制 (稱為「授權類型」)，可供應用程式發布存取權杖。OAuth 2.0 定義的最基本授權類型稱為「用戶端憑證」。在這種授權類型中，系統會產生 OAuth 存取權杖，以換取用戶端憑證 (即用戶端金鑰/用戶端密鑰配對，如上例所示)。

Edge 中的用戶端憑證授權類型是透過 API Proxy 中的政策實作。典型的 OAuth 流程包含兩個步驟：

• 呼叫 API Proxy 1，從用戶端憑證產生 OAuth 存取權杖。API Proxy 上的 OAuth v2.0 政策會處理這項作業。
• 呼叫 API Proxy 2，在 API 呼叫中傳送 OAuth 存取權杖。API Proxy 會使用 OAuth v2.0 政策驗證存取權杖。

軟硬體需求

• Apigee Edge 帳戶。如果還沒有帳戶，請按照「建立 Apigee Edge 帳戶」一文中的指示註冊。
• 電腦上已安裝 cURL，可從指令列發出 API 呼叫。

下載及部署權杖產生 API Proxy

在這個步驟中，您將建立 API Proxy，從 API 呼叫中傳送的用戶端金鑰和消費者密鑰產生 OAuth 存取權杖。Apigee 提供可執行這項操作的範例 API Proxy。您現在要下載及部署 Proxy，稍後在教學課程中會用到。(您可以輕鬆自行建構這個 API Proxy。(下載及部署步驟是為了方便起見，並向您展示分享已建立的 Proxy 有多麼容易。)

1. 將「oauth」範例 API Proxy ZIP 檔下載至檔案系統的任何目錄。
2. 前往 https://apigee.com/edge 並登入。
3. 在左側導覽列中，依序選取「開發」>「API Proxy」。
4. 按一下「+ Proxy」。
   
5. 在「建立 Proxy」精靈中，按一下「上傳 Proxy 套裝組合」。
6. 選擇您下載的 oauth.zip 檔案，然後按一下「下一步」。
7. 點選「建立」。
8. 建構完成後，按一下「編輯 Proxy」，即可在 API Proxy 編輯器中查看新的 Proxy。
9. 在 API Proxy 編輯器的「總覽」頁面中，按一下「部署」下拉式選單，然後選取「測試」。這是貴機構的測試環境。
   
   在確認提示中，按一下「Deploy」。
   再次點選「部署作業」下拉式選單時，綠色圖示會指出 Proxy 已部署至測試環境。
   

太棒了！您已成功下載並將存取權杖產生 API Proxy 部署至 Edge 機構。

查看 OAuth 流程和政策

讓我們進一步瞭解 API Proxy 包含哪些內容。

1. 在 API Proxy 編輯器中，點按「Develop」分頁標籤。左側的「Navigator」Navigator窗格會顯示兩項政策。您也會在「Proxy Endpoints」部分看到兩個 POST 流程。

2. 按一下 Proxy Endpoints 下方的「AccessTokenClientCredential」AccessTokenClientCredential。
   

   在 XML 程式碼檢視畫面中，您會看到名為 AccessTokenClientCredential 的 Flow：

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>

   流程是 API Proxy 中的處理步驟。在這種情況下，工作流程會在符合特定條件時觸發 (稱為條件式工作流程)。<Condition> 元素中定義的條件表示，如果 API Proxy 呼叫是針對 /accesstoken 資源發出，且要求動詞為 POST，則執行 GenerateAccessTokenClient 政策，產生存取權杖。

3. 現在來看看條件式流程會觸發的政策。按一下流程圖中的「GenerateAccessTokenClient」GenerateAccessTokenClient政策圖示。
   
   下列 XML 設定會載入程式碼檢視畫面：

   <OAuthV2 name="GenerateAccessTokenClient">
       <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
       <Operation>GenerateAccessToken</Operation>
       <!-- This is in millseconds, so expire in an hour -->
       <ExpiresIn>3600000</ExpiresIn>
       <SupportedGrantTypes>
           <!-- This part is very important: most real OAuth 2.0 apps will want to use other
            grant types. In this case it is important to NOT include the "client_credentials"
            type because it allows a client to get access to a token with no user authentication -->
           <GrantType>client_credentials</GrantType>
       </SupportedGrantTypes>
       <GrantType>request.queryparam.grant_type</GrantType>
       <GenerateResponse/>
   </OAuthV2>

   設定包括下列項目：

   • <Operation> 可以是多個預先定義的值之一，用於定義政策的用途。在本例中，政策會產生存取權杖。
   • 權杖會在產生 1 小時 (3600000 毫秒) 後失效。
   • 在 <SupportedGrantTypes> 中，預期使用的 OAuth <GrantType> 是 client_credentials (以 OAuth 權杖交換用戶端金鑰和密鑰)。
   • 第二個 <GrantType> 元素會根據 OAuth 2.0 規格，告知政策要在 API 呼叫中的哪個位置尋找授權類型參數。(稍後您會在 API 呼叫中看到這個值)。授權類型也可以在 HTTP 標頭 (request.header.grant_type) 中傳送，或是以表單參數 (request.formparam.grant_type) 的形式傳送。

目前您不需要對 API Proxy 採取任何其他行動。在後續步驟中，您會使用這個 API Proxy 產生 OAuth 存取權杖。但首先，您需要完成下列事項：

• 建立您實際要使用 OAuth 保護的 API Proxy。
• 再建立幾個構件，產生用戶端金鑰和密鑰，以便換取存取權杖。

建立受 OAuth 保護的 API Proxy

現在要建立您想保護的 API Proxy。這是會傳回所需內容的 API 呼叫。在本例中，API Proxy 會呼叫 Apigee 的 mocktarget 服務，傳回您的 IP 位址。但只有在 API 呼叫中傳遞有效的 OAuth 存取權杖，您才能看到這項資訊。

您在此建立的 API Proxy 會包含一項政策，用於檢查要求中是否有 OAuth 權杖。

1. 在左側導覽列中，依序選取「開發」>「API Proxy」。
2. 按一下「+ Proxy」。
   
3. 在「Build a Proxy」(建立 Proxy) 精靈中，選取「Reverse proxy (most common)」(反向 Proxy (最常見))，然後按一下「Next」(下一步)。
4. 使用下列項目設定 Proxy：
   

   在這個欄位中	請按照下列步驟操作：
   Proxy 名稱	輸入：helloworld_oauth2
   專案基本路徑	變更為：/hellooauth2 專案基本路徑是向 API Proxy 提出要求時所用網址的一部分。
   現有 API	輸入：https://mocktarget.apigee.net/ip 這會定義 Apigee Edge 在對 API Proxy 發出要求時，所叫用的目標網址。
   說明	輸入：hello world protected by OAuth

5. 點選 [下一步]。
6. 在「Common policies」(一般政策) 頁面中：

   在這個欄位中	請按照下列步驟操作：
   安全性：授權	選取「OAuth 2.0」

7. 點選 [下一步]。
8. 在「虛擬主機」頁面中，按一下「下一步」。
9. 在「Build」(建構) 頁面中，確認已選取 test 環境，然後按一下「Create and Deploy」(建立及部署)。
10. 在「摘要」頁面中，您會看到確認訊息，指出新的 API Proxy 已成功建立，且已部署至測試環境。
11. 按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。
    請注意，這次 API Proxy 會自動部署。按一下「部署」下拉式選單，確認「測試」環境旁有綠色的部署點。