GetOAuthV2Info 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

取得存取權杖、更新權杖、授權碼和用戶端應用程式的屬性 並在變數中填入這些屬性的值。

當您需要根據值設定動態的條件式行為時，這項政策就非常實用 憑證或驗證碼只要發生權杖驗證，系統就會自動填入變數。 並定義符記屬性的值不過，如果未進行權杖驗證 就可以使用這項功能，將符記的屬性值明確填入變數。其他參考資訊 自訂權杖和 授權碼。

您傳送至這項政策的存取權杖必須有效，否則這項政策會擲回 invalid_access_token 個錯誤。

範例

下列範例使用「取得 OAuth V2 資訊」政策擷取各種 執行程式碼，然後在程式碼中存取這些資訊。

存取權杖

如要取得存取權杖的參照，請在<AccessToken> 您的政策。

以下範例預期在名為 &quot;access_token&quot;(實際導入細節由你決定)：

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

取得存取權杖後，這項政策會查詢權杖的設定檔，並填入一組 變數。

接著，您就可以使用 JavaScript 或其他方式存取變數。以下範例 使用 JavaScript 擷取與存取權杖關聯的範圍：

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

請注意，若要存取程式碼中的這些變數，您必須替變數加上 「oauthv2accesstoken」。如需存取權杖可用的變數完整清單，請參閱 存取權杖變數。

驗證碼

如要取得授權碼屬性，請使用 <AuthorizationCode> 元素。

以下範例預期會使用表單尋找存取權杖 參數，名為「code」(實際導入細節由你決定)：

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

根據驗證碼，這項政策會查詢程式碼資訊並填入一組 含有驗證碼資料的變數

接著，您就可以使用 JavaScript 或其他方式存取變數。以下範例 使用 JavaScript 擷取與授權碼相關聯的自訂屬性：

var attr = context.getVariable(‘oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name’);

請注意，若要在程式碼中存取這些變數，您必須在變數前面加上「oauthv2authcode」。 如需驗證碼可用的變數完整清單，請參閱 授權碼變數。

重新整理權杖

如要取得重新整理權杖屬性，請在<RefreshToken> 政策。

以下範例預期在名為 &quot;refresh_token&quot;(實際導入細節由你決定)：

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

根據更新權杖，這項政策會查詢更新權杖的資訊並填入資料 包含更新權杖資料的一組變數。

接著，您可以使用 JavaScript 或其他方式存取這些變數。下列 範例會使用 JavaScript 擷取與重新整理權杖相關聯的自訂屬性：

var attr = context.getVariable(‘oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name’);

請注意，若要存取程式碼中的變數，您必須將變數前面加上 「oauthv2refreshtoken」。如需可透過更新權杖取得的完整變數清單，請參閱 重新整理權杖變數。

靜態

在極少數情況下，您可能需要取得靜態設定權杖的設定檔 (一個 無法透過變數存取)。做法是提供 做為元素

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

您也可以使用所有其他權杖類型 (用戶端 ID、授權碼，以及重新整理) 進行驗證 符記)，

用戶端 ID

本範例說明如何使用用戶端 ID 擷取用戶端應用程式的相關資訊。 執行時，這項政策會在一組變數中填入用戶端資訊。在本 政策會預期在查詢參數中找到用戶端 ID 名為 client_id。根據用戶端 ID，政策會查詢客戶的 並將設定檔資料填入一組變數。這些變數會是 前置字串為 oauthv2client. 

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

接著，您就可以使用 JavaScript 或其他方式存取變數。舉例來說 與用戶端應用程式相關聯的開發人員應用程式名稱和開發人員電子郵件地址 JavaScript：

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

元素參照

元素參照會說明 GetOAuthV2Info 政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info>屬性

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

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

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

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

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

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

&lt;AccessToken&gt;元素

擷取存取權杖的設定檔。您傳入一個包含 存取權杖字串或常值權杖字串 (少數情況)。在這個範例中，存取權杖為 擷取自要求中傳遞的查詢參數。使用 <IgnoreAccessTokenStatus> 元素，針對已撤銷或過期的權杖傳回相關資訊。

<AccessToken ref="request.queryparam.access_token"></AccessToken>

預設：

request.formparam.access_token (x-www-form-urlencoded，在要求中指定的) 內文)

所在地：

選用
類型： 字串
有效值：

包含存取權杖字串的流程變數，或常值字串。

&lt;AuthorizationCode&gt;元素

擷取授權碼的設定檔。傳入一個包含 驗證碼字串或常值權杖字串 (極少出現)。在這個範例中，auth code 為 擷取自要求中傳遞的查詢參數。如需由此函式填入的變數清單 運算，請參閱「流程變數」。

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

預設：

request.formparam.access_token (x-www-form-urlencoded，在要求中指定的) 內文)

所在地：

選用
類型： 字串
有效值：

含有驗證碼字串的流程變數，或常值字串。

&lt;ClientId&gt;元素

擷取與用戶端 ID 相關的資訊。在本例中，系統會擷取用戶端 ID 要求存取如需這項作業填入的變數清單， 請參閱「流程變數」。

<ClientId ref="request.queryparam.client_id"></ClientId>

預設：

request.formparam.access_token (x-www-form-urlencoded，在要求中指定的) 內文)

所在地：

選用
類型： 字串
有效值： 含有驗證碼字串的流程變數，或常值字串。

&lt;IgnoreAccessTokenStatus&gt;元素

即使權杖已過期或遭撤銷，系統會傳回權杖資訊。這個元素只能 可與存取權杖搭配使用更新權杖和授權等其他實體的資訊 根據預設，無論代碼狀態為何，系統都會傳回驗證碼。

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

預設：

false

所在地：

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

&lt;RefreshToken&gt;元素

擷取更新權杖的設定檔。您傳入一個包含 重新整理符記字串或常值符記字串 (極少數的情況下)。本例中的更新權杖 擷取自要求中傳遞的查詢參數。如需由此函式填入的變數清單 運算，請參閱「流程變數」。

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

預設：

request.formparam.access_token (x-www-form-urlencoded，在要求中指定的) 內文)

所在地：

選用
類型： 字串
有效值：

包含更新權杖字串的流程變數，或常值字串。

流程變數

GetOAuthV2Info 政策會填入這些變數，通常在 需要設定檔資料，但尚未進行授權或驗證的位置。。

用戶端 ID 變數

設定 ClientId 元素時，系統會填入這些變數：

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

存取權杖變數

設定 AccessToken 元素時，系統會填入這些變數：

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

授權碼變數

設定 AuthorizationCode 元素時，系統會填入這些變數：

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

重新整理權杖變數

設定 RefreshToken 元素時，系統會填入這些變數：

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

結構定義

每種政策類型都是由 XML 架構 (.xsd) 定義。供參考政策結構定義 GitHub 提供許多資源。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.authorization_code_expired 500 The authorization code sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
steps.oauth.v2.invalid_refresh_token 500 The refresh token sent to the policy is invalid.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see this Apigee Community post for information about troubleshooting this error.
steps.oauth.v2.refresh_token_expired 500 The refresh token sent to the policy is expired.

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":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

相關主題