使用 OAuth 2.0 保護 API

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

查看 Apigee Edge 說明文件。

本教學課程說明如何使用 OAuth 2.0 存取權杖保護 API Proxy。

事前準備

如要完成本教學課程，您必須有權存取 Apigee 機構，並具備以下權限：

• 建立及部署 API Proxy
• 建立 API 產品
• 建立開發人員應用程式

您也必須正確設定環境群組主機名稱，才能發出 Apigee API Proxy 呼叫。如果您不確定要使用哪個環境群組主機名，請諮詢您的 Apigee 管理員。

部署 OAuth 2.0 Proxy

我們在 GitHub 上提供了一個 API Proxy，該代理配置為產生 OAuth 2.0 存取權杖。請按照下列步驟將這個 API Proxy 下載並部署至您的環境：

將 oauth 範例 API Proxy 下載至檔案系統的目錄。

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

   前往 API Proxy

2. 在「API Proxy」窗格中，按一下「+ 建立」。
3. 在「建立 Proxy」窗格的「Proxy 範本」下方，選取「上傳 Proxy 套裝組合」。
4. 選擇您下載的 oauth.zip 文件，然後按一下 下一步。
5. 點選「下一步」。
6. 部署 (選用)：
   • 部署環境：選用。使用複選框選擇一個或多個要部署代理程式的環境。如果您此時不想部署代理，請將 部署環境 欄位留空。您之後隨時可以部署代理程式。
   • 服務帳戶：選填。將服務帳戶附加至部署作業，即可讓 Proxy 存取 Google Cloud 服務，如服務帳戶的角色和權限所指定。
7. 點選「建立」。

您已成功下載並將存取權杖產生 API Proxy 部署至 Apigee 機構。

查看 OAuth 2.0 流程和政策

請花幾分鐘檢查 OAuth 2.0 策略配置。

接下來，您將深入瞭解 API Proxy 的內容。

1. 在 API Proxy 編輯器中，點按「Develop」分頁標籤。

   

   左側窗格會顯示兩項政策。在代理端點部分，您也會看到兩個 POST 流。

2. 點選「Proxy Endpoints」下方的「AccessTokenClientCredential」。 文字編輯器顯示了 AccessTokenClientCredential 條件流的 XML 程式碼：

   <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> 元素中定義的條件表示，如果向 /accesstoken 資源發出 API Proxy 調用，並且請求謂詞為 POST，則執行 GenerateAccessTokenClient 策略，則策略會產生存取權杖。

3. 現在我們來看看條件流程將觸發的策略。在「Request」窗格中，按一下「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 milliseconds, 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 2.0 <GrantType> 是 client_credentials （以用戶端金鑰和金鑰交換 OAuth 2.0 權杖）。
• 第二個 <GrantType> 元素告訴策略在 API 呼叫中哪裡尋找授權類型參數，這是 OAuth 2.0 規範所要求的。 (稍後您會在 API 呼叫中看到這個值)。授權類型也可以在 HTTP 標頭 (request.header.grant_type) 中傳送，或作為表單參數 (request.formparam.grant_type) 傳送。

目前您不需要對 API Proxy 採取任何其他行動。在後續步驟中，您會使用這個 API Proxy 產生 OAuth 2.0 存取權杖。但首先，你還需要做幾件事：

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

建立受保護的 API Proxy

現在要建立您想保護的 API Proxy。這是傳回你想要的內容的 API 呼叫。在這種情況下，API 代理程式將呼叫 Apigee 的 mocktarget 服務來傳回您的 IP 位址。但只有在 API 呼叫中傳遞有效的 OAuth 2.0 存取權杖時，才會看到這項資訊。

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

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

   前往 API Proxy

2. 在「API Proxy」窗格中，按一下「+ 建立」。
3. 在創建代理窗格下方代理模板， 選擇反向代理（最常用） 。
4. 使用下列項目設定 Proxy：
   

   在這個欄位中	這樣做
   Proxy 名稱	輸入：helloworld_oauth2
   基本路徑	變更為：/hellooauth2 專案基本路徑是用於向 API 代理程式發出請求的 URL 的一部分。
   說明	輸入：hello world protected by OAuth 2.0
   目標 (現有 API)	輸入：https://mocktarget.apigee.net/ip 這會定義 Apigee 在要求 API Proxy 時叫用的目標網址。

5. 點選「下一步」。
6. 部署 (選用)：
   • 部署環境：選用。使用核取方塊選取要部署 Proxy 的一或多個環境。如果您此時不想部署代理，請將 部署環境 欄位留空。您之後隨時可以部署代理程式。
   • 服務帳戶：選填。將服務帳戶附加至部署作業，即可讓 Proxy 存取 Google Cloud 服務，如服務帳戶的角色和權限所指定。
7. 點選「建立」。
8. 點選「helloworld_oauth2」 Proxy 的「Develop」分頁標籤。
9. 在「政策」選單中，按一下「新增政策」圖示 control_point 。
10. 在「建立政策」窗格中，選取「OAuth 2.0」。
11. 按一下「建立」。

查看政策

讓我們進一步瞭解您建立的內容。

1. 在 API Proxy 編輯器中，點按「Develop」分頁標籤。您會看到 API Proxy 的請求流程中新增了兩個策略：
   • 驗證 OAuth v2.0 存取權杖：檢查 API 呼叫，確保存在有效的 OAuth 2.0 權杖。
   • 移除標頭授權 – 指派訊息策略，在檢查存取權杖後將其移除，以防止其傳遞給目標服務。(如果目標服務需要 OAuth 2.0 存取權杖，就不會使用這項政策)。

2. 點選驗證 OAuth v2.0 存取權令牌點擊右側窗格中的圖標，然後在文字編輯器中查看其下方的 XML。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

