Política de OAuthV2

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

Consulta la documentación de Apigee Edge.

Icono de política

Qué

OAuthV2 es una política multifacética para realizar operaciones de tipo de autorización de OAuth 2.0. Esta es la política principal que se usa para configurar los endpoints de OAuth 2.0 en Apigee.

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.

Para obtener más información sobre OAuth en Apigee, consulta la página principal de OAuth. Incluye enlaces a recursos, ejemplos, vídeos y más.

Muestras

VerifyAccessToken

VerifyAccessToken

Esta configuración de la política OAuthV2 (con la operación VerifyAccessToken) verifica que un token de acceso enviado a Apigee sea válido. Cuando se activa esta operación de política, Apigee busca un token de acceso válido en la solicitud. Si el token de acceso es válido, se permite que la solicitud continúe. Si no es válido, se detiene todo el procesamiento y se devuelve un error en la respuesta. 

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Una aplicación cliente tendría que enviar una solicitud con un token. Por ejemplo, si usas curl, podría ser así:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

Donde API_ENDPOINT es el dominio que se usa para acceder a tus APIs, tal como se ha configurado en tu sistema Apigee.

De forma predeterminada, la política OAuthV2 extrae el token de acceso del encabezado Authorization, quitando el prefijo Bearer. Puedes cambiar este comportamiento predeterminado con el elemento de configuración AccessToken.

GenerateAccessToken

Generar tokens de acceso

Para ver ejemplos de cómo solicitar tokens de acceso para cada uno de los tipos de concesión admitidos, consulta Obtener tokens de OAuth 2.0. En el tema se incluyen ejemplos de estas operaciones:

GenerateAuthorizationCode

Generar código de autorización

Para ver ejemplos de cómo solicitar códigos de autorización, consulta Solicitar un código de autorización.

RefreshAccessToken

Actualizar un token de acceso

Para ver ejemplos de cómo solicitar tokens de acceso mediante un token de actualización, consulta Actualizar un token de acceso.

Tokens de acceso JWT

Tokens de acceso JWT

Para ver ejemplos de cómo generar, verificar y actualizar tokens de acceso JWT, consulta Usar tokens de acceso JWT.

Token de flujo de respuesta

Generar un token de acceso en el flujo de respuesta

En ocasiones, es posible que tengas que generar un token de acceso en el flujo de respuesta. Por ejemplo, puedes hacerlo en respuesta a alguna validación personalizada realizada en un servicio de backend. En este ejemplo, el caso práctico requiere un token de acceso y un token de actualización, por lo que se descarta el tipo de concesión implícita. En este caso, usaremos el tipo de concesión de contraseña para generar el token. Como verás, el truco para que esto funcione es enviar un encabezado de solicitud de autorización con una política de JavaScript.

Primero, veamos la política de ejemplo:

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

Si incluyes esta política en el flujo de respuesta, se producirá un error 401 UnAuthorized aunque se especifiquen los parámetros de inicio de sesión correctos en la política. Para solucionar este problema, debes definir un encabezado de solicitud de autorización.

El encabezado Authorization debe contener un esquema de acceso básico con el valor client_id:client_secret codificado en Base64.

Puedes añadir este encabezado con una política de JavaScript colocada justo antes de la política OAuthV2, de esta forma. Las variables de contexto "local_clientid" y "local_secret" deben haberse definido previamente y estar disponibles en el flujo:

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Consulta también Codificar credenciales de autenticación básica.

Referencia de elemento

En la referencia de la política se describen los elementos y atributos de la política OAuthV2.

La política de ejemplo que se muestra a continuación es una de las muchas configuraciones posibles. En este ejemplo se muestra una política de OAuthV2 configurada para la operación GenerateAccessToken. Incluye elementos obligatorios y opcionales. Para obtener más información, consulta las descripciones de los elementos de esta sección.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Atributos <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

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>

<AccessToken>request.header.access_token</AccessToken>

De forma predeterminada, cuando Operation está VerifyAccessToken, la política espera que el token de acceso se envíe en el encabezado Authorization como token de portador, es decir, con el prefijo "Bearer" seguido de un espacio en blanco. Puede cambiar ese valor predeterminado con este elemento, especificando el nombre de una variable que contenga el token de acceso que se va a verificar. Cuando usas este elemento, la política no busca de forma predeterminada un prefijo en el contenido de la variable. Si quieres especificar que la política debe buscar un prefijo, usa también el elemento AccessTokenPrefix.

Ejemplos:

  • Cuando la configuración de la política es la siguiente:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    Para enviar el token mediante curl, puedes usar lo siguiente:

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • Cuando la configuración de la política es la siguiente:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    Para enviar el token mediante curl, puedes usar lo siguiente:

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Donde API_ENDPOINT es el dominio que se usa para acceder a tus APIs, tal como se ha configurado en tu sistema Apigee.

Predeterminado

N/A

Presencia

Opcional
Tipo Cadena
Valores válidos

cualquier nombre de variable
Se usa con operaciones
  • VerifyAccessToken

Elemento <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

De forma predeterminada, cuando Operation está VerifyAccessToken, la política espera que el token de acceso se envíe en el encabezado Authorization como token de portador, es decir, con el prefijo "Bearer" seguido de un espacio en blanco. Si usas el elemento AccessToken para especificar otra ubicación para el token de acceso entrante, también puedes usar este elemento, AccessTokenPrefix, para especificar otro prefijo no estándar.

Por ejemplo, si especifica lo siguiente:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

A continuación, la política extraerá el token de acceso entrante del encabezado de la solicitud token. De esta forma, si el encabezado empieza por la palabra "KEY" seguida de un espacio, la política eliminará ese prefijo y ese espacio, e interpretará el valor restante como el token de acceso. Si el prefijo especificado no está presente en el encabezado, la política generará un error.

Si especifica el elemento AccessToken y no especifica el elemento AccessTokenPrefix, la política interpretará todo el valor de la variable especificada en el elemento AccessToken como token de acceso.

Este elemento solo es efectivo cuando también se usa el elemento AccessToken.

Predeterminado

-ninguno-

Presencia

Opcional
Tipo Cadena
Valores válidos

cualquier cadena
Se usa con operaciones
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica el algoritmo de cifrado que se usa para firmar un token de acceso JWT. Los algoritmos RSA (RS*) emplean un par de claves pública y secreta, mientras que los algoritmos HMAC (HS*) emplean un secreto compartido. Este elemento es obligatorio para las operaciones GenerateJWTAccessToken, VerifyJWTAccessToken y RefreshJWTAccessToken.

