Política GetOAuthV2Info

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

Consulta la documentación de Apigee Edge.

La función de token de acceso JWT está disponible actualmente en Apigee y en Apigee hybrid 1.7.0 y versiones posteriores. Consulta Usar tokens de OAuth 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 aplicación cliente, y rellena las variables con los valores de esos atributos.

Esta política es útil cuando necesitas configurar un comportamiento dinámico y condicional basado en un valor de un token o un código de autorización. Cada vez que se valida un token, las variables se rellenan automáticamente con los valores de los atributos del token. Sin embargo, en los casos en los que no se haya validado el token, puede usar esta función para rellenar explícitamente las variables con los valores de los atributos de un token. Consulta también Personalizar tokens y códigos de autorización.

El token de acceso que envíes a esta política debe ser válido. De lo contrario, la política devolverá un error invalid_access_token.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

NOTA

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

Para obtener más información, consulta el artículo GetOAuthV2Info fails if token generated using product with resource paths (GetOAuthV2Info falla si el token se genera con 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 obtener información sobre varios componentes del flujo de trabajo de OAuth2 y, a continuación, acceder a esa información en el código.

Token de acceso

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

En el siguiente ejemplo, se espera encontrar el token de acceso en un parámetro de consulta llamado "access_token" (los detalles de la implementación dependen de ti):

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

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

Después, puedes acceder a las variables mediante JavaScript u otro método. En el siguiente ejemplo se obtienen los ámbitos asociados al token de acceso mediante JavaScript:

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

Ten en cuenta que, para acceder a esas variables en el código, debes añadirles el prefijo "oauthv2accesstoken". Para ver una lista completa de las variables disponibles a través del token de acceso, consulta Variables del token de acceso.

Código de autorización

Para obtener 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" (los detalles de la implementación real dependen de ti):

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

Dado el código de autorización, la política busca la información del código y rellena un conjunto de variables con los datos del código de autorización.

Después, puedes acceder a las variables mediante JavaScript u otro método. En el siguiente ejemplo, se obtiene un atributo personalizado asociado al 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 el código, debes añadirles el prefijo "oauthv2authcode". Para ver una lista completa de las variables disponibles a través del código de autorización, consulta Variables del código de autorización.

Token de actualización

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

En el siguiente ejemplo, se espera encontrar el token de acceso en un parámetro de consulta llamado "refresh_token" (los detalles de la implementación dependen de ti):

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

A partir del token de actualización, la política busca la información del token de actualización y rellena un conjunto de variables con los datos del token de actualización.

Después, puedes acceder a esas variables mediante JavaScript u otro método. En el siguiente ejemplo se obtiene un atributo personalizado asociado al 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 el código, debes añadirles el prefijo "oauthv2refreshtoken". Para ver una lista completa de las variables disponibles a través del token de actualización, consulta Variables del token de actualización.

Estática

En algunos casos excepcionales, puede que tengas que obtener el perfil de un token configurado de forma 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 tokens (ID de cliente, código de autorización y tokens de actualización).

ID de cliente

En este ejemplo se muestra cómo obtener información sobre la aplicación cliente mediante el ID de cliente. Cuando se ejecuta, la política rellena 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 consulta llamado client_id. A partir del ID de cliente, la política busca el perfil del cliente y rellena 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>

Después, puedes acceder a las variables mediante JavaScript u otro método. Por ejemplo, para obtener el nombre de la aplicación del desarrollador y el correo del desarrollador asociados a la aplicación cliente mediante JavaScript, haz lo siguiente:

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

---

Referencia de elemento

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

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. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.	N/A	Obligatorio
continueOnError	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual	falso	Opcional
enabled	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.	true	Opcional
async	Este atributo está obsoleto.	falso	Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>

Predeterminado	N/A Si omite este elemento, se usará el valor del atributo name de la política.
Presencia	Opcional
Tipo	Cadena

Elemento <AccessToken>

Obtiene el perfil de un token de acceso. Puedes introducir una variable que contenga la cadena del token de acceso o una cadena de token literal (en casos excepcionales). En este ejemplo, el token de acceso se obtiene de un parámetro de consulta que se ha incluido en una solicitud. Usa el elemento <IgnoreAccessTokenStatus> si quieres devolver información de un token revocado o caducado.

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

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

Elemento <AuthorizationCode>

Obtiene el perfil de un código de autorización. Envías una variable que contiene la cadena del código de autorización o una cadena de token literal (en casos excepcionales). En este ejemplo, el código de autorización se obtiene de un parámetro de consulta que se ha incluido en una solicitud. Para ver una lista de las variables que se rellenan con esta operación, consulta Variables de flujo.

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

Valor predeterminado:	request.formparam.access_token (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	Cadena
Valores válidos:	Una variable de flujo que contiene una cadena de código de autorización o una cadena literal.

Elemento <ClientId>

Recupera información relacionada con un ID de cliente. En este ejemplo, el ID de cliente se obtiene de un parámetro de consulta que se ha incluido en una solicitud. Para ver una lista de las variables que se rellenan con esta operación, consulta Variables de flujo.

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

Valor predeterminado:	request.formparam.access_token (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	Cadena
Valores válidos:	Una variable de flujo que contiene una cadena de código de autorización o una cadena literal.

Elemento <IgnoreAccessTokenStatus>

Devuelve la información del token aunque haya caducado o se haya revocado. Este elemento solo se puede usar con tokens de acceso. La información de otras entidades, como los tokens de actualización y los códigos de autorización, se devuelve de forma predeterminada independientemente de su estado.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Valor predeterminado:	falso
Presencia:	Opcional
Tipo:	Boolean
Valores válidos:	verdadero o falso

Elemento <RefreshToken>

Obtiene el perfil de un token de actualización. Puedes enviar una variable que contenga la cadena del token de actualización o una cadena de token literal (en casos excepcionales). En este ejemplo, el token de actualización se obtiene de un parámetro de consulta que se ha incluido en una solicitud. Para ver una lista de las variables que se rellenan con esta operación, consulta Variables de flujo.

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

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

Valor predeterminado:	request.formparam.access_token (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)
Presencia:	Opcional
Tipo:	Cadena
Valores válidos:	Una variable de flujo que contenga una cadena de token de actualización o una cadena literal.

Variables de flujo

La política GetOAuthV2Info rellena estas variables y se suele usar en los casos en los que necesitas los datos del perfil, pero aún no se ha producido ninguna concesión ni validación. .

Variables de ID de cliente

Estas variables se rellenan cuando se define 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 rellenan cuando se define 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 rellenan cuando se define 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 rellenan cuando se define 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

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Código de fallo	Estado de HTTP	Causa
steps.oauth.v2.access_token_expired	500	El token de acceso enviado a la política ha caducado.
steps.oauth.v2.authorization_code_expired	500	El código de autorización enviado a la política ha caducado.
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	Consulte el artículo La verificación del token de acceso de OAuth 2.0 genera el error "Invalid API call as no apiproduct match found" (Llamada a la API no válida porque no se ha encontrado ningún producto de API coincidente) para obtener información sobre cómo solucionar este error.
steps.oauth.v2.refresh_token_expired	500	El token de actualización enviado a la política ha caducado.

Errores de implementación

Consulta el mensaje que se muestra en la interfaz de usuario para obtener información sobre los errores de implementación.

Variables de error

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

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

Variables	Dónde	Ejemplo
fault.name="fault_name"	fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	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"
      }
   }
}

Regla de error de ejemplo

<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
• Personalizar tokens y códigos de autorización