OAuth

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

OAuth 已成為 API 的主要授權通訊協定。本文將詳細說明 OAuth 版本,詳情請參閱 OAuth 2.0 規格

OAuth 是一種通訊協定,可讓應用程式使用者授權「應用程式」代為執行動作。應用程式只要從 API 供應商取得存取權杖即可。API 供應商會驗證應用程式的使用者憑證,確保使用者已授權應用程式,然後向應用程式發出存取權杖。當應用程式使用受保護的 API 時,Apigee Edge 會檢查存取權杖,確認其是否有效且尚未過期。API 供應商必須公開端點,讓應用程式取得存取權杖。

為讓您輕鬆開始使用 OAuth,Apigee Edge 可讓您運用 政策設定和強制執行 OAuth,而不必編寫任何程式碼。在本主題中,您將瞭解如何保護 API、如何取得存取權杖,以及如何透過這些存取權杖存取受保護的 API。

貴機構的預設 OAuth 設定

為方便起見,Apigee Edge 上的所有機構都已預先設定一組實作用戶端憑證授權類型的 OAuth 2.0 端點。用戶端憑證授權類型會定義為交換應用程式憑證而核發存取權杖的程序。這類應用程式憑證只是用戶端金鑰和密鑰配對,Apigee Edge 會針對機構中註冊的每個應用程式發生問題。「用戶端憑證」是指用戶端金鑰和密鑰配對本身。

如要進一步瞭解如何使用 Edge Developer Services 向應用程式核發憑證,請參閱「註冊應用程式及管理金鑰」。

因此,從 API 金鑰驗證到 OAuth 用戶端憑證,將 API 安全性配置「加速」相對簡單。這兩種配置使用相同的用戶端金鑰和密鑰來驗證用戶端應用程式。差別在於用戶端憑證提供多層控管機制,因為您可以視需要輕鬆撤銷存取權杖,而不必撤銷應用程式的用戶端金鑰。如要使用預設 OAuth 端點,您可以使用機構中應用程式產生的任何用戶端金鑰和密鑰,從權杖端點擷取存取權杖。(您甚至可以為已有用戶端金鑰和密鑰的應用程式啟用用戶端憑證)。

如要瞭解用戶端憑證授權的完整規格,請參閱 OAuth 2.0 規格

透過政策保護 API

使用存取權杖之前,您必須先將 API 設為在執行階段驗證 OAuth 存取權杖。如要這麼做,請設定 API Proxy 來validate存取權杖。換句話說,每次應用程式發出使用其中一個 API 的要求時,應用程式都必須提供有效的存取權杖,以及 API 要求。Apigee Edge 會負責處理產生、儲存及驗證系統顯示的存取權杖的複雜作業。

建立新的 API Proxy 時,您可以輕鬆將 OAuth 驗證新增至 API。建立新的 API Proxy 時,您可以新增功能。如下所示,您可以選取「透過 OAuth v2.0 存取權杖確保安全性」旁的圓形按鈕,新增 OAuth 2.0 存取權杖的驗證作業。選取這個選項後,系統會將兩項政策附加至新建立的 API Proxy,一個用於驗證存取權杖,另一個則是用來在經過驗證後移除存取權杖。

此外,當您選取「Secure with OAuth v2.0 Access Tokens」選項時,系統會自動勾選「Publish API Product」核取方塊並自動選取。如果您想在建構新的 API Proxy 時自動產生產品,請勾選這個選項。自動產生的產品將連結至新的 API Proxy。如要將現有產品與這個新 API 建立關聯,請務必取消勾選這個核取方塊,以免建立不必要的產品。如需產品相關資訊,請參閱「什麼是 API 產品?」一文

如要為現有的 API Proxy 啟用存取權杖驗證功能,只需將 OAuthV2 類型的政策附加至您要保護的 API 即可。OAuthV2 政策的運作方法是指定「作業」。若要驗證存取權杖,請指定名為 VerifyAccessToken 的作業。(OAuthV2 政策類型支援的其他作業類型為 GenerateAccessToken 和 GenerateRefreshToken. 並在設定 OAuth 端點時瞭解這些作業。)

驗證 OAuthV2 類型的 OAuthTokens 政策

驗證存取權杖的範例政策如下所示。(各項設定的說明如下表所示)。

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

政策設定

名稱 說明 預設 必填與否
OAuthV2 政策類型
name 政策名稱,在 API Proxy 端點設定中參照。 不適用
Operation OAuthV2 政策將要執行的作業。指定 VerifyAccessToken,即可完成政策設定,檢查存取權杖的要求、驗證存取權杖是否有效、尚未過期,並已獲準使用要求的 API 資源 (URI)。(針對這項檢查,這項政策會讀取應用程式獲準使用的 API 產品。) 不適用

如要在管理 UI 中建立這項政策,請依序前往「API」>「API Proxy」

從 API Proxy 清單中,選取「weatherapi」

在氣象 API 的「Overview」中,選取「Develop」檢視畫面。

在下拉式選單中,依序選取「New Policy」>「OAuth v2.0」

選取 OAuth v2.0 政策後,系統會顯示「New Policy」設定選單。

為政策提供一個描述性名稱,請務必在政策連結設定中選取「Attach Policy」、「Flow PreFlow」和「Request」設定。

選取「Add」,系統便會建立政策並附加至氣象 API 的要求 PreFlow。

