本頁面由 Cloud Translation API 翻譯而成。

使用 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，該 Proxy 已設定為產生 OAuth 2.0 存取權杖。請按照下列步驟下載這個 API Proxy 並部署至環境：

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

Cloud 控制台中的 Apigee

在 Google Cloud 控制台中，前往「Proxy development」(Proxy 開發) >「API proxies」(API Proxy) 頁面。

前往 API Proxy

注意：繼續操作前，請先查看或搜尋 API Proxy 清單。如果已有名為 oauth 的值區，請點選該值區並跳至下一節，確認設定與說明內容相同。如果不同，請刪除並繼續執行這些步驟，或修改為符合所述設定。
在「API Proxies」窗格中，按一下「+ Create」。
在「建立 Proxy」窗格的「Proxy 範本」下方，選取「上傳 Proxy 套件」。
選擇您下載的 oauth.zip 檔案，然後按一下「下一步」。
點選「下一步」。
部署 (選用)：
- 部署環境：選用。使用核取方塊選取要部署 Proxy 的一或多個環境。如果不想在這個時間點部署 Proxy，請將「部署環境」欄位留空。您之後隨時可以部署 Proxy。
- 服務帳戶：選用。將服務帳戶附加至部署作業，即可讓 Proxy 存取 Google Cloud 服務，如服務帳戶的角色和權限所指定。
點選「建立」。

傳統版 Apigee

前往 Apigee 使用者介面，登入並選取 Apigee 機構。
在左側導覽列中選取「開發」>「API Proxy」。
注意：繼續操作前，請先查看或搜尋 API Proxy 清單。如果已有 oauth，請點選該項目並跳至下一節，確認設定與說明內容相同。如果不同，請刪除並繼續執行這些步驟，或修改為符合所述設定。
按一下「建立新項目」。
在「建立 Proxy」精靈中，選取「上傳 Proxy 套件」。
選擇您下載的 oauth.zip 檔案，然後按一下「下一步」。
點選「建立」。
建構完成後，按一下「Edit proxy」(編輯 Proxy)，即可在 API Proxy 編輯器中查看新的 Proxy。
按一下 [Deploy] (部署)。
選取要部署的修訂版本和環境。您可以將「服務帳戶」欄位留空。
按一下 [Deploy] (部署)。

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

查看 OAuth 2.0 流程和政策

請花點時間檢查 OAuth 2.0 政策設定。

Apigee Cloud 控制台

接下來，您將進一步瞭解 API 代理伺服器包含的內容。

在 API Proxy 編輯器中，按一下「開發」分頁標籤。

左側窗格會顯示兩項政策。您也會在「Proxy Endpoints」部分看到兩個 POST 流程。
按一下「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> 元素中定義的條件表示，如果 API Proxy 呼叫是傳送至 /accesstoken 資源，且要求動詞為 POST，則執行 GenerateAccessTokenClient 政策，產生存取權杖。
現在來看看條件式流程會觸發的政策。在「Request」(要求) 窗格中，按一下「GenerateAccessTokenClient」政策：

傳統版 Apigee

接下來，您將進一步瞭解 API 代理伺服器包含的內容。

在 API Proxy 編輯器中，按一下「開發」分頁標籤。左側的「Navigator」窗格會顯示兩項政策。您也會在「Proxy Endpoints」部分看到兩個 POST 流程。
按一下「Proxy 端點」下方的「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 政策，產生存取權杖。
現在來看看條件式流程會觸發的政策。在流程圖中，按一下「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 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> 元素會根據 OAuth 2.0 規格，告知政策要在 API 呼叫中的哪個位置尋找授權類型參數。(您稍後會在 API 呼叫中看到這個值)。授權類型也可以在 HTTP 標頭 (request.header.grant_type) 中傳送，或是做為表單參數 (request.formparam.grant_type) 傳送。

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

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

建立受保護的 API Proxy

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

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

Cloud 控制台中的 Apigee

在 Google Cloud 控制台中，前往「Proxy development」(Proxy 開發) >「API proxies」(API Proxy) 頁面。

前往 API Proxy
在「API Proxies」窗格中，按一下「+ Create」。
在「建立 Proxy」窗格的「Proxy 範本」下方，選取「反向 Proxy (最常見)」。

使用下列項目設定 Proxy：

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

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

傳統版 Apigee

前往 Apigee 使用者介面，登入並選取 Apigee 機構。
在左側導覽列中選取「開發」>「API Proxy」。
按一下「建立新項目」。
在「Build a Proxy」精靈中，選取「Reverse proxy (most common)」(反向 Proxy (最常見))。

使用下列項目設定 Proxy：

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

點選「下一步」。

在「Common policies」(一般政策) 頁面中：

在這個欄位中	請按照下列步驟操作：
安全性：授權	選取： OAuth 2.0 這些選項非常實用。系統會自動在 API Proxy 中新增兩項政策，並建立 API 產品。

在這個欄位中

請按照下列步驟操作：

安全性：授權

選取：

OAuth 2.0

這些選項非常實用。系統會自動在 API Proxy 中新增兩項政策，並建立 API 產品。

點選「下一步」。
在「摘要」頁面的「選用部署」下方，選取環境，然後按一下「建立並部署」。
按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。
系統會自動為您部署 API Proxy。(部署作業可能需要一些時間才能完成)。

查看政策

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

Apigee Cloud 控制台

