透過使用者 ID 和/或應用程式 ID 啟用擷取及撤銷 OAuth 2.0 存取權杖的功能

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

本節說明如何依據使用者 ID、應用程式 ID 或兩者,啟用擷取及撤銷 OAuth 2.0 存取權杖的功能。如本主題所述,使用者 ID 功能需要進行特殊設定。根據使用者,是指呼叫 API 的應用程式使用者。

啟用使用者 ID 存取權的時機

有時候,將使用者 ID 儲存在存取權杖中會很有用。請只在有正當用途時啟用 User ID 存取權功能。例如:

  • 網站或應用程式的功能,可讓使用者查看自己獲得授權的第三方應用程式,以及提供撤銷這些應用程式存取權的選項。
  • 這項功能可讓授權使用者撤銷與特定開發人員應用程式相關聯的所有存取權杖。

關於 OAuth 存取權杖

應用程式 ID 會自動新增至 OAuth 存取權杖。因此,按照下列說明為機構啟用權杖存取權後,即可依應用程式 ID 撤銷存取權杖。

如要依據使用者 ID 擷取及撤銷 OAuth 2.0 存取權杖,存取權杖必須包含使用者 ID。以下程序說明如何將使用者 ID 新增至現有權杖。

根據預設,當 Edge 產生 OAuth 2.0 存取權杖時,權杖的格式如下:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

請注意:

  • application_name 欄位包含與權杖相關聯的應用程式的 UUID。如果您依應用程式 ID 啟用擷取及撤銷 OAuth 2.0 存取權杖的功能,這就是您使用的應用程式 ID。
  • access_token 欄位包含 OAuth 2.0 存取權杖值。

預設 OAuth 存取權杖中沒有使用者 ID 欄位。如要依據使用者 ID 擷取及撤銷 OAuth 2.0 存取權杖,您必須按照下列程序設定 OAuth 2.0 政策,在權杖中加入使用者 ID。請注意,如果您只想依據應用程式 ID 擷取及撤銷 OAuth 2.0 存取權杖,就不需要依據使用者 ID 啟用存取權。

然後將使用者 ID 傳入權杖建立端點。您可以將使用者的 ID 做為查詢參數、表單參數或標頭中傳遞 (如本主題後續章節所述)。設定 Edge 以在權杖中加入使用者 ID 之後,系統就會將該 ID 納入 app_enduser 欄位,如下所示:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

如要瞭解如何建立執行這些擷取和撤銷的 API 呼叫,請參閱下列智慧文件:

依據使用者 ID 和應用程式 ID 啟用 OAuth 2.0 權杖的存取權

如何依據使用者 ID 和應用程式 ID 啟用 OAuth 2.0 權杖的存取權,取決於您部署 Edge 的方式:

  • 雲端式部署

    以雲端為基礎的 Edge 部署作業,因此大多數的設定都是由 Apigee 處理。您只需設定 OAuth 2.0 政策,將使用者 ID 新增至存取權杖。詳情請參閱以下程序。

  • 私有雲部署邊緣

    在 Apigee Edge for Private Cloud (地端部署) 中,您必須完全負責設定。詳情請參閱作業與設定

  • Apigee Hybrid

    根據預設,系統會依使用者 ID 啟用 OAuth 2.0 權杖的存取權。您只需設定 OAuth 2.0 政策,將使用者 ID 新增至存取權杖。詳情請參閱下方程序的步驟 5。

在雲端啟用存取權

步驟 1:為機構啟用這項功能

您必須為每個要支援這項功能的機構啟用這項功能。

Apigee Edge 支援團隊聯絡,請對方更新貴機構。

步驟 2:將 oauth2 資源權限提供給 opsadmin 和 orgadmin 角色

只有 orgadminopsadmin 角色應取得相關權限,才能進行這些擷取 (get),以及根據使用者 ID 或應用程式 ID 撤銷 (put) 對 oauth2 資源的呼叫。

您可以使用 Get Permission for a Resource API 呼叫,查看哪些角色具備 oauth2 資源的 getput 權限。

如果您需要新增或移除任何權限,請與 Apigee Edge 支援團隊聯絡,請對方執行更新。

步驟 3:將現有的 OAuth 2.0 存取權杖複製到 Cassandra 節點

由 Apigee 支援執行:在這項工作中,系統會複製受影響機構中現有 OAuth 2.0 存取權杖的複本,並儲存在 Cassandra 節點中。這項程序將在每個 Apigee Edge Pod 的 Cassandra 節點上執行。這麼做可讓擷取及撤銷 API 呼叫,並針對所有 OAuth 2.0 存取權杖 (現有和新產生的權杖) 執行。

步驟 4:將 oauth_max_search_limit 屬性新增至管理伺服器和訊息處理器

在這項工作中,管理伺服器和訊息處理器的 keymanagement.properties 檔案會更新,加入這項屬性:oauth_max_search_limit = 100100 是 Apigee 的建議值,但您也可以視需要設定。

請與 Apigee Edge 支援團隊聯絡,要求他們新增這項解決方案。

步驟 5:設定 OAuth 2.0 政策,產生含有使用者 ID 的存取權杖

設定用來產生存取權杖的 OAuth 2.0 政策,在權杖中加入使用者 ID。將使用者 ID 納入存取權杖後,您就能依據使用者 ID 執行擷取和撤銷作業。

如要設定政策,在存取權杖中加入使用者 ID,您必須指定包含使用者 ID 的輸入變數。使用 <AppEndUser> 標記指定變數。

下列名為 GenerateAccessTokenClient 的 OAuth 2.0 政策會產生 OAuth 2.0 存取權杖。請注意,新增的 <AppEndUser> 標記 (以粗體表示):

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GenerateAccessTokenClient">
  <DisplayName>OAuth 2.0.0 1</DisplayName>
  <ExternalAuthorization>false</ExternalAuthorization>
  <Operation>GenerateAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <GrantType>request.queryparam.grant_type</GrantType>
  <AppEndUser>request.header.appuserID</AppEndUser>
  <ExpiresIn>960000</ExpiresIn>
</OAuthV2>

接著,您可以使用下列 cURL 指令產生 OAuth 2.0 存取權杖,並將使用者 ID 做為 appuserID 標頭傳遞:

curl -H "appuserID:6ZG094fgnjNf02EK" /
  https://myorg-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials /
  -X POST /
  -d 'client_id=k3nJyFJIA3p62TKIkLO6OJNi87GYXFmP&client_secret=gk58jK5lIp943AY4'

在這個範例中,appuserID 會以要求標頭的形式傳遞。您可以透過多種方式在要求中傳送資訊。舉例來說,您可以採用下列做法:

  • 使用表單參數變數:request.formparam.appuserID
  • 使用提供使用者 ID 的流程變數