Predeterminado N/A
Presencia Obligatorio cuando se usan las operaciones GenerateJWTAccessToken, VerifyJWTAccessToken y RefreshJWTAccessToken.
Tipo Cadena
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512

Elemento <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

En los casos en los que el ID de usuario final de la aplicación se debe enviar al servidor de autorización, este elemento le permite especificar dónde debe buscar Apigee el ID de usuario final. Por ejemplo, se puede enviar como un parámetro de consulta o en un encabezado HTTP.

Por ejemplo, request.queryparam.app_enduser indica que el valor de AppEndUser debe estar presente como parámetro de consulta, como ?app_enduser=ntesla@theramin.com. Para requerir el AppEndUser en un encabezado HTTP, por ejemplo, asigna el valor request.header.app_enduser.

Si proporciona este ajuste, podrá incluir un ID de usuario final de la aplicación en el token de acceso. Esta función es útil si quieres poder recuperar o revocar tokens de acceso de OAuth 2.0 por ID de usuario final. Para obtener más información, consulta Habilitar la recuperación y la revocación de tokens de acceso de OAuth 2.0 por ID de usuario final, ID de aplicación o ambos.

Predeterminado

N/A

Presencia

Opcional
Tipo Cadena
Valores válidos

Cualquier variable de flujo a la que pueda acceder la política en el tiempo de ejecución.
Se usa con tipos de concesión
  • authorization_code
  • implícito
  • contraseña
  • client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Utiliza este elemento para añadir atributos personalizados a un token de acceso o a un código de autorización. Por ejemplo, puedes insertar un ID de usuario o un identificador de sesión en un token de acceso que se pueda extraer y comprobar en tiempo de ejecución.

Este elemento le permite especificar un valor en una variable de flujo o a partir de una cadena literal. Si especificas tanto una variable como una cadena, se usará el valor especificado en la variable de flujo. Si no se puede resolver la variable, la cadena es el valor predeterminado.

Para obtener más información sobre cómo usar este elemento, consulta Personalizar tokens y códigos de autorización.

Mostrar u ocultar atributos personalizados en la respuesta

Recuerda que, si asignas el valor true al elemento GenerateResponse de esta política, se devolverá la representación JSON completa del token en la respuesta, incluidos los atributos personalizados que hayas definido. En algunos casos, puede que quieras ocultar algunos o todos tus atributos personalizados en la respuesta para que no sean visibles para las aplicaciones cliente.

De forma predeterminada, los atributos personalizados aparecen en la respuesta. Si quieres ocultarlos, puedes asignar el valor false al parámetro display. Por ejemplo:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

El valor del atributo display no se conserva. Supongamos que generas un token de acceso con atributos personalizados que quieres ocultar en la respuesta generada. El ajuste display=false cumple ese objetivo. Sin embargo, si se genera un nuevo token de acceso más adelante con un token de actualización, los atributos personalizados originales del token de acceso se mostrarán en la respuesta del token de actualización. Esto se debe a que Apigee no recuerda que el atributo display se asignó originalmente a false en la política de generación de tokens de acceso. El atributo personalizado es simplemente parte de los metadatos del token de acceso.

Verá el mismo comportamiento si añade atributos personalizados a un código de autorización: cuando se genere un token de acceso con ese código, esos atributos personalizados aparecerán en la respuesta del token de acceso. De nuevo, puede que no sea el comportamiento que quieres.

Para ocultar atributos personalizados en estos casos, tienes las siguientes opciones:

  • Restablece explícitamente los atributos personalizados en la política de tokens de actualización y define su valor como false. En este caso, es posible que tengas que recuperar los valores personalizados originales del token de acceso original mediante la política GetOAuthV2Info.
  • Usa una política de JavaScript de posprocesamiento para extraer manualmente los atributos personalizados que no quieras que aparezcan en la respuesta.

Consulta también Personalizar tokens y códigos de autorización.

Predeterminado

N/A

Presencia

Opcional
Valores válidos
  • name: nombre del atributo
  • ref: valor del atributo. Puede proceder de una variable de flujo.
  • display (opcional): permite especificar si los atributos personalizados aparecen en la respuesta. Si true, los atributos personalizados aparecen en la respuesta (si GenerateResponse también está habilitado). Si false, los atributos personalizados no se incluyen en la respuesta. El valor predeterminado es true. Consulta Mostrar u ocultar atributos personalizados en la respuesta.
Se usa con tipos de concesión
  • authorization_code
  • implícito
  • contraseña
  • client_credentials
  • refresh_token
  • También se puede usar con la operación GenerateAuthorizationCode.

Elemento <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Este elemento solo se puede usar con la operación VerifyAccessToken. Especifica el tiempo de vida (TTL) de la caché de tokens de acceso para la ejecución de una política concreta. La primera vez que Apigee verifica un token de acceso de OAuth 2, debe obtenerlo de un almacén persistente. Se trata de una operación relativamente costosa, por lo que Apigee almacena en caché el resultado de la búsqueda de tokens, incluido el estado del token, la lista de productos para los que es válido y los atributos personalizados asociados al token. Las invocaciones posteriores de OAuthV2/VerifyAccessToken hasta que transcurra el TTL leerán el resultado almacenado en caché en la memoria, lo que significa que la verificación del token será mucho más rápida.

El TTL predeterminado de la caché de tokens de acceso es de 180 segundos. Este elemento te permite reducir ese TTL, lo que supone sacrificar rendimiento a cambio de precisión. Un caso en el que esto tendría sentido es si a veces revocas tokens y quieres reducir el periodo durante el cual Apigee seguirá tratando los tokens revocados como válidos.

El intervalo admitido es de entre 1 y 180 segundos. Puede proporcionar una variable de flujo y un valor predeterminado. Si proporciona una variable de flujo y contiene un valor numérico, tendrá prioridad sobre el valor predeterminado especificado.

Predeterminado

 N/A

Si omite este elemento, el periodo de vencimiento predeterminado del token de acceso almacenado en caché será de 180 segundos.

Presencia

 Opcional

Tipo

 Entero

Valores válidos

 Cualquier número entero positivo distinto de cero. Especifica el tiempo de vencimiento en segundos.
Se usa con operaciones
  • VerifyAccessToken

Atributos

En la siguiente tabla se describen los atributos del elemento <CacheExpiryInSeconds>.

Atributo Descripción Predeterminado Presencia
ref

Referencia a la variable de flujo que contiene el valor de la caducidad de la caché, expresado en segundos.

Si se proporciona, el valor de la variable de flujo tiene prioridad sobre el valor predeterminado especificado.

 N/A Opcional

Elemento <ClientId>

<ClientId>request.formparam.client_id</ClientId>