在 API Proxy 編輯器中，按一下「開發」分頁標籤。您會看到 API 代理的要求流程中新增了兩項政策：
- 驗證 OAuth v2.0 存取權杖：檢查 API 呼叫，確保存在有效的 OAuth 2.0 權杖。
- 移除標頭授權：指派訊息政策會在檢查存取權杖後移除權杖，以免權杖傳遞至目標服務。(如果目標服務需要 OAuth 2.0 存取權杖，您就不會使用這項政策)。
按一下右側窗格中的「Verify OAuth v2.0 Access Token」圖示，然後查看文字編輯器中的 XML。

傳統版 Apigee

在 API Proxy 編輯器中，按一下「開發」分頁標籤。您會看到 API 代理的要求流程中新增了兩項政策：
- 驗證 OAuth v2.0 存取權杖：檢查 API 呼叫，確保存在有效的 OAuth 2.0 權杖。
- 移除標頭授權：指派訊息政策會在檢查存取權杖後移除權杖，以免權杖傳遞至目標服務。(如果目標服務需要 OAuth 2.0 存取權杖，您就不會使用這項政策)。
在流程檢視畫面中，按一下「Verify OAuth v2.0 Access Token」圖示，然後查看程式碼窗格中下方的 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。「Operation」會定義政策應執行的動作。在本例中，這項動作會在要求中檢查有效的 OAuth 2.0 權杖。

新增 API 產品

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

建立 API 產品：

Cloud 控制台中的 Apigee

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

前往 API 產品

傳統版 Apigee

在 Apigee 使用者介面中，依序前往「發布」> API 產品。

點選「+ 建立」。

輸入 API 產品的產品詳細資料。

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

在「Operations」部分中，按一下「Add An Operation」。
在「API Proxy」欄位中，選取您剛建立的 API Proxy。
在「路徑」欄位中輸入「/」，並忽略其他欄位。
按一下「儲存」儲存作業。
按一下「儲存」儲存 API 產品。

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

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

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

建立開發人員

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

Cloud 控制台中的 Apigee

開啟「開發人員」編輯器。
在 Google Cloud 控制台中，前往「發布」>「開發人員」頁面。

前往「開發人員」
點選「+ 建立」。

在「新增開發人員」視窗中輸入下列資訊：

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

按一下「新增」。

傳統版 Apigee

開啟「開發人員」編輯器。
在 Apigee 使用者介面中，依序前往「發布」>「開發人員」。
按一下「+ 開發人員」。

在「建立開發人員」視窗中輸入下列資訊：

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

點選「建立」。

註冊應用程式

為 Nigel 建立應用程式。

Cloud 控制台中的 Apigee

在 Google Cloud 控制台中，前往「發布」>「應用程式」頁面。

前往「應用程式」
點選「+ 建立」。

在「New App」(新應用程式) 視窗中輸入下列內容：

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

按一下「+ 新增憑證」。
然後按一下「+ 新增產品」。
選取剛建立的 API 產品。
按一下「新增」。
點選「建立」。

傳統版 Apigee

在 Apigee 使用者介面中，依序前往「發布」>「開發人員」。
按一下「+ 開發人員」。
按一下「+ 應用程式」。

在「New App」(新應用程式) 視窗中輸入下列內容：

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

在「產品」下方，按一下「新增產品」。
新增您剛建立的 API 產品。
點選「建立」。

取得用戶端金鑰和密鑰

現在您會取得用戶端金鑰和用戶端密鑰，這些金鑰和密鑰會交換為 OAuth 2.0 存取權杖。

開啟 nigel_app 頁面。

Cloud 控制台中的 Apigee

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

前往「應用程式」
在「nigel_app」頁面中，按一下「金鑰」和「密鑰」欄中的。請注意，金鑰/密鑰與您先前建立的 API 產品相關聯。

傳統版 Apigee

確認顯示 nigel_app 頁面。如果沒有，請前往「應用程式」頁面 (依序點選「發布」>「應用程式」)，然後按一下「nigel_app」。
在 nigel_app 頁面中，按一下「金鑰」和「密鑰」欄中的「顯示」。請注意，金鑰/密鑰與您先前建立的 API 產品相關聯。

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

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

請嘗試呼叫您剛建立的受保護 API Proxy。請注意，您並未在呼叫中傳遞 OAuth 2.0 存取權杖。

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

由於 API 代理伺服器具有「驗證 OAuth 2.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 代理伺服器，並取得 IP 位址。例如：

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

您可以在將近一小時內重複呼叫該 API，之後存取權杖就會過期。如要在 1 小時後撥打電話，請按照先前的步驟產生新的存取權杖。

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

使用 OAuth 2.0 保護 API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

部署 OAuth 2.0 Proxy

Cloud 控制台中的 Apigee

傳統版 Apigee

查看 OAuth 2.0 流程和政策

Apigee Cloud 控制台

傳統版 Apigee

建立受保護的 API Proxy

Cloud 控制台中的 Apigee

傳統版 Apigee

查看政策

Apigee Cloud 控制台

傳統版 Apigee

新增 API 產品

Cloud 控制台中的 Apigee

傳統版 Apigee

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

建立開發人員

Cloud 控制台中的 Apigee

傳統版 Apigee

註冊應用程式

Cloud 控制台中的 Apigee

傳統版 Apigee

取得用戶端金鑰和密鑰

Cloud 控制台中的 Apigee

傳統版 Apigee

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

取得 OAuth 2.0 存取權杖

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

相關主題

使用 OAuth 2.0 保護 API