新增政策後,下方的 PreFlow 設定會顯示在「Designer」窗格中。

如果是在本機使用文字編輯器或 IDE 工作,請將政策附加至要保護的 API Proxy 要求 PreFlow:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

將政策附加至要求 PreFlow,即可確保一律對所有要求訊息強制執行這項政策。

現在,您已使用 OAuth 2.0 用戶端憑證保護 API。下一步是瞭解如何取得存取權杖,以及如何使用權杖存取安全 API。

使用存取權杖來存取受保護的資源

由於 Weatherapi 受到 OAuth 2.0 保護,因此應用程式必須提供存取權杖才能使用 API。如要存取受保護的資源,應用程式會在要求中以 「Authorization」HTTP 標頭顯示存取權杖,如下所示:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

由於 API 已附加 OAuthV2 政策,因此 Apigee Edge 會驗證提供的存取權杖是否有效,然後授予 API 存取權,將天氣報告傳回提出要求的應用程式。

但應用程式如何取得存取權杖?詳情請見下一節。

如何交換用戶端憑證以存取存取權杖

應用程式會向權杖端點提供用戶端金鑰/密鑰配對,藉此取得存取權杖。權杖端點在名為 oauth 的 API Proxy 中設定。因此,應用程式必須呼叫 oauth API Proxy 公開的 API,才能取得存取權杖。應用程式取得存取權杖後,就能重複呼叫 Weatherapi,直到存取權杖過期或存取權杖撤銷為止。

現在,你必須改變自己的設計,將自己視為應用程式開發人員。您想要呼叫 Weatherapi,因此需要取得應用程式的存取權杖。首先,您需要取得「用戶端金鑰和密鑰配對」 (又稱為「API 金鑰」或「應用程式金鑰」)。

您可以在 Apigee 機構中註冊應用程式,藉此取得用戶端金鑰和密鑰。

您可以在 Apigee Edge 管理 UI 中查看貴機構的所有應用程式。

畫面上會隨即顯示貴機構中註冊的應用程式清單。

(如果未顯示任何應用程式,您可以在名為「註冊應用程式及管理 API 金鑰」的主題中註冊應用程式。)

從清單中選取應用程式,即可查看其詳細個人資料。

在所選應用程式的詳細資料檢視畫面中,記下「Consumer Key」(消費者金鑰) 和「Consumer Secret」(消費者密鑰) 欄位。這兩個值是您將用來取得 OAuth 存取權杖的用戶端憑證

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

此呼叫會根據應用程式 ID 傳回應用程式清單。

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

您可以對應用程式 ID 進行簡單的 GET 呼叫,藉此擷取應用程式的設定檔:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

例如:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

API 呼叫會傳回您指定的應用程式設定檔。舉例來說,weatherapp 的應用程式設定檔採用下列 JSON 表示法:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

請記下 consumerKeyconsumerSecret 的值。您可以在 HTTP 要求中以基本驗證憑證的形式提供這些憑證,藉此取得存取權杖,如下所示。授權類型會以查詢參數的形式顯示在要求中。(請務必變更「{org_name}」變數的值,以反映您在 Apigee Edge 上的機構名稱)。

建立要求來取得存取權杖

在後續要求中,將 client_id 替換為 consumerKey 的值。將 client_secret 替換成相關聯的 consumerSecret 值。

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

API 服務會驗證用戶端金鑰和密鑰,然後產生包含這個應用程式存取權杖的回應:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

請記下上方回應中的 access_token 值。這是應用程式用來取得受保護資源的執行階段存取權的存取權杖。這個應用程式的存取權杖為 ylSkZIjbdWybfs4fUQe9BqP0LH5Z

您現在擁有有效的存取權杖 ylSkZIjbdWybfs4fUQe9BqP0LH5Z,可以用來存取受保護的 API。

使用預設 OAuth 設定

在 Apigee Edge 中,每個機構 (甚至是免費試用機構) 都會使用 OAuth 權杖端點佈建。端點已在 API Proxy 中名為 oauth 的政策設定。當您在 Apigee Edge 中建立帳戶後,即可開始使用權杖端點。

預設的 OAuth 端點會顯示下列端點 URI:

/oauth/client_credential/accesstoken

請將這個 URI 發布給需要取得存取權杖的開發人員。應用程式開發人員會將應用程式設為呼叫這個端點,並呈現用戶端金鑰和密鑰配對來取得存取權杖。

預設用戶端憑證權杖端點會透過網路公開於下列網址:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

舉例來說,如果機構名稱是「apimakers」,網址會是:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

這是開發人員呼叫的網址,用來取得存取權杖。

三足式 OAuth 設定

三足式 OAuth 設定 (授權碼、隱式與密碼授權類型) 需要 API 供應商來驗證應用程式使用者。由於每個機構會以不同的方式驗證使用者,因此必須自訂政策或編寫程式碼,才能將 OAuth 與您的使用者存放區整合。舉例來說,您的所有使用者可能會儲存在 Active Directory、LDAP 或其他使用者儲存庫中。如要啟動並執行三足式 OAuth,您必須將使用者存放區的檢查機制整合至整體 OAuth 流程。

OAuth 1.0a

如要進一步瞭解 OAuth 1.0a 政策,請參閱 OAuth v1.0a 政策

取得協助

相關說明請參閱 Apigee 客戶服務相關說明。