En varios casos, la aplicación cliente debe enviar el ID de cliente al servidor de autorización. Este elemento especifica que Apigee debe buscar el ID de cliente en la variable de flujo request.formparam.client_id. No se admite la asignación de ClientId a ninguna otra variable. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.client_id (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo Cadena
Valores válidos La variable de flujo: request.formparam.client_id
Se usa con tipos de concesión
  • authorization_code
  • contraseña
  • implícito
  • client_credentials

También se puede usar con la operación GenerateAuthorizationCode.

Elemento <Code>

<Code>request.queryparam.code</Code>

En el flujo de tipo de concesión de autorización, el cliente debe enviar un código de autorización al servidor de autorización (Apigee). Este elemento le permite especificar dónde debe buscar Apigee el código de autorización. Por ejemplo, se puede enviar como parámetro de consulta, encabezado HTTP o parámetro de formulario (opción predeterminada).

La variable request.queryparam.auth_code indica que el código de autorización debe estar presente como parámetro de consulta, como ?auth_code=AfGlvs9. Para requerir el código de autorización en un encabezado HTTP, por ejemplo, asigna el valor request.header.auth_code. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.code (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

opcional
Tipo Cadena
Valores válidos Cualquier variable de flujo a la que pueda acceder la política durante el tiempo de ejecución
Se usa con tipos de concesión authorization_code

Elemento <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Aplica el tiempo de vencimiento de los tokens de acceso y los códigos de autorización en milisegundos. En el caso de los tokens de actualización, usa <RefreshTokenExpiresIn>. El valor de tiempo de vencimiento es un valor generado por el sistema más el valor de <ExpiresIn>. Si no se especifica <ExpiresIn>, el sistema aplica un valor predeterminado configurado a nivel del sistema.

El tiempo de vencimiento también se puede definir en el tiempo de ejecución mediante un valor predeterminado codificado o haciendo referencia a una variable de flujo. Por ejemplo, puede almacenar un valor de vencimiento de token en un mapa de pares clave-valor, recuperarlo, asignarlo a una variable y hacer referencia a él en la política. Por ejemplo, kvm.oauth.expires_in.

Apigee mantiene las siguientes entidades en la caché durante un mínimo de 180 segundos después de que se acceda a ellas.

  • Tokens de acceso OAuth. Esto significa que el elemento ExpiresIn de la política de OAuth v2 no podrá hacer que un token de acceso caduque en menos de 180 segundos.
  • Entidades de Key Management Service (KMS) (aplicaciones, desarrolladores y productos de API).
  • Atributos personalizados en tokens de OAuth y entidades de KMS.

La siguiente sección especifica una variable de flujo y un valor predeterminado. Ten en cuenta que el valor de la variable de flujo tiene prioridad sobre el valor predeterminado especificado.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee no ofrece ninguna forma de forzar el vencimiento de un token una vez que se ha creado. Si necesitas forzar la caducidad de un token (por ejemplo, en función de una condición), puedes consultar una posible solución en esta publicación de la comunidad de Apigee.

De forma predeterminada, los tokens de acceso caducados se eliminan del sistema de Apigee automáticamente 3 días después de su vencimiento. Consulta también Purgar tokens de acceso.

Predeterminado

Si no se especifica, el sistema aplica un valor predeterminado configurado a nivel del sistema.

Presencia

Opcional
Tipo Entero
Valores válidos

Cualquier número entero positivo distinto de cero. Especifica el tiempo de vencimiento en milisegundos. Aunque el valor de este elemento está en milisegundos, el valor definido en la propiedad expires_in del token y en la variable de flujo expires_in se expresa en segundos.
Se usa con tipos de concesión
  • authorization_code
  • implícito
  • contraseña
  • client_credentials
  • refresh_token

También se usa con la operación GenerateAuthorizationCode.

Elemento <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indica a Apigee dónde encontrar un token de acceso externo (un token de acceso no generado por Apigee).

La variable request.queryparam.external_access_token indica que el token de acceso externo debe estar presente como parámetro de consulta, como ?external_access_token=12345678. Para requerir el token de acceso externo en un encabezado HTTP, por ejemplo, asigna el valor request.header.external_access_token. Consulta también Usar tokens OAuth de terceros.

Elemento <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Si este elemento es falso o no está presente, Apigee valida el client_id y el client_secret normalmente en el almacén de autorización de Apigee. Utiliza este elemento cuando quieras trabajar con tokens OAuth de terceros. Para obtener información sobre cómo usar este elemento, consulta Usar tokens OAuth de terceros.

Predeterminado

falso

Presencia

Opcional
Tipo Booleano
Valores válidos verdadero o falso
Se usa con tipos de concesión
  • authorization_code
  • contraseña
  • client_credentials

Elemento <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indica a Apigee dónde encontrar un código de autorización externo (un código de autorización no generado por Apigee).

La variable request.queryparam.external_auth_code indica que el código de autorización externo debe estar presente como parámetro de consulta, como ?external_auth_code=12345678. Para requerir el código de autenticación externo en un encabezado HTTP, por ejemplo, asigna el valor request.header.external_auth_code. Consulta también Usar tokens OAuth de terceros.

Elemento <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indica a Apigee dónde encontrar un token de actualización externo (un token de actualización no generado por Apigee).

La variable request.queryparam.external_refresh_token indica que el token de actualización externo debe estar presente como parámetro de consulta, como ?external_refresh_token=12345678. Para requerir el token de actualización externo en un encabezado HTTP, por ejemplo, asigna el valor request.header.external_refresh_token. Consulta también Usar tokens OAuth de terceros.

Elemento <GenerateResponse>

<GenerateResponse enabled='true'/>

Si se le asigna el valor true o se omite el atributo enabled, la política genera una respuesta y la devuelve. Por ejemplo, en el caso de GenerateAccessToken, la respuesta podría ser la siguiente:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Si se le asigna el valor false o se omite el elemento <GenerateResponse>, no se envía ninguna respuesta. En su lugar, se rellenan una serie de variables de flujo con valores relacionados con la función de la política. Por ejemplo, una variable de flujo llamada oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code se rellena con el código de autorización recién generado. Ten en cuenta que expires_in se expresa en segundos en la respuesta.

Predeterminado

true

Presencia

Opcional
Tipo cadena
Valores válidos verdadero o falso
Se usa con tipos de concesión
  • implícito
  • contraseña
  • client_credentials
  • refresh_token
  • También se puede usar con la operación GenerateAuthorizationCode.

Elemento <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Si se le asigna el valor true, la política genera y devuelve una respuesta si el atributo ContinueOnError tiene el valor true. Si se usa false (el valor predeterminado), no se envía ninguna respuesta. En su lugar, se rellenan una serie de variables de flujo con valores relacionados con la función de la política.

Predeterminado

falso

Presencia

Opcional
Tipo cadena
Valores válidos verdadero o falso
Se usa con tipos de concesión
  • implícito
  • contraseña
  • client_credentials
  • refresh_token
  • También se puede usar con la operación GenerateAuthorizationCode.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indica a la política dónde encontrar el parámetro grant_type que se envía en una solicitud. De acuerdo con la especificación de OAuth 2.0, el tipo de concesión debe proporcionarse con las solicitudes de tokens de acceso y códigos de autorización. La variable puede ser un encabezado, un parámetro de consulta o un parámetro de formulario (opción predeterminada).

Por ejemplo, request.queryparam.grant_type indica que la contraseña debe estar presente como parámetro de consulta, como ?grant_type=password. Para requerir el tipo de concesión en un encabezado HTTP, por ejemplo, asigna el valor request.header.grant_type. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.grant_type (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo cadena
Valores válidos Una variable, como se ha explicado más arriba.
Se usa con tipos de concesión
  • authorization_code
  • contraseña
  • implícito
  • client_credentials
  • refresh_token

Elemento <Operation>

<Operation>GenerateAuthorizationCode</Operation>

La operación de OAuth 2.0 ejecutada por la política.

Predeterminado

Si no se especifica <Operation>, Apigee consulta la lista de <SupportedGrantTypes>. Solo se podrán realizar operaciones en esos tipos de concesión. Es decir, puedes omitir <Operation> si especificas un <GrantType> en la lista <SupportedGrantTypes>. Si no se especifican <Operation> ni <SupportedGrantTypes>, el tipo de concesión predeterminado es authorization_code. Es decir, las solicitudes de tipo de concesión authorization_code se completarán correctamente, pero todas las demás fallarán.

Presencia

Opcional
Tipo Cadena
Valores válidos
  • GenerateAccessToken: genera un token de acceso. Consulta también Obtener tokens de OAuth 2.0.
  • GenerateAccessTokenImplicitGrant: genera un token de acceso para el tipo de concesión implícito. Consulta también Obtener tokens de OAuth 2.0.
  • GenerateAuthorizationCode: genera un código de autorización. Se usa con el tipo de concesión de código de autorización. Consulta también Obtener tokens de OAuth 2.0.
  • RefreshAccessToken: intercambia un token de actualización por un nuevo token de acceso. Consulta también Obtener tokens de OAuth 2.0.
  • VerifyAccessToken: verifica que un token de acceso enviado en una solicitud sea válido. Consulta el ejemplo VerifyAccessToken anterior y el artículo Verificar tokens de acceso.
  • InvalidateToken: revoca un token de acceso. Una vez que se ha revocado un token, los clientes no pueden usarlo para llamar a una API protegida. Consulta también Aprobar y revocar tokens de acceso.
  • ValidateToken: restaura o "aprueba" un token de acceso que se había revocado anteriormente. Consulta también Aprobar y revocar tokens de acceso.

Operaciones adicionales con tokens de acceso JWT

Si prefieres usar tokens de acceso JWT en lugar de tokens de cadena opacos, también puedes usar las siguientes operaciones para generar y validar tokens JWT. Para obtener más información, consulta Usar operaciones de tokens de OAuth JWT:

Elemento <PassWord>

<PassWord>request.queryparam.password</PassWord>

Este elemento solo se usa con el tipo de concesión de contraseña. Con el tipo de concesión de contraseña, las credenciales de usuario (contraseña y nombre de usuario) deben estar disponibles para la política OAuthV2. Los elementos <PassWord> y <UserName> se usan para especificar variables en las que Apigee puede encontrar estos valores. Si no se especifican estos elementos, la política espera encontrar los valores (de forma predeterminada) en los parámetros de formulario denominados username y password. Si no se encuentran los valores, la política genera un error. Puedes usar los elementos <PassWord> y <UserName> para hacer referencia a cualquier variable de flujo que contenga las credenciales.

Por ejemplo, puede enviar la contraseña en una solicitud de token mediante un parámetro de consulta y definir el elemento de la siguiente manera: <PassWord>request.queryparam.password</PassWord>. Para requerir la contraseña en un encabezado HTTP, asigne el valor request.header.password.

La política OAuthV2 no hace nada más con estos valores de credenciales. Apigee simplemente verifica que estén presentes. El desarrollador de la API debe recuperar los valores de la solicitud y enviarlos a un proveedor de identidades antes de que se ejecute la política de generación de tokens.

Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.password (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo Cadena
Valores válidos Cualquier variable de flujo disponible para la política en el tiempo de ejecución.
Se usa con tipos de concesión contraseña

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Proporciona la clave privada que se usa para verificar o firmar tokens de acceso con formato JWT mediante un algoritmo RSA. Usa el atributo ref para transferir la clave en una variable de flujo. Úsalo solo cuando el valor del elemento Algorithm sea RS256, RS384 o RS512. Para obtener más información, consulta el artículo sobre cómo usar operaciones de tokens de OAuth JWT.

Predeterminado N/A
Presencia Obligatorio cuando el valor del elemento Algorithm es HS256, HS384 o HS512.
Tipo Cadena
Valores válidos Variable de flujo que contiene una cadena que representa un valor de clave privada RSA codificada en PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Especifica la clave pública o el certificado público que se usa para verificar la firma de un token de acceso con formato JWT firmado con un algoritmo RSA. Use el atributo ref para transferir la clave o el certificado en una variable de flujo. Úsalo solo cuando el valor del elemento Algorithm sea RS256, RS384 o RS512.

Predeterminado N/A
Presencia Para verificar un JWT firmado con un algoritmo RSA, debes usar los elementos Certificate, JWKS o Value.
Tipo Cadena
Valores válidos Una variable de flujo o una cadena.

Elemento <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Especifica dónde debe buscar Apigee el parámetro redirect_uri en la solicitud.

Acerca de los URIs de redirección

Los URIs de redirección se usan con los tipos de concesión de código de autorización e implícito. El URI de redirección indica al servidor de autorización (Apigee) dónde enviar un código de autorización (para el tipo de concesión de código de autorización) o un token de acceso (para el tipo de concesión implícito). Es importante saber cuándo es obligatorio este parámetro, cuándo es opcional y cómo se usa:

  • (Obligatorio) Si se registra una URL de retrollamada en la aplicación del desarrollador asociada a las claves de cliente de la solicitud y si redirect_uri está presente en la solicitud, ambas deben coincidir exactamente. Si no coinciden, se devuelve un error. Para obtener información sobre cómo registrar aplicaciones de desarrollador en Apigee y especificar una URL de retrollamada, consulta el artículo Registrar aplicaciones y gestionar claves de API.

  • (Opcional) Si se ha registrado una URL de retrollamada y falta el redirect_uri en la solicitud, Apigee redirige a la URL de retrollamada registrada.
  • Obligatorio. Si no se ha registrado ninguna URL de retrollamada, se requiere el parámetro redirect_uri. Ten en cuenta que, en este caso, Apigee aceptará CUALQUIER URL. Este caso puede suponer un problema de seguridad, por lo que solo se debe usar con aplicaciones cliente de confianza. Si las aplicaciones cliente no son de confianza, la práctica recomendada es requerir siempre el registro de una URL de retrollamada.

Puede enviar este parámetro en un parámetro de consulta o en un encabezado. La variable request.queryparam.redirect_uri indica que RedirectUri debe estar presente como parámetro de consulta, como ?redirect_uri=login.myapp.com. Para requerir el RedirectUri en un encabezado HTTP, por ejemplo, defina este valor como request.header.redirect_uri. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.redirect_uri (con el formato x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo Cadena
Valores válidos Cualquier variable de flujo accesible en la política durante el tiempo de ejecución
Se usa con tipos de concesión
  • authorization_code
  • implícito

También se usa con la operación GenerateAuthorizationCode.

Elemento <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Cuando solicites un token de acceso con un token de actualización, debes proporcionar el token de actualización en la solicitud. Este elemento le permite especificar dónde debe buscar Apigee el token de actualización. Por ejemplo, se puede enviar como parámetro de consulta, encabezado HTTP o parámetro de formulario (opción predeterminada).

La variable request.queryparam.refreshtoken indica que el token de actualización debe estar presente como parámetro de consulta, como ?refresh_token=login.myapp.com. Para requerir el RefreshToken en un encabezado HTTP, por ejemplo, asigna el valor request.header.refresh_token. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.refresh_token (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo Cadena
Valores válidos Cualquier variable de flujo accesible en la política durante el tiempo de ejecución
Se usa con tipos de concesión
  • refresh_token

Elemento <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Aplica el tiempo de vencimiento de los tokens de actualización en milisegundos. El valor de la hora de vencimiento es un valor generado por el sistema más el valor <RefreshTokenExpiresIn>. Si no se especifica <RefreshTokenExpiresIn>, el sistema aplica el valor predeterminado.

El tiempo de vencimiento también se puede definir en el tiempo de ejecución mediante un valor predeterminado codificado o haciendo referencia a una variable de flujo. Por ejemplo, puede almacenar un valor de vencimiento de token en un mapa de pares clave-valor, recuperarlo, asignarlo a una variable y hacer referencia a él en la política. Por ejemplo, kvm.oauth.expires_in.

La siguiente sección especifica una variable de flujo y un valor predeterminado. Ten en cuenta que el valor de la variable flow tiene prioridad sobre el valor predeterminado especificado.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

Predeterminado

2592000000 ms (30 días) (a partir del 31 de mayo del 2023)

Presencia

Opcional
Tipo Entero
Valores válidos

Cualquier número entero positivo distinto de cero. Especifica el tiempo de vencimiento en milisegundos.
Se usa con tipos de concesión
  • authorization_code
  • contraseña
  • refresh_token

Elemento <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Este elemento informa a Apigee sobre el tipo de concesión que solicita la aplicación cliente. Se usa solo con los flujos de tipo de concesión implícito y de código de autorización.

De forma predeterminada, Apigee busca el valor del tipo de respuesta en un parámetro de consulta response_type. Si quiere anular este comportamiento predeterminado, use el elemento <ResponseType> para configurar una variable de flujo que contenga el valor del tipo de respuesta. Por ejemplo, si asigna el valor request.header.response_type a este elemento, Apigee busca el tipo de respuesta que se va a transferir en el encabezado de la solicitud. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.response_type (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional. Utilice este elemento si quiere anular el comportamiento predeterminado.

Tipo Cadena
Valores válidos code (para el tipo de autorización de código de autorización) o token (para el tipo de autorización implícita)
Se usa con tipos de concesión
  • implícito
  • También se usa con la operación GenerateAuthorizationCode.

Elemento <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Si se define como true, el token de actualización se reutiliza hasta que caduque. Si false, Apigee emite un nuevo token de actualización cuando se presenta un token de actualización válido.

Predeterminado

false

Presencia

opcional
Tipo booleano
Valores válidos

true o false
Se usa con tipos de concesión
  • refresh_token

Elemento <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

La política OAuthV2, con la operación GenerateAccessToken, puede devolver una respuesta que no cumpla las especificaciones de OAuth 2.0 de IETF relacionadas, incluidas RFC 6749 y RFC 6750. Si incluye el elemento RFCCompliantRequestResponse en su política con el valor true, la política OAuthV2 devuelve una respuesta conforme a RFC.

En la siguiente tabla se muestran las diferencias en algunos valores devueltos por la política OAuthV2, en función de si el elemento RFCCompliantRequestResponse es true o false.

Elemento El valor es falso o no está presente El valor es true
Encabezado HTTP Cache-Control Ninguno proporcionado Las respuestas de error y las que no son de error incluirán el campo de encabezado de respuesta HTTP Cache-Control para cumplir la RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1), con el valor no-store en cualquier respuesta que contenga tokens, credenciales u otra información sensible, así como el campo de encabezado de respuesta Pragma con el valor no-cache.
Propiedad "token_type" en la respuesta del token válido

Un valor de token_type que no cumple las políticas.

{
 ...
 "token_type": "BearerToken",
 ...
}

Un valor token_type conforme.

{
 ...
 "token_type": "Bearer",
 ...
}
Propiedades "expires_in" y "refresh_token_expires_in" en una respuesta de token válida

El valor numérico está entre comillas. Ejemplo:

{
 ...
 "expires_in": "3600",
 "refresh_token_expires_in":
   "345600",
 ...
}

El valor se serializa como un número, no como una cadena. Ejemplo: 

{
 ...
 "expires_in": 3600,
 "refresh_token_expires_in":
   345600,
 ...
}
Respuesta de error de un token de actualización caducado cuando grant_type = refresh_token

Las respuestas de error no cumplían el estándar RFC 6749. Ejemplo:

{
 "ErrorCode": "InvalidRequest",
 "Error": "Refresh Token expired"
}

Las cargas útiles de las respuestas de error incluirán los elementos "error" y "error_description". Ejemplo:

{
 "error": "invalid_grant",
 "error_description":
   "refresh token expired"
}

Predeterminado

false: de forma predeterminada, la política mostrará determinados comportamientos que no cumplen el RFC, como se ha descrito anteriormente.

Presencia

Opcional
Tipo Booleano
Valores válidos true o false
Se usa con tipos de concesión Todo

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Proporciona la clave secreta que se usa para verificar o firmar tokens de acceso con formato JWT mediante un algoritmo HMAC. Úsalo solo cuando el algoritmo sea HS256, HS384 o HS512. Usa el atributo ref para transferir la clave en una variable de flujo. Para obtener más información, consulta el artículo sobre cómo usar operaciones de tokens de OAuth JWT.

Apigee aplica una longitud mínima de clave para los algoritmos HS256, HS384 y HS512. La longitud mínima de la clave de HS256 es de 32 bytes, la de HS384 es de 48 bytes y la de HS512 es de 64 bytes. Si se usa una clave con una seguridad inferior, se produce un error de tiempo de ejecución.

Predeterminado N/A
Presencia Obligatorio para los algoritmos HMAC.
Tipo Cadena
Valores válidos Una variable de flujo

Elemento <Scope>

<Scope>request.queryparam.scope</Scope>

Si este elemento está presente en una de las políticas GenerateAccessToken o GenerateAuthorizationCode, se usa para especificar a qué ámbitos se debe conceder el token o el código. Estos valores se suelen transferir a la política en la solicitud de una aplicación cliente. Puede configurar el elemento para que tome una variable de flujo, lo que le permite elegir cómo se transfieren los ámbitos en una solicitud. En el ejemplo siguiente, request.queryparam.scope indica que el ámbito debe estar presente como parámetro de consulta, como ?scope=READ. Para requerir el ámbito en un encabezado HTTP, por ejemplo, asigna a este valor el valor request.header.scope.

Si este elemento aparece en una política "VerifyAccessToken", se usa para especificar los ámbitos que debe aplicar la política. En este tipo de política, el valor debe ser un nombre de ámbito codificado de forma rígida. No se pueden usar variables. Por ejemplo:

<Scope>A B</Scope>

Consulta también Usar permisos OAuth2 y Obtener tokens de OAuth 2.0.

Predeterminado

Sin ámbito

Presencia

Opcional
Tipo Cadena
Valores válidos

Si se usa con políticas Generate*, una variable de flujo.

Si se usa con VerifyAccessToken, una lista de nombres de ámbito (cadenas) separados por espacios.
Se usa con tipos de concesión
  • authorization_code
  • implícito
  • contraseña
  • client_credentials
  • También se puede usar con las operaciones GenerateAuthorizationCode y VerifyAccessToken.

Elemento <State>

<State>request.queryparam.state</State>

En los casos en los que la aplicación cliente debe enviar la información de estado al servidor de autorización, este elemento le permite especificar dónde debe buscar Apigee los valores de estado. Por ejemplo, se puede enviar como un parámetro de consulta o en un encabezado HTTP. El valor de estado se suele usar como medida de seguridad para evitar ataques CSRF.

Por ejemplo, request.queryparam.state indica que el estado debe estar presente como parámetro de consulta, como ?state=HjoiuKJH32. Para requerir el estado en un encabezado HTTP, por ejemplo, defina este valor en request.header.state. Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

Ningún estado

Presencia

Opcional
Tipo Cadena
Valores válidos Cualquier variable de flujo a la que pueda acceder la política durante el tiempo de ejecución
Se usa con tipos de concesión
  • Todo
  • También se puede usar con la operación GenerateAuthorizationCode.

Elemento <StoreToken>

 <StoreToken>true</StoreToken>

Asigna el valor true a este elemento cuando el elemento <ExternalAuthorization> sea true. El elemento <StoreToken> indica a Apigee que almacene el token de acceso externo. De lo contrario, no se conservará.

Predeterminado

falso

Presencia

Opcional
Tipo Booleano
Valores válidos verdadero o falso
Se usa con tipos de concesión
  • authorization_code
  • contraseña
  • client_credentials

Elemento <SupportedGrantTypes>/<GrantType> 

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Especifica los tipos de concesión admitidos por un endpoint de token de OAuth en Apigee. Un endpoint puede admitir varios tipos de concesión (es decir, un solo endpoint se puede configurar para distribuir tokens de acceso de varios tipos de concesión). Para obtener más información sobre los endpoints, consulta Información sobre los endpoints de OAuth. El tipo de concesión se transfiere en las solicitudes de token mediante un parámetro grant_type.

Si no se especifica ningún tipo de concesión admitido, los únicos tipos de concesión permitidos son authorization_code y implicit. Consulte también el elemento <GrantType> (que es un elemento de nivel superior que se usa para especificar dónde debe buscar Apigee el parámetro grant_type que se transfiere en una solicitud de cliente. Apigee se asegurará de que el valor del parámetro grant_type coincida con uno de los tipos de concesión admitidos.

Predeterminado

código de autorización e implícito

Presencia

Obligatorio
Tipo Cadena
Valores válidos
  • client_credentials
  • authorization_code
  • contraseña
  • implícito

Elemento <Tokens>/<Token>

Se usa con las operaciones ValidateToken e InvalidateToken. Consulta también Aprobar y revocar tokens de acceso. El elemento <Token> identifica la variable de flujo que define la fuente del token que se va a revocar. Si se espera que los desarrolladores envíen tokens de acceso como parámetros de consulta llamados access_token, por ejemplo, usa request.queryparam.access_token.

Elemento <UserName>

<UserName>request.queryparam.user_name</UserName>

Este elemento solo se usa con el tipo de concesión de contraseña. Con el tipo de concesión de contraseña, las credenciales de usuario (contraseña y nombre de usuario) deben estar disponibles para la política OAuthV2. Los elementos <PassWord> y <UserName> se usan para especificar variables en las que Apigee puede encontrar estos valores. Si no se especifican estos elementos, la política espera encontrar los valores (de forma predeterminada) en los parámetros de formulario denominados username y password. Si no se encuentran los valores, la política genera un error. Puedes usar los elementos <PassWord> y <UserName> para hacer referencia a cualquier variable de flujo que contenga las credenciales.

Por ejemplo, puede enviar el nombre de usuario en un parámetro de consulta y definir el elemento <UserName> de la siguiente manera: <UserName>request.queryparam.username</UserName>.Para requerir el nombre de usuario en un encabezado HTTP, defina este valor como request.header.username.

La política OAuthV2 no hace nada más con estos valores de credenciales. Apigee simplemente verifica que estén presentes. El desarrollador de la API debe recuperar los valores de la solicitud y enviarlos a un proveedor de identidades antes de que se ejecute la política de generación de tokens.

Consulta también Obtener tokens de OAuth 2.0.

Predeterminado

request.formparam.username (x-www-form-urlencoded y especificado en el cuerpo de la solicitud)

Presencia

Opcional
Tipo Cadena
Valores válidos Cualquier ajuste de variable.
Se usa con tipos de concesión contraseña

Verificar tokens de acceso

Una vez que se ha configurado un endpoint de token para un proxy de API, se adjunta una política OAuthV2 correspondiente que especifica la operación VerifyAccessToken al flujo que expone el recurso protegido.

Por ejemplo, para asegurarse de que todas las solicitudes a una API están autorizadas, la siguiente política aplica la verificación del token de acceso:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

La política se asocia al recurso de API que se va a proteger. Para asegurarse de que se verifiquen todas las solicitudes a una API, adjunte la política al PreFlow de la solicitud ProxyEndpoint de la siguiente manera:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Los siguientes elementos opcionales se pueden usar para anular los ajustes predeterminados de la operación VerifyAccessToken.

Nombre Descripción
Ámbito

Lista de ámbitos delimitada por espacios. La verificación se realizará correctamente si al menos uno de los ámbitos indicados está presente en el token de acceso. Por ejemplo, la siguiente política comprobará el token de acceso para asegurarse de que contiene al menos uno de los ámbitos enumerados. Si se incluye READ o WRITE, la verificación se realizará correctamente.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken Variable en la que se espera que se encuentre el token de acceso. Por ejemplo: request.queryparam.accesstoken. De forma predeterminada, se espera que la aplicación presente el token de acceso en el encabezado HTTP Authorization, de acuerdo con la especificación de OAuth 2.0. Usa este ajuste si se espera que el token de acceso se presente en una ubicación no estándar, como un parámetro de consulta o un encabezado HTTP con un nombre distinto de Authorization.

Consulta también Verificar tokens de acceso y Obtener tokens de OAuth 2.0.

Especificar las ubicaciones de las variables de solicitud

En cada tipo de concesión, la política hace suposiciones sobre la ubicación o la información necesaria en los mensajes de solicitud. Estas suposiciones se basan en la especificación de OAuth 2.0. Si tus aplicaciones necesitan desviarse de la especificación de OAuth 2.0, puedes especificar las ubicaciones esperadas de cada parámetro. Por ejemplo, al gestionar un código de autorización, puede especificar la ubicación del código de autorización, el ID de cliente, el URI de redirección y el ámbito. Se pueden especificar como encabezados HTTP, parámetros de consulta o parámetros de formulario.

En el ejemplo siguiente se muestra cómo puede especificar la ubicación de los parámetros de código de autorización obligatorios como encabezados HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

También puedes combinar encabezados y parámetros de consulta si es necesario para admitir tu base de aplicaciones cliente:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Solo se puede configurar una ubicación por parámetro.

Variables de flujo

Las variables de flujo definidas en esta tabla se rellenan cuando se ejecutan las políticas de OAuth correspondientes y, por lo tanto, están disponibles para otras políticas o aplicaciones que se ejecuten en el flujo del proxy de API.

Operación VerifyAccessToken

Cuando se ejecuta la operación VerifyAccessToken, se rellenan un gran número de variables de flujo en el contexto de ejecución del proxy. Estas variables te proporcionan propiedades relacionadas con el token de acceso, la aplicación del desarrollador y el desarrollador. Puedes usar una política AssignMessage o JavaScript, por ejemplo, para leer cualquiera de estas variables y usarlas según sea necesario más adelante en el flujo. Estas variables también pueden ser útiles para depurar errores.

Variables específicas de tokens

Variables Descripción
organization_name Nombre de la organización en la que se ejecuta el proxy.
developer.id El ID del desarrollador o del AppGroup asociado a la aplicación cliente registrada.
developer.app.name El nombre del desarrollador o de la aplicación AppGroup asociada a la aplicación cliente registrada.
client_id ID de cliente de la aplicación cliente registrada.
grant_type El tipo de concesión asociado a la solicitud. No se admite en la operación VerifyJWTAccessToken.
token_type El tipo de token asociado a la solicitud.
access_token El token de acceso que se está verificando.
accesstoken.{custom_attribute} Un atributo personalizado con nombre en el token de acceso.
issued_at Fecha en la que se emitió el token de acceso, expresada en tiempo de época de Unix en milisegundos.
expires_in Hora de vencimiento del token de acceso. Se expresa en segundos. Aunque el elemento ExpiresIn define la caducidad en milisegundos, en la respuesta del token y en las variables de flujo, el valor se expresa en segundos.
status El estado del token de acceso (por ejemplo, aprobado o revocado).
scope El ámbito (si lo hay) asociado al token de acceso.
apiproduct.<custom_attribute_name> Atributo personalizado con nombre del producto de la API asociado a la aplicación cliente registrada.
apiproduct.name Nombre del producto de API asociado a la aplicación cliente registrada.
revoke_reason

(Solo Apigee hybrid) Indica por qué se revoca el token de acceso. No se admite en la operación VerifyJWTAccessToken.

El valor puede ser REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER o TOKEN_REVOKED.

Variables específicas de la aplicación

Estas variables están relacionadas con la aplicación de desarrollador asociada al token.

Variables Descripción
app.name
app.id
app.accessType
app.callbackUrl
app.status aprobada o revocada
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType Por ejemplo: Desarrollador
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} Atributo personalizado con nombre de la aplicación cliente registrada.

Variables específicas de AppGroup

Las siguientes variables de flujo contienen información sobre el AppGroup del token y se rellenan con la política. Estos atributos de AppGroup solo se rellenan si verifyapikey.{policy_name}.app.appType es "AppGroup".

Variables Descripción
appgroup.displayName Nombre visible de AppGroup.
appgroup.name Nombre del AppGroup.
appgroup.id ID de AppGroup.
appOwnerStatus El estado del propietario de la aplicación: "active", "inactive" o "login_lock".
created_at Marca de fecha y hora en la que se creó el AppGroup.
created_by La dirección de correo del desarrollador que creó el AppGroup.
last_modified_at Marca de fecha y hora de la última modificación de AppGroup.
last_modified_by La dirección de correo del desarrollador que modificó el AppGroup por última vez.
{appgroup_custom_attributes} Cualquier atributo personalizado de AppGroup. Especifica el nombre del atributo personalizado.

Variables específicas del desarrollador

Si el valor de app.appType es "Developer", se rellenan los atributos del desarrollador.

Variables Descripción
Variables específicas del desarrollador
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status Activo o inactivo
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} Atributo personalizado con nombre del desarrollador.

Operación GenerateAuthorizationCode

Estas variables se definen cuando se ejecuta correctamente la operación GenerateAuthorizationCode:

Prefijo: oauthv2authcode.{policy_name}.{variable_name}

Ejemplo: oauthv2authcode.GenerateCodePolicy.code

Variable Descripción
code El código de autorización generado cuando se ejecuta la política.
redirect_uri La URI de redireccionamiento asociada a la aplicación cliente registrada.
scope El ámbito de OAuth opcional que se ha transferido en la solicitud del cliente.
client_id El ID de cliente que se ha enviado en la solicitud del cliente.

Operaciones GenerateAccessToken y RefreshAccessToken

Estas variables se definen cuando se ejecutan correctamente las operaciones GenerateAccessToken y RefreshAccessToken. Ten en cuenta que las variables de token de actualización no se aplican al flujo de tipo de concesión de credenciales de cliente.

Prefijo: oauthv2accesstoken.{policy_name}.{variable_name}

Ejemplo: oauthv2accesstoken.GenerateTokenPolicy.access_token

Nombre de variable Descripción
access_token Token de acceso que se ha generado.
client_id ID de cliente de la aplicación de desarrollador asociada a este token.
expires_in Valor de vencimiento del token. Consulta los detalles del elemento <ExpiresIn>. Ten en cuenta que, en la respuesta, expires_in se expresa en segundos.
scope Lista de los permisos disponibles configurados para el token. Consulta Usar permisos OAuth2.
status Puede ser approved o revoked.
token_type Se ha definido como BearerToken.
developer.email La dirección de correo del desarrollador registrado propietario de la aplicación de desarrollador asociada al token.
organization_name La organización en la que se ejecuta el proxy.
api_product_list Lista de los productos asociados a la aplicación de desarrollador correspondiente al token.
refresh_count
refresh_token Token de actualización que se ha generado. Ten en cuenta que no se generan tokens de actualización para el tipo de autorización de credenciales de cliente.
refresh_token_expires_in Tiempo de vida del token de actualización, en segundos.
refresh_token_issued_at Este valor temporal es la representación de cadena de la cantidad de marca de tiempo de 32 bits correspondiente. Por ejemplo, "Wed, 21 Aug 2013 19:16:47 UTC" corresponde al valor de marca de tiempo 1377112607413.
refresh_token_status Puede ser approved o revoked.

GenerateAccessTokenImplicitGrant

Estas variables se definen cuando la operación GenerateAccessTokenImplicit se ejecuta correctamente en el flujo del tipo de concesión implícita.

Prefijo: oauthv2accesstoken.{policy_name}.{variable_name}

Ejemplo: oauthv2accesstoken.RefreshTokenPolicy.access_token

Variable Descripción
oauthv2accesstoken.access_token El token de acceso generado cuando se ejecuta la política.
oauthv2accesstoken.{policy_name}.expires_in Valor de vencimiento del token, en segundos. Consulta los detalles del elemento <ExpiresIn>.

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.

Fault code HTTP status Cause Thrown by operations
steps.oauth.v2.access_token_expired 401 The access token is expired.

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 The access token was revoked. VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist 401 The requested API product does not exist in any of the API products associated with the access token. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. VerifyAccessToken
steps.oauth.v2.invalid_client 401

This error name is returned when the <GenerateResponse> property of the policy is set to true and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidRequest 400 This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 The authorization header does not have the word Bearer, which is required. For example: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401

The currently executing API proxy or operation is not in the Product associated with the access token.

Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Managing API products for details.

See also Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for more guidance on causes for this error.

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 The policy must specify either an access token or an authorization code, but not both. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 The response type is token, but no grant types are specified. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element).

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

JWT token-specific runtime errors

Runtime error codes and descriptions for JWT auth token flows depend on the OAuth2 flow context:

Error codes for JWT token generation and refresh flows

For OAuth2 flows that generate or refresh JWT tokens, error responses adhere to the error responses specified in RFC6749. For details, see Section 5.2 Error Response.

Error codes for the token verification flow

The error codes listed in the following table apply to VerifyAccessToken operation only.

Fault code HTTP status Cause Thrown by operations
oauth.v2.JWTSigningFailed 401 The policy was unable to sign the JWT.

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 This occurs when the algorithm is not present in the JWT access token or when the value is not supported.

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 In Generation of JWT, for a key less than the minimum size for the HS384 or HS512 algorithms

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 Occurs when the required claims are not present in the Jwt Access token

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 This occurs when the signature of JWT access token could not be verified or when the signature is invalid.

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 Occurs when the JWT's type is not at+Jwt

VerifyJWTAccessToken

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
InvalidValueForExpiresIn

For the <ExpiresIn> element, valid values are positive integers.
InvalidValueForRefreshTokenExpiresIn For the <RefreshTokenExpiresIn> element, valid values are positive integers.
InvalidGrantType An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired

You must specify an operation in this policy using the <Operation> element.
InvalidOperation

You must specify a valid operation in this policy using the <Operation> element.
TokenValueRequired You must specify a token <Token> value in the <Tokens> element.

JWT token-specific deployment errors

These deployment errors are specific to policies that use JWT token operations.

Error name Cause
InvalidValueForAlgorithm The algorithm specified in the <Algorithm> element is not among the list of available algorithms or is not present.
MissingKeyConfiguration The required <SecretKey>, <PrivateKey>, or <PublicKey> elements are missing, depending on which algorithm is used.
EmptyValueElementForKeyConfiguration The required child element <Value> is not defined in the <PrivateKey>, <PublicKey>, or <SecretKey> elements
InvalidKeyConfiguration The <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
EmptyRefAttributeForKeyconfiguration The ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements is empty.
InvalidVariableNameForKey The flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements does not contain the private prefix.

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 = "InvalidRequest"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Los tokens de almacenamiento están cifrados con hash

Si usas Apigee hybrid o Apigee, los tokens de acceso y de actualización de OAuthV2 se cifran de forma predeterminada cuando se almacenan en la base de datos de Cassandra del tiempo de ejecución. El cifrado con hash impide que se usen los tokens si la base de datos se viera vulnerada.

Trabajar con la configuración predeterminada de OAuth

Cada organización de Apigee (incluso las de prueba gratuita) se aprovisiona con un endpoint de token OAuth. El endpoint está preconfigurado con políticas en el proxy de API llamado oauth. Puedes empezar a usar el endpoint de token en cuanto crees una cuenta en Apigee. Para obtener más información, consulta Comprender los endpoints de OAuth.

Purgar tokens de acceso

De forma predeterminada, los tokens de OAuth2 se purgan del sistema de Apigee 3 días (259.200 segundos) después de que hayan caducado tanto el token de acceso como el token de actualización (si existe).

Temas relacionados