本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
RevokeOAuthV2 政策會撤銷與開發人員應用程式 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 清單,請使用:
- 方法:organizations.developers.apps.list API,可取得與開發人員相關聯的應用程式清單。
- 方法:organizations.developers.apps.get API,可取得應用程式詳細資料,包括應用程式 ID。
依應用程式使用者 ID 撤銷
撤銷與特定應用程式使用者 ID 相關聯的 OAuth2 存取權杖。這是與權杖核發對象使用者 ID 相關聯的權杖。
根據預設,OAuth 存取權杖中沒有使用者 ID 欄位。如要讓使用者 ID 能夠撤銷 OAuth 2.0 存取權杖,您必須設定 OAuthv2 政策,在權杖中加入使用者 ID,如上所示。
如要取得應用程式使用者 ID,請使用方法:organizations.developers.get。
範例
下列範例使用 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 |
政策的內部名稱。 您可以選擇使用 |
不適用 | 必填 |
continueOnError |
將其設為 將其設為 |
false | 選用 |
enabled |
設為 設為 |
是 | 選用 |
<DisplayName> 元素
除了 name 屬性之外,您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。
<DisplayName>Policy Display Name</DisplayName>
| 預設 |
不適用 如果省略這個元素,系統會使用政策的 |
|---|---|
| 存在必要性 | 選用 |
| 類型 | 字串 |
<AppId> 元素
指定要撤銷權杖的開發人員應用程式 ID。傳遞包含應用程式 ID 的變數,或傳遞應用程式 ID 常值。
<AppId>appIdString</AppId> or: <AppId ref="request.queryparam.app_id"></AppId>
| 預設 |
|
|---|---|
| 狀態 |
選用 |
| 類型 | 字串 |
| 有效值 |
包含應用程式 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>
| 預設 |
|
|---|---|
| 狀態 |
選用 |
| 類型 | 字串 |
| 有效值 |
包含使用者 ID 字串的流程變數,或字串常值。 |
<RevokeBeforeTimestamp> 元素
撤銷時間戳記之前核發的權杖。這個元素會與 <AppId> 和 <EndUserId> 搭配運作,讓您在特定時間前撤銷權杖。預設值為政策執行時間。
<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp> or: <RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>
| 預設 |
政策的執行時間戳記。 |
|---|---|
| 狀態 |
選用 |
| 類型 | 64 位元 (長) 整數,代表自世界標準時間 1970 年 1 月 1 日午夜起經過的毫秒數。 |
| 有效值 |
包含時間戳記的流程變數,或時間戳記常值。 時間戳記不得為未來的時間,也不得早於 2014 年 1 月 1 日。 |
流程變數
RevokeOAuthV2 政策不會設定流程變數。
錯誤參考資料
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes. The error names shown below are the strings
that are assigned to the fault.name variable when an error occurs. See the Fault
variables section below for more details.
| Fault code | HTTP status | Cause |
|---|---|---|
steps.oauth.v2.InvalidFutureTimestamp |
500 | Timestamp cannot be in the future. |
steps.oauth.v2.InvalidEarlyTimestamp |
500 | Timestamp cannot be earlier than January 1, 2014. |
steps.oauth.v2.InvalidTimestamp |
500 | Timestamp is invalid. |
steps.oauth.v2.EmptyAppAndEndUserId |
500 | Both AppdId and EndUserId cannot be empty. |
Deployment errors
Refer to the message reported in the UI for information about deployment errors.
Fault variables
These variables are set when this policy triggers an error at runtime.
| Variables | Where | Example |
|---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "IPDeniedAccess" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetTokenInfo.failed = true |
oauthV2.policy_name.fault.name |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id |
oauthV2.policy_name.fault.cause |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetTokenInfo.cause = ClientID is Invalid |
Example error response
{
"fault":{
"faultstring":"Timestamp is in the future.",
"detail":{
"errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
}
}
}Example fault rule
<FaultRule name="RevokeOAuthV2 Faults">
<Step>
<Name>AM-InvalidTimestamp</Name>
</Step>
<Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>