撤銷 OAuth V2 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

總覽

撤銷與開發人員應用程式 ID 或應用程式使用者 ID 相關聯的 OAuth2 存取權杖 (或兩者皆撤銷)。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

使用 OAuthv2 政策產生 OAuth 2.0 存取權杖。Apigee 產生的權杖格式如下：

{
  "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 元素包含與權杖相關聯的開發人員應用程式 ID。

根據預設，Apigee 不會在權杖中加入使用者 ID。您可以將 <AppEndUser> 元素新增至 OAuthv2 政策，藉此設定 Apigee 納入使用者 ID：

<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessToken</Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>

在這個範例中，您可以在名為 app_enduser 的查詢參數中，將使用者 ID 傳遞至 OAuthv2 政策。接著，系統會在 app_enduser 元素的權杖中加入使用者 ID：

{
 "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"
}

依開發人員應用程式 ID 撤銷

撤銷與開發人員應用程式 ID 相關聯的 OAuth2 存取權杖。所有由 Apigee 產生的 OAuth2 存取權權杖都包含與權杖相關聯的開發人員應用程式 ID。接著，您可以根據該應用程式 ID 撤銷權杖。

如要取得特定開發人員的應用程式 ID 清單，請使用：

依應用程式使用者 ID 撤銷

撤銷與特定應用程式使用者 ID 相關聯的 OAuth2 存取權杖。這是與已核發權杖的使用者 ID 相關聯的權杖。

根據預設，OAuth 存取權杖中沒有使用者 ID 欄位。如要啟用撤銷 OAuth 2.0 存取權杖的使用者 ID，您必須設定 OAuthv2 政策，讓權杖中包含使用者 ID，如上圖所示。

如要取得應用程式使用者 ID，請使用 方法：organizations.developers.get。

範例

以下範例使用「撤銷 OAuth 2.0」政策來撤銷 OAuth 2.0 存取權杖。

開發人員應用程式 ID

如要根據開發人員應用程式 ID 撤銷存取權存取權杖，請在政策中使用 <AppId> 元素。

以下範例預期會在名為 app_id 的查詢參數中，找到存取權杖的開發人員應用程式 ID：

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>

政策會根據開發人員應用程式的 ID 撤銷存取權杖。

在時間戳記前撤銷

如要撤銷在特定日期和時間之前產生的開發人員應用程式 ID 所產生的存取權權杖，請在政策中使用 <RevokeBeforeTimestamp> 元素。<RevokeBeforeTimestamp> 以毫秒為單位指定世界標準時間 Epoch 時間。系統會撤銷所有在該日期之前核發的權杖。

以下範例會撤銷 2019 年 7 月 1 日前建立的開發人員應用程式存取權杖：

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>

<RevokeBeforeTimestamp> 元素會採用 64 位元 (長) 整數，代表自世界標準時間 1970 年 1 月 1 日午夜起經過的毫秒數。

元素參考

元素參考資料說明瞭 RevokeOAuthV2 政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>

<RevokeOAuthV2> 屬性

<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續。

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<AppId> 元素

指定要撤銷權杖的開發人員應用程式 ID。傳遞含有應用程式 ID 的變數或應用程式 ID 字面值。

<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>
預設

request.formparam.app_id (x-www-form-url-encoded，並在要求主體中指定)
存在必要性

選用
類型 字串
有效值

包含應用程式 ID 字串的流程變數，或字面字串。

<Cascade> 元素

如果 true 和您有傳統的非透明存取權杖，當 <AppId> 或 <EndUserId> 相符時，系統會撤銷更新權杖和存取權杖。如果您有 JWT 存取權杖，則只有使用存取權杖核發的重新整理權杖會遭到撤銷。根據設計，JWT 存取權杖無法撤銷。如果是 false，則只會撤銷存取權杖，更新權杖則不會變更。這項行為僅適用於不透明存取權杖。無法撤銷 JWT 存取權杖。

<Cascade>false<Cascade>
預設

false
存在必要性

選用
類型 布林值
有效值 true 或 false

<EndUserId> 元素

指定要撤銷的憑證應用程式使用者 ID。傳遞包含使用者 ID 的變數或字面值符號字串。

<EndUserId>userIdString</EndUserId>

or:

<EndUserId ref="request.queryparam.access_token"></EndUserId>
預設

request.formparam.enduser_id (x-www-form-urlencoded，並在要求主體中指定)
存在必要性

選用
類型 字串
有效值

包含使用者 ID 字串的流程變數，或字面字串。

<RevokeBeforeTimestamp> 元素

撤銷在時間戳記之前核發的權杖。這個元素可搭配 <AppId> 和 <EndUserId> 使用，讓您在特定時間前撤銷權杖。預設值是政策執行的時間。

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>
預設

政策執行的時間戳記。
存在必要性

選用
類型 64 位元 (長) 整數，代表自世界標準時間 1970 年 1 月 1 日午夜起經過的毫秒數。
有效值

包含時間戳記的流程變數，或時間戳記文字。時間戳記不得為未來的時間，也不得早於 2014 年 1 月 1 日。

流程變數

RevokeOAuthV2 政策不會設定流程變數。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。下方顯示的錯誤名稱是發生錯誤時，指派給 fault.name 變數的字串。詳情請參閱下方的「錯誤變數」一節。

錯誤代碼 HTTP 狀態 原因
steps.oauth.v2.InvalidFutureTimestamp 500 時間戳記不得為未來的時間。
steps.oauth.v2.InvalidEarlyTimestamp 500 時間戳記不得早於 2014 年 1 月 1 日。
steps.oauth.v2.InvalidTimestamp 500 時間戳記無效。
steps.oauth.v2.EmptyAppAndEndUserId 500 AppdId 和 EndUserId 皆不得留空。

部署錯誤

請參閱 UI 中回報的訊息，瞭解部署錯誤。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統會設定這些變數。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GetTokenInfo.cause = ClientID is Invalid

錯誤回應範例

{
   "fault":{
      "faultstring":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}

錯誤規則範例

<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>

相關主題