Política de GetOAuthV2Info

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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.

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

No disponible Obligatorias
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.

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

false Funciones obsoletas

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

No disponible

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo Cadena

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

false

Presencia:

Opcional

Tipo: Booleano
Valores válidos: verdadero o falso

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

<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 y mensajes de error que se muestran y las variables de fallas que establece Edge 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 enviado a la política está vencido.
steps.oauth.v2.authorization_code_expired 500 El código de autorización que se envió 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 enviado a la política no es válido.
steps.oauth.v2.invalid_refresh_token 500 El token de actualización enviado a la política no es válido.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 El código de autorización enviado a la política no es válido.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Consulta esta publicación de la comunidad de Apigee para obtener información sobre cómo solucionar 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.

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