使用 OAuth 保護 API

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

課程內容

  • 下載並部署範例 API Proxy。
  • 建立受 OAuth 保護的 API Proxy。
  • 建立產品、開發人員和應用程式。
  • 交換 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 帳戶,可以按照建立 Apigee Edge 帳戶中的操作說明進行註冊。
  • 機器上安裝的 cURL,以便透過指令列發出 API 呼叫。

下載及部署權杖產生 API Proxy

在這個步驟中,您將建立 API Proxy,該 Proxy 會從 API 呼叫中傳送的用戶端金鑰和用戶端密鑰產生 OAuth 存取權杖。Apigee 提供了範例 API Proxy 來執行這項作業。您可以先下載並部署 Proxy,稍後在教學課程中使用。(您可以輕鬆地自行建構這個 API Proxy。這個下載及部署步驟很方便,而且會告訴您如何輕鬆共用已建立的 Proxy。)

  1. 將「oauth」範例 API Proxy 範例 ZIP 檔案下載至檔案系統中的任何目錄。
  2. 前往 https://apigee.com/edge 並登入。
  3. 在左側導覽列中,依序選取「Develop」(開發) >「API Proxy」
  4. 按一下「+ Proxy」
    「建立 Proxy」按鈕
  5. 在「建立 Proxy」精靈中,按一下「上傳 Proxy 組合」
  6. 選擇您下載的 oauth.zip 檔案,然後按一下「Next」
  7. 點選「建立」
  8. 建構完成後,按一下「Edit Proxy」,即可在 API Proxy 編輯器中查看新 Proxy。
  9. 在 API Proxy 編輯器總覽頁面中,按一下「Deployment」下拉式選單,然後選取「test」。這是貴機構的測試環境。

    在確認提示中,按一下「部署」
    再次點選「Deployment」下拉式選單時,綠色圖示表示 Proxy 已部署至測試環境。

恭喜!您已成功將產生存取權杖的 API Proxy 並部署至 Edge 機構。

查看 OAuth 流程和政策

讓我們進一步瞭解 API Proxy 的內容。

  1. 在 API Proxy 編輯器中,按一下「Develop」分頁標籤。左側「Navigator」窗格中會顯示兩項政策。您也會在 Proxy Endpoints 區段中看到兩個 POST 資料流。
  2. 按一下 Proxy Endpoints 下方的「AccessTokenClientCredential」AccessTokenClientCredential

    在 XML 程式碼檢視畫面中,您會看到名為 AccessTokenClientCredentialFlow

    <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> 元素會指示政策要在何處查看授權類型參數的 API 呼叫 (依 OAuth 2.0 規格要求)。(您稍後會在 API 呼叫中看到這個項目)。授權類型也可以透過 HTTP 標頭 (request.header.grant_type) 或表單參數 (request.formparam.grant_type) 傳送。

您目前不需要使用 API Proxy 執行其他操作。在後續步驟中,您將使用這個 API Proxy 產生 OAuth 存取權杖。不過,您必須先再完成幾個步驟:

  • 建立確實要使用 OAuth 保護的 API Proxy。
  • 再建立一些構件,您會產生需要的用戶端金鑰和用戶端密鑰來交換存取權杖。

建立受 OAuth 保護的 API Proxy

關於「模擬目標」

mocktarget 服務由 Apigee 託管,並傳回簡單資料。事實上,您可以透過網路瀏覽器存取。請點選下列按鈕來試用:

http://mocktarget.apigee.net/ip

當您最終呼叫這個 API Proxy 時,目標會傳回應顯示的內容。

您也可以點選 http://mocktarget.apigee.net/help,查看 mocktarget 提供的其他 API 資源。

接下來要建立要保護的 API Proxy。這是會傳回所需項目的 API 呼叫。在這種情況下,API Proxy 會呼叫 Apigee 的模擬目標服務以傳回您的 IP 位址。但是,只有在您透過 API 呼叫傳遞有效的 OAuth 存取權杖時,才會看到這個項目。

