GetOAuthV2Info policy

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The GetOAuthV2Info policy 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 alsoCustomizing Tokens and Authorization Codes.

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

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Note: The resource path that is used to call a proxy with this policy must be included in the Product that was used to generate the original token. In other words, if you call the proxy with the path/tokeninfo, then the/tokeninfo resource path must be included in the Product that was used to generate the token. If not, you will receive anInvalidAPICallAsNoApiProductMatchFound error.

For more information, see GetOAuthV2Info fails if token generated using product with resource paths in theApigee Community.

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.

Access token

To get a reference to an access token, use the<AccessToken> element in your policy.

The following example expects to find the access token in a query parameter named "access_token" (the actual implementation details are up to you):

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

Given the access token, the policy looks up the token's profile and populates a set of variables with the profile data.

You can then access the variables using JavaScript or another means. The following example retrieves the scope(s) associated with the access token using #"true" translate="no" dir="ltr" is-upgraded syntax="GDScript" syntax-guessed>varscope=context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

Note that to access those variables in code, you must prefix them with "oauthv2accesstoken". For a complete list of variables available via the access token, seeAccess token variables.

Auth code

To get authorization code attributes, use the<AuthorizationCode> element in your policy.

The following example expects to find the access token in a form parameter named "code" (the actual implementation details are up to you):

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

Given the auth code, the policy looks up the code's information and populates a set of variables with the auth code data.

You can then access the variables using JavaScript or another means. The following example retrieves a custom attribute associated with the authorization code using #"true" translate="no" dir="ltr" is-upgraded syntax="GDScript" syntax-guessed>varattr=context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

Note that to access those variables in code, you must prefix them with "oauthv2authcode". For a complete list of variables available via the auth code, seeAuthorization code variables.

Refresh token

To get refresh token attributes, use the<RefreshToken> element in your policy.

The following example expects to find the access token in a query parameter named "refresh_token" (the actual implementation details are up to you):

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

Given the refresh token, the policy looks up the refresh token's information and populates a set of variables with the refresh token data.

You can then access those variables using JavaScript or another means. The following example retrieves a custom attribute associated with the refresh token using #"true" translate="no" dir="ltr" is-upgraded syntax="GDScript" syntax-guessed>varattr=context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

Note that to access the variables in code, you must prefix them with "oauthv2refreshtoken". For a complete list of variables available via the refresh token, seeRefresh token variables.

Static

In some rare cases you may need to get the profile of a statically configured token (one that is not accessible through a variable). You can do this by providing the value of the access token as an element.

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

You can do this with all other token types (client ID, authorization code, and refresh tokens) as well.

Client ID

This example shows how to retrieve information about the client app using the client ID. Upon execution, the policy populates a set of variables with client information. In this case, the policy expects to find the client ID in a query parameter calledclient_id. Given the client ID, the policy looks up the client's profile and populates a set of variables with the profile data. The variables will be prefixed withoauthv2client.

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

You can then access the variables using JavaScript or another means. For example, to get the developer app name and developer email associated with the client app using #"true" translate="no" dir="ltr" is-upgraded syntax="Text only" syntax-guessed>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.

<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?><GetOAuthV2Infoasync="false"continueOnError="false"enabled="true"name="GetOAuthV2Info-1"<DisplayName>GetOAuthv2.0Info1</DisplayName><AccessTokenref="variable"></AccessToken><AuthorizationCoderef="variable"></AuthorizationCode><ClientIdref="variable"></ClientId><RefreshTokenref="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:

