OAuth

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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 開發人員服務核發應用程式憑證，請參閱「註冊應用程式及管理金鑰」。

因此，從 API 金鑰驗證「升級」至 OAuth 用戶端憑證的 API 安全性架構相對簡單。這兩種機制都使用相同的用戶端金鑰和密碼來驗證用戶端應用程式。不同之處在於，用戶端憑證提供額外的控制層，因為您可以在需要時輕鬆撤銷存取權杖，不必撤銷應用程式的用戶端金鑰。如要使用預設的 OAuth 端點，您可以透過為貴機構應用程式產生的任何用戶端金鑰和密鑰，從權杖端點擷取存取權杖。(您甚至可以為已具備消費者金鑰和密鑰的應用程式啟用用戶端憑證)。

如要查看用戶端憑證授權的完整規格，請參閱 OAuth 2.0 規格。

使用政策保護 API

您必須先設定 API，在執行階段驗證 OAuth 存取權杖，才能使用存取權杖。如要這麼做，請設定 API Proxy 來驗證存取權杖。也就是說，應用程式每次要求使用您的 API 時，都必須在 API 要求中提供有效的存取權杖。Apigee Edge 會處理產生、儲存及驗證所提供存取權杖的複雜作業。

建立新的 API Proxy 時，您可以輕鬆將 OAuth 驗證新增至 API。建立新的 API Proxy 時，您可以新增功能。如下所示，選取「Secure with OAuth v2.0 Access Tokens」(使用 OAuth 2.0 存取權杖確保安全) 旁的單選按鈕，即可新增 OAuth 2.0 存取權杖的驗證。選取這個選項後，系統會將兩項政策附加至新建立的 API Proxy，一項用於驗證存取權杖，另一項則用於在驗證後移除存取權杖。

此外，選取「使用 OAuth v2.0 存取權杖保護安全」選項後，「發布 API 產品」核取方塊會變成可選取狀態，並自動勾選。如要在建構新的 API Proxy 時自動產生產品，請勾選這個選項。系統會建立自動產生的產品，並與新的 API Proxy 建立關聯。如果您有要與這個新 API 建立關聯的現有產品，請務必取消勾選這個核取方塊，以免建立不必要的產品。如要瞭解產品，請參閱「什麼是 API 產品？」一文。

如要為現有的 API Proxy 啟用存取權杖驗證，只要將 OAuthV2 類型的政策附加至要保護的 API 即可。OAuthV2 政策會指定作業。如要驗證存取權杖，請指定名為「VerifyAccessToken」 VerifyAccessToken的作業。(OAuthV2 政策類型支援的其他作業類型包括 GenerateAccessToken 和 GenerateRefreshToken。設定 OAuth 端點時，您會瞭解這些作業。

OAuthV2 類型的 VerifyOAuthTokens 政策

以下是驗證存取權杖的政策範例。(下表說明這些設定)。

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

政策設定

名稱 說明 預設 是否必要？
OAuthV2 政策類型
name 政策名稱，API Proxy 端點設定會參照這個名稱。 N/A 是
Operation OAuthV2 政策要執行的作業。指定 VerifyAccessToken，即可設定政策來檢查要求中的存取權杖，並驗證存取權杖是否有效、未過期，且已獲准使用所要求的 API 資源 (URI)。(為進行這項檢查，這項政策會讀取應用程式獲准使用的 API 產品)。 N/A 是

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

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

在 weatherapi 的「總覽」中，選取「開發」檢視畫面。

從下拉式選單中，選取「New Policy」>「OAuth v2.0」

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

為政策命名，並務必選取「附加政策」、「流程 PreFlow」和「要求」做為政策附加設定。

選取「新增」，系統就會建立政策並附加至 weatherapi 的要求前置流程。

新增政策後，下方的要求 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 Edge 註冊機構的應用程式，請取得用戶端金鑰和密鑰。

您可以在 Apigee Edge 管理使用者介面中查看機構中的所有應用程式。

系統會顯示貴機構已註冊的應用程式清單。

(如果沒有顯示任何應用程式，請參閱「註冊應用程式及管理 API 金鑰」一節，瞭解如何註冊應用程式)。

從清單中選取應用程式，即可查看詳細設定檔。

在所選應用程式的詳細資料檢視畫面中，記下「用戶端金鑰」和「用戶端密鑰」欄位。這兩個值是用戶端憑證，可用於取得 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"
}

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

建立要求以取得存取權杖

在下列要求中，請將 client_id 替換為 consumerKey 的值。將關聯 consumerSecret 的值代入 client_secret。

$ 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 權杖端點。端點已在名為 oauth 的 API Proxy 中預先設定政策。在 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 客戶支援」。