Política de GetOAuthV2Info

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Por el momento, la función del token de acceso de JWT está disponible para Apigee y para las versiones de Apigee Hybrid 1.7.0 y posteriores. Consulta Usa tokens de OAuth de JWT.

Qué

Obtiene los atributos de los tokens de acceso, los tokens de actualización, los códigos de autorización y los atributos de la app cliente, y propaga variables con los valores de esos atributos.

Esta política es útil cuando necesitas configurar el comportamiento condicional y dinámico en función de un valor en un token o código de autenticación. Cuando se realiza la validación del token, las variables se propagan automáticamente con los valores de los atributos del token. Sin embargo, en los casos en que no se haya generado la validación del token, puedes usar esta característica para propagar explícitamente variables con los valores de atributo de un token. Consulta también Personaliza tokens y códigos de autorización.

Un token de acceso que pasas a esta política debe ser válido o la política arrojará un error invalid_access_token.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

NOTA

La ruta del recurso que se usa a fin de llamar a un proxy con esta política debe incluirse en el producto que se usó para generar el token original. En otras palabras, si llamas al proxy con la ruta /tokeninfo, entonces la ruta de acceso del recurso /tokeninfo debe incluirse en el producto que se usó para generar el token. De lo contrario, recibirás un error InvalidAPICallAsNoApiProductMatchFound.

Para obtener más información, consulta GetOAuthV2Info falla si el token generado usa un producto con rutas de recursos en la Comunidad de Apigee.

Ejemplos

En los siguientes ejemplos, se usa la política Get OAuth V2 Info para recuperar información sobre varios componentes del flujo de trabajo de OAuth2 y, luego, acceder a esa información dentro del código.

Token de acceso

Para obtener una referencia a un token de acceso, usa el elemento <AccessToken> en tu política.

El siguiente ejemplo espera encontrar el token de acceso en un parámetro de búsqueda llamado “access_token” (puedes ver los detalles de la implementación real):

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

Debido al token de acceso, la política busca el perfil del token y propaga un conjunto de variables con los datos del perfil.

Luego, puedes acceder a las variables con JavaScript o con otros medios. En el siguiente ejemplo, se recuperan los alcances asociados con el token de acceso mediante JavaScript:

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

Ten en cuenta que, para acceder a esas variables en código, debes agregarles un prefijo con “oauthv2accesstoken”. Para obtener una lista completa de variables disponibles a través del token de acceso, consulta Variables de token de acceso.

Código de autenticación

Para obtener los atributos de código de autorización, usa el elemento <AuthorizationCode> en tu política.

En el siguiente ejemplo, se espera encontrar el token de acceso en un parámetro de formulario llamado “code” (puedes elegir los detalles reales de la implementación):

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

Con el código de autenticación, la política busca la información del código y propaga un conjunto de variables con los datos del código de autenticación.

Luego, puedes acceder a las variables con JavaScript o con otros medios. En el siguiente ejemplo, se recupera un atributo personalizado asociado con el código de autorización mediante JavaScript:

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

Ten en cuenta que, para acceder a esas variables en código, debes agregarles el prefijo “oauthv2authcode”. Para obtener una lista completa de las variables disponibles a través del código de autenticación, consulta Variables de código de autorización.

Token de actualización

Para obtener los atributos del token de actualización, usa el elemento <RefreshToken> en tu política.

El siguiente ejemplo espera encontrar el token de acceso en un parámetro de consulta llamado “refresh_token” (puedes consultar los detalles de la implementación real):

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

Con el token de actualización, la política busca la información del token de actualización y propaga un conjunto de variables con los datos del token de actualización.

Luego, puedes acceder a esas variables con JavaScript o con otros medios. En el siguiente ejemplo, se recupera un atributo personalizado asociado con el token de actualización mediante JavaScript:

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

Ten en cuenta que, para acceder a las variables en código, debes agregarles un prefijo con “oauthv2refreshtoken”. Para obtener una lista completa de las variables disponibles a través del token de actualización, consulta Variables de token de actualización.

Estático

En algunos casos poco frecuentes, es posible que necesites obtener el perfil de un token configurado de manera estática (uno al que no se puede acceder a través de una variable). Para ello, proporciona el valor del token de acceso como un elemento.

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