Attribute	Description	Default	Presence
`name`	The internal name of the policy. The value of the`name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the`<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
`continueOnError`	Set to`false` to return an error when a policy fails. This is expected behavior for most policies. Set to`true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
`enabled`	Set to`true` to enforce the policy. Set to`false` toturn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
`async`	This attribute is deprecated.	false	Deprecated

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>

Default

Default	N/A If you omit this element, the value of the policy's`name` attribute is used.
Presence	Optional
Type	String

N/A

If you omit this element, the value of the policy'sname attribute is used.

Presence Optional

Type String

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

Default:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
Presence:	Optional
Type:	String
Valid values:	Either a flow variable containing an access token string, or a literal string.

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

Default:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
Presence:	Optional
Type:	String
Valid values:	Either a flow variable containing an auth code string, or a literal string.

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

Default:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
Presence:	Optional
Type:	String
Valid values:	Either a flow variable containing an auth code string, or a literal string.

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

Default:	false
Presence:	Optional
Type:	Boolean
Valid values:	true or false

<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".

Note:This element works the same whether you use a refresh token issued with a JWT access token or with a traditional opaque access token.

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

Default:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
Presence:	Optional
Type:	String
Valid values:	Either a flow variable containing an refresh token string, or a literal string.

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_idoauthv2client.{policy_name}.client_secretoauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'oauthv2client.{policy_name}.developer.emailoauthv2client.{policy_name}.developer.app.nameoauthv2client.{policy_name}.developer.idoauthv2client.{policy_name}.{developer_app_custom_attribute_name}

Access token variables

These variables are populated when the AccessToken element is set:

oauthv2accesstoken.{policy_name}.developer.idoauthv2accesstoken.{policy_name}.developer.app.nameoauthv2accesstoken.{policy_name}.developer.app.idoauthv2accesstoken.{policy_name}.developer.emailoauthv2accesstoken.{policy_name}.organization_nameoauthv2accesstoken.{policy_name}.api_product_listoauthv2accesstoken.{policy_name}.access_tokenoauthv2accesstoken.{policy_name}.scopeoauthv2accesstoken.{policy_name}.expires_in//insecondsoauthv2accesstoken.{policy_name}.statusoauthv2accesstoken.{policy_name}.client_idoauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}oauthv2accesstoken.{policy_name}.refresh_tokenoauthv2accesstoken.{policy_name}.refresh_token_statusoauthv2accesstoken.{policy_name}.refresh_token_expires_in//insecondsoauthv2accesstoken.{policy_name}.refresh_countoauthv2accesstoken.{policy_name}.refresh_token_issued_atoauthv2accesstoken.{policy_name}.revoke_reason//ApigeehybridonlywithvalueofREVOKED_BY_APP,REVOKED_BY_ENDUSER,REVOKED_BY_APP_ENDUSER,orTOKEN_REVOKED

Authorization code variables

These variables are populated when the AuthorizationCode element is set:

oauthv2authcode.{policy_name}.codeoauthv2authcode.{policy_name}.scopeoauthv2authcode.{policy_name}.redirect_urioauthv2authcode.{policy_name}.client_idoauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Refresh token variables

These variables are populated when the RefreshToken element is set:

oauthv2refreshtoken.{policy_name}.developer.idoauthv2refreshtoken.{policy_name}.developer.app.nameoauthv2refreshtoken.{policy_name}.developer.app.idoauthv2refreshtoken.{policy_name}.developer.emailoauthv2refreshtoken.{policy_name}.organization_nameoauthv2refreshtoken.{policy_name}.api_product_listoauthv2refreshtoken.{policy_name}.access_tokenoauthv2refreshtoken.{policy_name}.scopeoauthv2refreshtoken.{policy_name}.expires_in//insecondsoauthv2refreshtoken.{policy_name}.statusoauthv2refreshtoken.{policy_name}.client_idoauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}oauthv2refreshtoken.{policy_name}.refresh_tokenoauthv2refreshtoken.{policy_name}.refresh_token_statusoauthv2refreshtoken.{policy_name}.refresh_token_expires_in//insecondsoauthv2refreshtoken.{policy_name}.refresh_countoauthv2refreshtoken.{policy_name}.refresh_token_issued_atoauthv2refreshtoken.{policy_name}.revoke_reason//ApigeehybridonlywithvalueofREVOKED_BY_APP,REVOKED_BY_ENDUSER,REVOKED_BY_APP_ENDUSER,orTOKEN_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 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, seeWhat you need to know about policy errors andHandling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to thefault.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 Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error 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.

Note: You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in theRuntime 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>

Movatterモバイル変換

GetOAuthV2Info policy

Samples

Access token

Auth code

Refresh token

Static

Client ID

Element Reference

<GetOAuthV2Info> attributes

<DisplayName> element

<AccessToken> element

<AuthorizationCode> element

<ClientId> element

<IgnoreAccessTokenStatus> element

<RefreshToken> element

Flow variables

Client ID variables

Access token variables

Authorization code variables

Refresh token variables

Schema

Error reference

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Related topics

Movatterモバイル変換

GetOAuthV2Info policy Stay organized with collections Save and categorize content based on your preferences.

Samples

Access token

Auth code

Refresh token

Static

Client ID

Element Reference

<GetOAuthV2Info> attributes

<DisplayName> element

<AccessToken> element

<AuthorizationCode> element

<ClientId> element

<IgnoreAccessTokenStatus> element

<RefreshToken> element

Flow variables

Client ID variables

Access token variables

Authorization code variables

Refresh token variables

Schema

Error reference

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Related topics

GetOAuthV2Info policy