Política GetOAuthV2Info

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

Consulta la documentación de Apigee Edge.

La política GetOAuthV2Info obtiene atributos de tokens de acceso, tokens de actualización, códigos de autorización y atributos de aplicaciones cliente, y rellena 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.

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>

A partir del 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 necesites 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. Al ejecutarse, 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:

 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: Booleano
Valores válidos: verdadero o falso

Elemento <RefreshToken>

Obtiene el perfil de un token de actualización. Puedes introducir 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. 

<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

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.

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