您在這裡建立的 API Proxy 會包含政策,檢查要求中的 OAuth 權杖。

  1. 在左側導覽列中,依序選取「Develop」(開發) >「API Proxy」
  2. 按一下「+ Proxy」
    「建立 Proxy」按鈕
  3. 在「建構 Proxy」精靈中選取「反向 Proxy (最常用)」,然後點選「下一步」
  4. 使用下列設定 Proxy:
    這個欄位中 採取行動
    Proxy 名稱 輸入:helloworld_oauth2
    專案基本路徑

    變更為:/hellooauth2

    專案基本路徑是網址的一部分,用於向 API Proxy 提出要求。

    現有 API

    輸入:https://mocktarget.apigee.net/ip

    這會定義 Apigee Edge 針對傳送至 API Proxy 的要求叫用的目標網址。

    說明 輸入:hello world protected by OAuth
  5. 按一下「Next」
  6. 在「常見政策」頁面中:
    這個欄位中 採取行動
    安全性:授權 選取:OAuth 2.0
  7. 按一下「Next」
  8. 在「Virtual Hosts」頁面中,按一下「Next」
  9. 在「Build」頁面中,確定已選取「test」環境,然後按一下「Create and Deploy」
  10. 您會在「摘要」頁面上看到已成功建立新的 API Proxy,且該 API Proxy 已部署至測試環境的確認通知。
  11. 按一下「編輯 Proxy」,開啟 API Proxy 的「總覽」頁面。
    請注意,系統這次會自動部署 API Proxy。按一下「Deployment」下拉式選單,確認「test」環境旁有綠色的部署作業圓點。

查看政策

接著就來看看您建立的內容。

  1. 在 API Proxy 編輯器中,按一下「Develop」分頁標籤。接著您會看到兩項政策已新增至 API Proxy 的要求流程:
    • 「Verify OAuth v2.0 Access Token」- 檢查 API 呼叫,確認是否具備有效的 OAuth 權杖。
    • 「Remove Header Authorization」 – 這個 AssignMessage 政策會在勾選後移除存取權杖,避免它無法傳送至目標服務。(如果目標服務需要 OAuth 存取權杖,則不會使用這項政策)。
  2. 按一下流程檢視畫面中的「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 權杖。

新增 API 產品

如要透過 Apigee UI 新增 API 產品,請按照下列步驟操作:

  1. 依序選取「發布」>「API 產品」
  2. 按一下「+API 產品」
  3. 輸入 API 產品的「產品詳細資料」
    欄位 說明
    名稱 API 產品的內部名稱。請勿在名稱中指定特殊字元。
    注意:API 產品建立後,就無法再編輯名稱。例如,helloworld_oauth2-Product
    顯示名稱 API 產品的顯示名稱。UI 會使用這個顯示名稱,您隨時可以編輯。如未指定,系統會使用「Name」值。這個欄位會自動填入「名稱」值,您可以編輯或刪除其中的內容。顯示名稱可包含特殊字元。例如 helloworld_oauth2-Product
    說明 API 產品的說明。
    環境 API 產品允許存取的環境。請選取您已部署 API Proxy 的環境。例如 test
    存取權 選取「公開」
    自動核准存取要求 啟用自動核准從任何應用程式對這個 API 產品提出的金鑰要求。
    配額 略過本教學課程。
    允許的 OAuth 範圍 略過本教學課程。
  4. 在「API Proxy」欄位中,選取您剛建立的 API Proxy。
  5. 在「Path」欄位中輸入「/」。忽略其他欄位。
  6. 點按「儲存」

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

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

開發人員擁有一或多個呼叫您 API 的應用程式,每個應用程式都會取得專屬的用戶端金鑰和用戶端密鑰。此外,由於 Edge 知道哪個開發人員和應用程式屬於哪個 OAuth 權杖,因此 API 供應商也能更精細地控管您的 API 存取權,以及更精細的 API 流量數據分析報表。

建立開發人員

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

  1. 在選單中依序選取「發布」>「開發人員」
  2. 按一下「+ 開發人員」
  3. 在「New Developer」視窗中輸入以下內容:
    這個欄位中 Enter 鍵
    名字 Nigel
    姓氏 Tufnel
    使用者名稱 nigel
    電子郵件 nigel@example.com
  4. 點選「建立」

