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.

Ejemplos

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 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 la siguiente manera: 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 autorizació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 será 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): te permite especificar si los atributos personalizados aparecen o no 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 autorizació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 del tiempo de vencimiento 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 asignar 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 autorizació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 autorización authorization_code

Elemento <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Aplica el tiempo de caducidad 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 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 autorizació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 autorizació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 autorizació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 se define como true. Si false (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 autorizació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 transfiere 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 autorizació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, puedes 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, asigna 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 es quien 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 autorizació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. Usa 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 debe usarse 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 autorizació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 autorizació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 autorizació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 asignas el valor request.header.response_type a este elemento, Apigee buscará el tipo de respuesta que se haya pasado 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ícito)
Se usa con tipos de autorizació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 autorización
  • refresh_token

Elemento <RFCCompliantRequestResponse>

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

Cuando se true, la política cumple los estándares de RFC6749 y habilita los siguientes comportamientos:

  • Las respuestas con y sin errores incluirán el campo de encabezado de respuesta HTTP Cache-Control para cumplir la RFC2616 (Protocolo de transferencia de hipertexto: 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.
  • La propiedad expires_in tendrá un formato alfanumérico. Para mantener la coherencia, el refresh_token_expires_in también será alfanumérico.
  • Las respuestas de OAuth V2 para la generación de tokens incluirán el campo de encabezado Bearer que cumple el RFC en lugar de BearerToken.
  • Los mensajes de error de las cargas útiles de respuesta tendrán el formato {"error" : "xxx", "error_description" :"yyy"} para los errores de token de actualización.

Predeterminado

false: de forma predeterminada, la política permite determinados comportamientos que no cumplen el RFC. Para obtener más información, consulta Comportamiento no conforme a RFC. Asigna el valor true a este elemento para habilitar el cumplimiento de RFC.

Presencia

Opcional
Tipo Booleano
Valores válidos true o false
Se usa con tipos de autorizació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 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 autorizació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 autorizació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 autorizació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 Comprender 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 es quien 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 autorizació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 especificar la ubicación de los parámetros del código de autorización necesarios 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 muchas 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

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

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa Arrojados por operaciones
steps.oauth.v2.access_token_expired 401 El token de acceso expiró.

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 El token de acceso se revocó. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 El recurso solicitado no existe en ninguno de los productos de API asociados con el token de acceso. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 La política esperaba encontrar un token de acceso en una variable especificada en el elemento <AccessToken>, pero no se pudo resolver la variable. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 La política esperaba encontrar un código de autorización en una variable especificada en el elemento <Code>, pero no se pudo resolver la variable. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 La política esperaba encontrar el ID de cliente en una variable especificada en el elemento <ClientId>, pero no se pudo resolver la variable. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 La política esperaba encontrar un token de actualización en una variable especificada en el elemento <RefreshToken>, pero no se pudo resolver la variable. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 La política esperaba encontrar un token en una variable especificada en el elemento <Tokens>, pero no se pudo resolver la variable.

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 El token de acceso presentado en la solicitud tiene un permiso que no coincide con el permiso especificado en la política de verificación de token de acceso. Para obtener información sobre el alcance, consulta Trabaja con permisos de OAuth2. VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 No es válido el token de acceso que se envió desde el cliente. VerifyAccessToken
steps.oauth.v2.invalid_client 401

Este nombre de error se muestra cuando la propiedad <GenerateResponse> de la política se establece como true y el ID de cliente enviado en la solicitud no es válido. Asegúrate de usar la clave de cliente y los valores secretos correctos para la app para desarrolladores asociada con tu proxy. Por lo general, estos valores se envían como un encabezado de autorización básica codificado en base64.

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.invalid_request 400 Este nombre de error se usa para varios tipos de errores, por lo general, para parámetros incorrectos o faltantes de la solicitud enviada. Si <GenerateResponse> está configurado como false, usa las variables de falla (descritas a continuación) para recuperar detalles sobre el error, como el nombre y la causa de la falla. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 El encabezado de autorización no tiene la palabra Bearer, que es obligatoria. Por ejemplo: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
ApiProductMatchFound		 401

La operación o el proxy de API que se encuentra en ejecución no está en el producto asociado con el token de acceso.

Sugerencias: Asegúrate de que el producto asociado con el token de acceso esté configurado correctamente. Por ejemplo, si usas comodines en las rutas de acceso a los recursos, asegúrate de que los comodines se usen correctamente. Consulta Administra productos de API para obtener más información.

Consulta también la Verificación del token de acceso de Oauth2.0 muestra el error “Llamada a la API no válida porque no se encontró ninguna coincidencia de apiproduct” para obtener más instrucciones sobre las causas de este error.

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

Este nombre de error se muestra cuando la propiedad <GenerateResponse> de la política se establece en false y el ID de cliente enviado en la solicitud no es válido. Asegúrate de usar la clave de cliente y los valores secretos correctos para la app para desarrolladores asociada con tu proxy. Por lo general, estos valores se envían como un encabezado de autorización básica codificado en base64.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 La política debe especificar un token de acceso o un código de autorización, pero no ambos. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 El elemento <Tokens>/<Token> requiere que especifiques el tipo de token (por ejemplo, refreshtoken). Si el cliente pasa el tipo incorrecto, se genera este error. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 El tipo de respuesta es token, pero no se especifican tipos de otorgamiento. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

El cliente especificó un tipo de otorgamiento que no es compatible con la política (no incluido en el elemento <SupportedGrantTypes>).

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

Errores específicos de entorno de ejecución del token JWT

Los códigos de error del entorno de ejecución y las descripciones para los flujos del token de autenticación JWT dependen del contexto del flujo de OAuth2:

Códigos de error para los flujos de generación y actualización de tokens de JWT

Para los flujos de OAuth2 que generan o actualizan tokens de JWT, las respuestas de error se rigen por las respuestas de error especificadas en RFC6749. Para obtener más información, consulta la Sección 5.2 Respuesta de error.

Códigos de error del flujo de verificación de tokens

Los códigos de error que se enumeran en la siguiente tabla se aplican solo a la operación VerifyAccessToken.

Código de falla Estado de HTTP Causa Arrojados por operaciones
oauth.v2.JWTSigningFailed 401 La política no pudo firmar el JWT.

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 Esto ocurre cuando el algoritmo no está presente en el token de acceso de JWT o cuando el valor no es compatible.

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 En la generación de JWT, en el caso de una clave que es menor que el tamaño mínimo para los algoritmos HS384 o HS512

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 El algoritmo especificado en la política de generación no coincide con el esperado en la política de verificación. Los algoritmos especificados deben coincidir.

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 La política no pudo decodificar el JWT. Es posible que el JWT esté dañado.

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 Ocurre cuando las reclamaciones obligatorias no están presentes en el token de acceso de JWT.

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 Esto ocurre cuando no se puede verificar la firma del token de acceso de JWT o cuando esta no es válida.

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 Ocurre cuando el tipo de JWT no es at+Jwt.

VerifyJWTAccessToken

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa
InvalidValueForExpiresIn

Para el elemento <ExpiresIn>, los valores válidos son números enteros positivos y -1.
InvalidValueForRefreshTokenExpiresIn Para el elemento <RefreshTokenExpiresIn>, los valores válidos son números enteros positivos y -1.
InvalidGrantType Se especifica un tipo de otorgamiento no válido en el elemento <SupportedGrantTypes>. Consulta la referencia de la política para obtener una lista de tipos válidos.
ExpiresInNotApplicableForOperation Asegúrate de que las operaciones especificadas en el elemento <Operations> admitan el vencimiento. Por ejemplo, la operación VerifyToken no lo hace.
RefreshTokenExpiresInNotApplicableForOperation Asegúrate de que las operaciones especificadas en el elemento <Operations> admitan el vencimiento del token. Por ejemplo, la operación VerifyToken no lo hace.
GrantTypesNotApplicableForOperation Asegúrate de que los tipos de otorgamiento especificados en <SupportedGrantTypes> sean compatibles con la operación especificada.
OperationRequired

Debes especificar una operación en esta política mediante el elemento <Operation>.
InvalidOperation

Debes especificar una operación válida en esta política con el elemento <Operation>.
TokenValueRequired Debes especificar un valor <Token> del token en el elemento <Tokens>.

Errores específicos de implementación del token JWT

Estos errores de implementación son específicos de las políticas que usan operaciones de token de JWT.

Nombre del error Causa
InvalidValueForAlgorithm El algoritmo especificado en el elemento <Algorithm> no se encuentra entre la lista de algoritmos disponibles o no está presente.
MissingKeyConfiguration Faltan los elementos <SecretKey>, <PrivateKey> o <PublicKey> obligatorios, según el algoritmo que se use.
EmptyValueElementForKeyConfiguration El elemento secundario obligatorio <Value> no está definido en los elementos <PrivateKey>, <PublicKey> ni <SecretKey>.
InvalidKeyConfiguration El elemento <PrivateKey> no se usa con algoritmos de la familia RSA o el elemento <SecretKey> no se usa con algoritmos de la familia HS.
EmptyRefAttributeForKeyconfiguration El atributo ref del elemento secundario <Value> de los elementos <PrivateKey>, <PublicKey> o <SecretKey> está vacío.
InvalidVariableNameForKey El nombre de la variable de flujo especificado en el atributo ref del elemento secundario <Value> de los elementos <PrivateKey>, <PublicKey> o <SecretKey> no contiene el prefijo private.

Variables con fallas

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

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name = "invalid_request"
oauthV2.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name es el nombre especificado por el usuario de la política que generó la falla. oauthV2.GenerateAccesstoken.fault.name = invalid_request
oauthV2.policy_name.fault.cause policy_name es el nombre especificado por el usuario de la política que generó la falla. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Ejemplo de respuesta de error

Estas respuestas se envían al cliente si el elemento <GenerateResponse> es true.

Si <GenerateResponse> es true, la política muestra errores en este formato para las operaciones que generan tokens y códigos. Para obtener una lista completa, consulta la referencia de respuesta de error de HTTP de OAuth.

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

Si <GenerateResponse> es true, la política muestra errores en este formato para verificar y validar operaciones. Para obtener una lista completa, consulta la referencia de respuesta de falla de HTTP de OAuth.

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

Ejemplo de regla de falla

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

Comportamiento que no cumple los RFC

De forma predeterminada, la política OAuthV2, con la operación GenerateAccessToken, devuelve una respuesta de token que contiene determinadas propiedades que no cumplen el RFC. En la siguiente tabla se muestran las propiedades no conformes devueltas por la política OAuthV2 y las propiedades conformes correspondientes.

al elemento RFCCompliantRequestResponse.
Devoluciones de OAuthV2: La propiedad que cumple el RFC es:
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

El valor conforme es un número, no una cadena.

Además, la respuesta de error de un token de actualización caducado cuando grant_type = refresh_token es la siguiente:

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

Sin embargo, la respuesta conforme a RFC es la siguiente: 

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

Temas relacionados