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

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Predeterminado	Presencia
name	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	falso	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	falso	Obsoleta

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presencia	Opcional
Tipo	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

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política. Los nombres de error que se muestran a continuación son las strings que se asignan a la variable fault.name cuando se produce un error. Consulta la sección Variables de falla a continuación para obtener más información.

Código de falla	Estado de HTTP	Causa
steps.oauth.v2.access_token_expired	500	El token de acceso que se envió a la política venció.
steps.oauth.v2.authorization_code_expired	500	El código de autorización enviado a la política venció.
steps.oauth.v2.invalid_access_token	500	El token de acceso enviado a la política no es válido.
steps.oauth.v2.invalid_client-invalid_client_id	500	El ID de cliente que se envió a la política no es válido.
steps.oauth.v2.invalid_refresh_token	500	El token de actualización que se envió a la política no es válido.
steps.oauth.v2.invalid_request-authorization_code_invalid	500	El código de autorización que se envió a la política no es válido.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	Consulta La verificación del token de acceso de Oauth2.0 muestra el error “Se produjo una llamada a la API no válida, ya que no se encontró ninguna coincidencia de apiproduct” para obtener información sobre la solución de este error.
steps.oauth.v2.refresh_token_expired	500	El token de actualización que se envió a la política venció.

Errores en la implementación

Consulta el mensaje reportado en la IU para obtener información sobre los errores de implementación.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución.

Nota: Puedes usar estas variables para crear condiciones de la regla de falla. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
fault.name="fault_name"	fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name es el nombre especificado por el usuario de la política que generó la falla.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name es el nombre especificado por el usuario de la política que generó la falla.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Ejemplo de respuesta de error

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Ejemplo de regla de falla

<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