撤銷 OAuth V2 政策

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

政策圖示

總覽

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

使用 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>GenerateAccessTokenV/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 相關聯的 OAuth2 存取權杖。這是與權杖核發對象使用者 ID 相關聯的權杖。

根據預設，OAuth 存取權杖中沒有使用者 ID 欄位。如要啟用依使用者 ID 撤銷 OAuth 2.0 存取權杖的功能，您必須設定 OAuthv2 政策，在權杖中加入使用者 ID，如上所示。

如要取得應用程式使用者 ID，請使用 Developer apps API。

範例

下列範例使用 Revoke OAuth V2 政策撤銷 OAuth2 存取權杖。

開發人員應用程式 ID

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

在以下範例中，存取權杖的開發人員應用程式 ID 應位於名為 app_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 代理項目編輯器中，以其他自然語言名稱標記政策。

 N/A 必填
continueOnError

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

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

 false 選用
enabled

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

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

 true 選用
async

這項屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性，您也可以使用這個屬性，在管理 UI 代理項目編輯器中，以其他自然語言名稱標示政策。

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

N/A

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

<AppId> 元素

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

<AppId>appIdString</AppId>

or:

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

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

選用
類型 字串
有效值

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

<Cascade> 元素

如果 true 且您有傳統的不透明存取權杖，則如果 <AppId> 或 <EndUserId> 相符，更新權杖和存取權杖都會遭到撤銷。如果 false，則只會撤銷存取權杖，更新權杖不會變更。只有不透明存取權杖適用相同行為。

<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 政策不會設定流程變數。

錯誤參考資料

本節說明 Edge 在這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息，以及設定的錯誤變數。如果您要開發用來處理錯誤的錯誤規則，就必須瞭解這項資訊。如要瞭解詳情，請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤碼 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 皆不得留空。

部署錯誤

如要瞭解部署錯誤，請參閱使用者介面中回報的訊息。

錯誤變數

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

變數 地點 範例
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>

相關主題