本頁面由 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，已設定為產生 OAuth 2.0 存取權憑證。請按照下列步驟下載並將此 API Proxy 部署至環境：

將 oauth API Proxy 範例下載至檔案系統的某個目錄。
前往 Apigee UI 登入並選取 Apigee 機構。
在左側導覽列中，依序選取「Develop」>「API Proxies」。
注意：請先查看或搜尋 API Proxy 清單，再繼續操作。如果您已有名為 oauth 的值，請點選該值，然後跳至下一節，確認其設定與說明一致。如果您的設定不同，請刪除並繼續執行這些步驟，或修改設定以符合上述設定。
按一下「建立新項目」。
在「Create Proxy」精靈中，選取「Upload proxy bundle」。
選擇您下載的 oauth.zip 檔案，然後按一下「下一步」。
按一下 [建立]。
建構完成後，按一下「Edit proxy」，即可在 API Proxy 編輯器中查看新的 Proxy。
按一下 [Deploy] (部署)。
選取要部署的修訂版本和環境。您可以將「Service account」(服務帳戶)欄位留空。
按一下 [Deploy] (部署)。

您已成功下載及部署存取權憑證產生 API Proxy 至 Apigee 機構。

查看 OAuth 2.0 流程和政策

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

全新 Proxy 編輯器

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

在 API 代理編輯器中，按一下「Develop」分頁標籤。

左側窗格會顯示兩個政策。您也會在「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」政策：

傳統 Proxy 編輯器

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

在 API Proxy 編輯器中，按一下「Develop」分頁標籤。在左側導覽面板中，您會看到兩個政策。您也會在「Proxy Endpoints」部分看到兩個 POST 流程。
按一下「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 政策，產生存取權存證。
接下來，我們來看看條件式流程會觸發哪些政策。按一下流程圖中的「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> 元素會告知政策在 API 呼叫中尋找授權類型參數的位置，這符合 OAuth 2.0 規範的要求。(您稍後會在 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 權杖。

在左側導覽列中，依序選取「Develop」>「API Proxies」。
按一下「建立新項目」。
在「Build a Proxy」精靈中，選取「Reverse proxy (most common)」。

使用以下設定 Proxy：

在這個欄位中	執行這項操作
Proxy 名稱	輸入：`helloworld_oauth2`
專案 Base Path	變更為：`/hellooauth2` 專案基礎路徑是用於向 API Proxy 提出要求的網址的一部分。
現有 API	輸入：`https://mocktarget.apigee.net/ip` 這會定義 Apigee 在對 API Proxy 提出要求時，所叫用的目標網址。
說明	輸入：`hello world protected by OAuth 2.0`

點按「Next」。

在「常見政策」頁面中：

在這個欄位中	執行這項操作
安全性：授權	選取： OAuth 2.0 這些選項非常實用。系統會自動在 API 代理程式中新增兩項政策，並建立 API 產品。

在這個欄位中

執行這項操作

安全性：授權

選取：

OAuth 2.0

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

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

查看政策

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

全新 Proxy 編輯器

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

傳統 Proxy 編輯器

在 API Proxy 編輯器中，按一下「Develop」分頁標籤。您會發現已在 API 代理程式的要求流程中新增兩項政策：
- 驗證 OAuth 2.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。作業會定義政策應執行的動作。在本例中，作業會在要求中檢查有效的 OAuth 2.0 權杖。

新增 API 產品

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

依序選取「發布」>「API 產品」。
點選「+建立」。

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

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

在「操作」部分中，按一下「新增操作」。
在「API Proxy」欄位中，選取您剛剛建立的 API Proxy。
在「路徑」欄位中輸入「/」。請忽略其他欄位。
按一下「儲存」，即可儲存作業。
按一下「儲存」，即可儲存 API 產品。

將開發人員和應用程式新增至貴機構

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

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

建立開發人員

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

在選單中依序選取「發布」>「開發人員」。
按一下「+ 開發人員」。

在「新增開發人員」視窗中輸入以下內容：

在這個欄位中	Enter 鍵
名字	`Nigel`
姓氏	`Tufnel`
使用者名稱	`nigel`
電子郵件	`[email protected]`

按一下 [儲存]。

註冊應用程式

我們來為奈傑爾建立應用程式。

依序選取「發布」>「應用程式」。
按一下「+ 應用程式」。

在「New App」視窗中輸入以下內容：

在這個欄位中	執行這項操作
名稱和顯示名稱	輸入：`nigel_app`
開發人員	按一下「開發人員」，然後選取：`Nigel Tufnel ([email protected])`
回呼網址和附註	留空

點選「產品」下方的「新增產品」。
新增剛剛建立的 API 產品。
按一下 [建立]。

取得用戶端金鑰和密鑰

您現在會取得用戶端金鑰和密鑰，並用來換取 OAuth 2.0 存取權杖。

確認畫面顯示 nigel_app 頁面。如果沒有，請在「應用程式」頁面 (「發布」>「應用程式」) 中，按一下「nigel_app」。
在 nigel_app 頁面上，按一下「Key」和「Secret」欄中的「Show」。請注意，金鑰/密鑰會與您先前建立的 API 產品相關聯。
選取並複製金鑰和密鑰。將這些內容貼到暫存文字檔中。您會在後續步驟中使用這些憑證，呼叫 API Proxy 時，系統會將這些憑證換成 OAuth 2.0 存取權杖。

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

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

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

由於 API Proxy 有「Verify OAuth v2.0 Access Token」政策，會在要求中檢查有效的 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 發出 API 呼叫，也就是 oauth，這會產生 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 會放在要求的 Body 中，且必須為 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" : "[email protected]",
  "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 快取代理中查看「條件式流程」時，有提到如果資源 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 約一小時，之後存取權杖就會到期。如要在一小時後撥打電話，您必須按照先前的步驟產生新的存取權杖。

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

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

事前準備

部署 OAuth 2.0 Proxy

查看 OAuth 2.0 流程和政策

全新 Proxy 編輯器

傳統 Proxy 編輯器

建立受保護的 API Proxy

查看政策

全新 Proxy 編輯器

傳統 Proxy 編輯器

新增 API 產品

將開發人員和應用程式新增至貴機構

建立開發人員

註冊應用程式

取得用戶端金鑰和密鑰

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

取得 OAuth 2.0 存取權杖

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

相關主題

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