註冊應用程式

我們來為 Nigel 製作應用程式吧!

  1. 依序選取「發布」>「應用程式」
  2. 按一下「+ 應用程式」
  3. 在「New App」視窗中輸入以下內容:
    這個欄位中 採取行動
    名稱顯示名稱 輸入:nigel_app
    開發人員 按一下「開發人員」,然後選取:Nigel Tufnel (nigel@example.com)
    回呼網址備註 留空
  4. 按一下「產品」下方的「新增產品」
  5. 選取「helloworld_oauth2-Product」
  6. 點選「建立」

取得用戶端金鑰和用戶端密鑰

您現在可以取得用戶端金鑰和用戶端密鑰,用來交換 OAuth 存取權杖。

  1. 確認 nigel_app 頁面已顯示。如果沒有,請在「應用程式」頁面 (「發布」>「應用程式」) 中,按一下「nigel_app」nigel_app
  2. 在 nigel_app 頁面的「Key」和「Secret」欄中,按一下「Show」。請注意,金鑰/密鑰與先前自動建立的「helloworld_oauth2-Product」相關聯。

  3. 選取並複製金鑰和密鑰。將這些內容貼到暫存文字檔中。您將在後續步驟中用到這些憑證,以便呼叫 API Proxy,以便交換這些憑證來取得 OAuth 存取權杖。

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

請先嘗試呼叫受保護的 API Proxy,這個 Proxy 應會傳回您的 IP 位址。在終端機視窗中執行下列 cURL 指令,並替換成您的 Edge 機構名稱。網址中的 test 是貴機構的測試環境,也就是您部署 Proxy 的目標環境。Proxy 基本路徑為 /hellooauth2,與您在建立 Proxy 時指定的基本路徑相同。 請注意,您並未在呼叫中傳遞 OAuth 存取權杖。

curl https://ORG_NAME-test.apigee.net/hellooauth2

由於 API Proxy 具有「驗證 OAuth v2.0 存取權杖」政策來檢查要求中的有效 OAuth 權杖,因此呼叫應會失敗並顯示下列訊息:

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

在本例中,失敗就代表失敗了!這代表 API Proxy 更加安全。只有具備有效 OAuth 存取權杖的可信任應用程式,才能成功呼叫這個 API。

取得 OAuth 存取權杖

我們現在見證豐碩的成果。您即將使用複製並貼到文字檔中的金鑰和密鑰,並以金鑰和密鑰交換 OAuth 存取權杖。接下來,您要對匯入的 API 範例 Proxy (oauth) 進行 API 呼叫,這個 Proxy 會產生 API 存取權杖。

使用該金鑰和密鑰進行以下 cURL 呼叫 (請注意,通訊協定為 https),請將您的 Edge 機構名稱、金鑰和密鑰替換成註明值:

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

請注意,如果您是透過 Postman 這類用戶端進行呼叫,client_idclient_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 存取權杖!複製 access_token 值 (不含引號),然後貼到文字檔案中。稍後會用到。

剛剛發生了什麼事?

請記住,您在 oauth Proxy 中查看該條件流程時,如果資源 URI 為 /accesstoken,且要求動詞為 POST,則在執行 GenerateAccessTokenClient OAuth 政策時會產生存取權杖嗎?您的 cURL 指令符合這些條件,因此系統已執行 OAuth 政策。該金鑰會驗證您的用戶端金鑰和用戶端密鑰,並將其交換為 1 小時後到期的 OAuth 權杖。

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

現在您已取得存取權杖,可以用來呼叫 API Proxy。請執行下列 cURL 呼叫。替換成您的 Edge 機構名稱和存取權杖。

curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"

現在,您應該可以成功呼叫傳回您 IP 位址的 API Proxy。範例如下:

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

您可以重複這個 API 呼叫大約 1 小時,之後存取權杖就會過期。如要在一小時後發出呼叫,您必須使用前述步驟產生新的存取權杖。

恭喜!您建立了 API Proxy,並要求在呼叫中加入有效的 OAuth 存取權杖,藉此保護該 Proxy。

相關主題