GetOAuthV2Info policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

What

Gets attributes of access tokens, refresh tokens, authorization codes, and client app attributes and populates variables with the values of those attributes.

This policy is useful when you need to configure dynamic, conditional behavior based on a value in a token or auth code. Whenever token validation occurs, variables are automatically populated with the values of token attributes. However, in cases where token validation has not occurred, you can use this feature to explicitly populate variables with the attribute values of a token. See also Customizing Tokens and Authorization Codes.

An access token that you pass to this policy must be valid or the policy will throw an invalid_access_token error.

Samples

The following samples use the Get OAuth V2 Info policy to retrieve information about various components of the OAuth2 workflow and then then access that information within code.

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

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

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

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

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

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

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

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

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

Element Reference

The element reference describes the elements and attributes of the GetOAuthV2Info policy.

<?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> attributes

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

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<AccessToken> element

Retrieves the profile for an access token. You pass in a either a variable that contains the access token string or a literal token string (rare case). In this example, the access token is retrieved from a query parameter passed in a request. Use the <IgnoreAccessTokenStatus> element if you want to return information for a revoked or expired token.

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

<AuthorizationCode> element

Retrieves the profile for an authorization code. You pass in a either a variable that contains the auth code string or a literal token string (rare case). In this example, the auth code is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables".

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

<ClientId> element

Retrieves information related to a client ID. In this example, the client ID is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables".

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

<IgnoreAccessTokenStatus> element

Returns the token information even if the token is expired or revoked. This element can only be used with access tokens. Information for other entities like refresh tokens and authorization codes are returned regardless of their status, by default.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

<RefreshToken> element

Retrieves the profile for a refresh token. You pass in a either a variable that contains the refresh token string or a literal token string (rare case). In this example, the refresh token is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables".

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

Flow variables

The GetOAuthV2Info policy populates these variables, and is typically used in cases where you need the profile data, but where a grant or validation has not occurred yet. .

Client ID variables

These variables are populated when the ClientId element is set:

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}

Access token variables

These variables are populated when the AccessToken element is set:

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

Authorization code variables

These variables are populated when the AuthorizationCode element is set:

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}

Refresh token variables

These variables are populated when the RefreshToken element is set:

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

Schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Error reference

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.

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.

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>

Related topics

• OAuthV2 policy
• OAuth home
• Customizing Tokens and Authorization Codes