請注意，<Operation> 為 VerifyAccessToken。操作定義了策略應該執行的操作。在本例中，它將檢查請求中是否存在有效的 OAuth 2.0 令牌。

新增 API 產品

要取得 OAuth 2.0 存取權杖，您需要建立三個 Apigee 實體：API 產品、開發人員和開發人員應用程式。

1. 建立 API 產品：

在 Google Cloud 控制台中，前往 「Apigee」 > 「發布」 > 「API 產品」頁面。

前往 API 產品

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

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

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

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

接下來，您要模擬開發人員註冊使用 API 的工作流程。 理想情況下，開發人員會透過開發人員入口網站自行註冊，並註冊自己的應用程式。不過，在這個步驟中，您會以管理員身分新增開發人員和應用程式。

開發人員會有一或多個呼叫您 API 的應用程式，每個應用程式都會取得專屬的用戶端金鑰和消費者密碼。此外，API 提供者也能透過這項機制，更精細地控管 API 存取權，並取得更精細的 API 流量數據分析報表，因為 Apigee 知道哪些開發人員和應用程式屬於哪些 OAuth 2.0 權杖。

建立開發人員

我們來建立名為 Nigel Tufnel 的開發人員。

1. 開啟「開發人員」編輯器。

2. 在 Google Cloud 控制台，依序前往「Apigee」>「Distribution」>「Developers」頁面。

   前往「開發人員」

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

   在這個欄位中	Enter 鍵
   名字	Nigel
   姓氏	Tufnel
   電子郵件	nigel@example.com
   使用者名稱	nigel

5. 按一下「新增」。

註冊應用程式

為奈傑建立應用程式。

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

   前往「應用程式」

2. 點選「+ 建立」。
3. 在「New App」(新應用程式) 視窗中輸入下列內容：
   

   在這個欄位中	請按照下列步驟操作：
   「名稱」和「顯示名稱」	輸入：nigel_app
   開發人員	按一下「開發人員」，然後選取：Nigel Tufnel (nigel@example.com)
   回呼網址和附註	留空

4. 按一下「+ 新增憑證」。
5. 然後按一下「+ 新增產品」。
6. 選取剛建立的 API 產品。
7. 按一下「新增」。
8. 點選「建立」。

取得用戶端金鑰和密鑰

現在您將獲得用戶端金鑰和消費者密鑰，它們將用於交換 OAuth 2.0 存取權杖。

1. 開啟 nigel_app 頁面。
1. 確認顯示 nigel_app 頁面。如果沒有，請前往「發布」>「應用程式」頁面。

   前往「應用程式」

2. 在 nigel_app 頁面上，點選 Key 和 Secret 欄位中的 visibility_off。請注意，金鑰/密鑰與您先前建立的 API 產品相關聯。

2. 選取並複製「金鑰」和「密鑰」值。將這些內容貼到暫存文字檔中。您會在後續步驟中使用這些憑證，呼叫 API 代理程式，將這些憑證換成 OAuth 2.0 存取權杖。

嘗試呼叫 API 來取得 IP 位址 (失敗！)

嘗試呼叫您剛剛建立的受保護 API Proxy。Notice that you are 不是passing an OAuth 2.0 存取權杖 in the call.

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

由於 API Proxy 具有 驗證 OAuth v2.0 存取權杖 策略，用於檢查請求中是否存在有效的 OAuth 2.0 權杖，因此呼叫應失敗並顯示下列訊息：

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

在這種情況下，失敗是件好事！這意味著您的 API Proxy 更加安全。只有擁有有效 OAuth 2.0 存取權杖的受信任應用程式才能成功呼叫此 API。

取得 OAuth 2.0 存取權杖

接著，您會使用複製並貼到文字檔的金鑰和密鑰，換取 OAuth 2.0 存取權杖。現在要對匯入的 API 範例 Proxy「oauth」發出 API 呼叫，產生 API 存取權杖。

使用該金鑰和密碼，進行下列 cURL 呼叫 (請注意，通訊協定為 https)：

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

請注意，如果您使用 Postman 等用戶端發出呼叫，client_id 和 client_secret 會放在要求主體中，且必須為 x-www-form-urlencoded。

您應該會收到類似下面的回應：

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

您已取得 OAuth 2.0 存取權杖！複製 access_token 值 (不含引號)，然後貼到文字檔中。你馬上就會用到它。

發生什麼事了？

還記得您先前在 oauth Proxy 中查看「條件流程」時，系統顯示如果資源 URI 是 /accesstoken 且要求動詞是 POST，就會執行 GenerateAccessTokenClient OAuth 2.0 政策來產生存取權杖嗎？您的 cURL 指令符合這些條件，因此執行了 OAuth 2.0 策略。並驗證您的用戶端金鑰和消費者密鑰，然後換取 1 小時後過期的 OAuth 2.0 權杖。

使用存取權杖呼叫 API (成功！)

取得存取權杖後，您就可以使用該權杖呼叫 API Proxy。執行以下 cURL 呼叫。替換 Apigee 機構名稱和存取權杖。

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

您現在應該可以成功呼叫 API Proxy，並傳回 IP 位址。例如：

{"ip":"::ffff:192.168.14.136"}

您可以在將近一小時內重複呼叫該 API，之後存取權杖就會過期。如果要在一小時後進行呼叫，則需要使用前面的步驟產生新的存取權杖。

恭喜！您已建立 API Proxy，並要求在呼叫中加入有效的 OAuth 2.0 存取權杖，以保護 API Proxy。

相關主題

• OAuth 2.0 首頁
• OAuthV2 政策
• 下載 API Proxy (說明如何將 API Proxy 封裝成 ZIP 檔案，就像您下載的檔案一樣)