También puedes hacerlo con todos los demás tipos de token (ID de cliente, código de autorización y tokens de actualización).

ID de cliente

En este ejemplo, se muestra cómo recuperar información sobre la app cliente mediante el ID de cliente. Después de la ejecución, la política propaga un conjunto de variables con información del cliente. En este caso, la política espera encontrar el ID de cliente en un parámetro de búsqueda llamado client_id. Dada la ID del cliente, la política busca el perfil del cliente y propaga un conjunto de variables con los datos del perfil. Las variables tendrán el prefijo oauthv2client.

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

Luego, puedes acceder a las variables con JavaScript o con otros medios. Por ejemplo, para obtener el nombre de la app de desarrollador y el correo electrónico del desarrollador asociado con la app cliente mediante JavaScript, haz lo siguiente:

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

---

Referencia de elementos

En la referencia del elemento, se describen los elementos y atributos de la política de 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>

Atributos <GetOAuthV2Info>

<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 to turn 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 the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

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

Elemento <AccessToken>

Recupera el perfil de un token de acceso. Debes pasar una variable que contiene la string de token de acceso o una string de token literal (casos poco frecuentes). En este ejemplo, el token de acceso se recupera de un parámetro de consulta pasado en una solicitud. Usa el elemento <IgnoreAccessTokenStatus> si quieres mostrar información para un token anulado o vencido.

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

Predeterminado:	request.formparam.access_token (una x-www-form-urlencoded y especificada en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	String
Valores válidos:	Una variable de flujo que contiene una string de token de acceso o una string literal.

Elemento <AuthorizationCode>

Recupera el perfil para un código de autorización. Debes pasar una variable que contenga la string de autenticación o una string de token literal (casos poco frecuentes). En este ejemplo, el código de autenticación se recupera de un parámetro de búsqueda pasado en una solicitud. Para obtener una lista de variables propagadas por esta operación, consulta “Variables de flujo”.

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

Predeterminado:	request.formparam.access_token (una x-www-form-urlencoded y especificada en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	String
Valores válidos:	Una variable de flujo que contiene una string de código de autenticación o una string literal.

Elemento <ClientId>

Recupera información relacionada con un ID de cliente. En este ejemplo, el ID de cliente se recupera de un parámetro de búsqueda pasado en una solicitud. Para obtener una lista de variables que propagó esta operación, consulta “Variables de flujo”.

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

Predeterminado:	request.formparam.access_token (una x-www-form-urlencoded y especificada en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	String
Valores válidos:	Una variable de flujo que contiene una string de código de autenticación o una string literal.

Elemento <IgnoreAccessTokenStatus>

Muestra la información del token, incluso si el token venció o se revocó. Este elemento solo se puede usar con tokens de acceso. Según la configuración predeterminada, se muestra la información de otras entidades como tokens de actualización y códigos de autorización, independientemente de su estado.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Predeterminado:	falso
Presencia:	Opcional
Tipo:	booleano
Valores válidos:	True o False

Elemento <RefreshToken>

Recupera el perfil para un token de actualización. Debes pasar una variable que contiene la string de token de actualización o una string de token literal (casos poco frecuentes). En este ejemplo, el token de actualización se recupera de un parámetro de búsqueda pasado en una solicitud. Para obtener una lista de variables propagadas por esta operación, consulta “Variables de flujo”.

Nota: Este elemento funciona igual si usas un token de actualización emitido con un token de acceso JWT o con un token de acceso opaco tradicional.

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

Predeterminado:	request.formparam.access_token (una x-www-form-urlencoded y especificada en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	String
Valores válidos:	Una variable de flujo que contiene una string de token de actualización o una string literal.

Variables de flujo

La política de GetOAuthV2Info propaga estas variables y se suele usar en los casos en los que necesitas datos de perfil, pero donde aún no se ha otorgado una concesión o validación. .

Variables de ID de cliente

Estas variables se propagan cuando se establece el elemento 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}

Variables de token de acceso

Estas variables se propagan cuando se configura el elemento 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

Variables de código de autorización

Estas variables se propagan cuando se establece el elemento 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}

Variables de token de actualización

Estas variables se propagan cuando se configura el elemento 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

Esquema

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Referencia de errores

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

Temas relacionados

• Política de OAuthV2
• Página principal de OAuth
• Personalización de tokens y códigos de autorización