本頁面由 Cloud Translation API 翻譯而成。

撤銷 OAuth V2 政策

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

總覽

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

注意： RevokeOAuthV2 不適用於私人雲端適用的 Apigee Edge。

使用 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 政策。接著，系統會將使用者 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"
}

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

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

使用 Developer apps API 取得特定開發人員的應用程式 ID 清單。
您也可以使用 Developer apps API 取得應用程式的詳細資料。

依應用程式使用者 ID 撤銷

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

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

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

範例

以下範例使用「撤銷 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` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	true	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

無

如果省略這個元素，系統會使用政策的 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> 相符時，系統會撤銷更新權杖和存取權杖。如果是 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-url-encoded，並在要求主體中指定)
存在必要性	選用
類型	字串
有效值	包含使用者 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 傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。下方顯示的錯誤名稱是發生錯誤時，指派給 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>