Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de Apigee Edge.
Qué
OAuthV2 es una política multifacética para realizar operaciones de tipo de otorgamiento de OAuth 2.0. Esta es la política principal que se usa para configurar los extremos de OAuth 2.0 en Apigee.
Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.
Sugerencia: Si deseas obtener más información sobre OAuth en Apigee, consulta la página principal de OAuth. Proporciona vínculos a recursos, muestras, videos y mucho más.
Ejemplos
VerifyAccessToken
VerifyAccessToken
Esta configuración de política de OAuthV2 (con la operación VerifyAccessToken) verifica que el token de acceso que se envía 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, la solicitud puede continuar. Si no es válido, se detendrán todos los procesamientos y se muestra un error en la respuesta.
<OAuthV2 name="OAuthV2-Verify-Access-Token"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Una aplicación cliente deberá enviar una solicitud con un token. Por ejemplo, con curl, podría ser la siguiente:
$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \ -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"
En el que API_ENDPOINT es el dominio que se usa para acceder a tus API, como se configuró en tu sistema Apigee.
De forma predeterminada, la política de OAuthV2 extrae el token de acceso del encabezado Authorization
y quita el prefijo Bearer
. Puedes cambiar este comportamiento predeterminado con el elemento de configuración AccessToken
.
GenerateAccessToken
Generating access tokens
Para ver ejemplos de cómo solicitar tokens de acceso para cada uno de los tipos de otorgamiento admitidos, consulta Obtén tokens de OAuth 2.0. El tema incluye ejemplos de estas operaciones:
GenerateAuthorizationCode
Genera un código de autorización
Para ver ejemplos de cómo solicitar códigos de autorización, consulta Solicita un código de autorización.
RefreshAccessToken
Cómo actualizar un token de acceso
Si deseas ver ejemplos que muestran cómo solicitar tokens de acceso con un token de actualización, consulta Actualiza un token de acceso.
Tokens de acceso JWT
Tokens de acceso JWT
Si deseas ver ejemplos que muestran cómo generar, verificar y actualizar tokens de acceso JWT, consulta Usa tokens de acceso JWT.
Token de flujo de respuesta
Genera un token de acceso en el flujo de respuesta
En ocasiones, es posible que debas generar un token de acceso en el flujo de respuesta. Por ejemplo, puedes hacer esto en respuesta a alguna validación personalizada realizada en un servicio de backend. En este ejemplo, el caso de uso requiere un token de acceso y uno de actualización, que determina el tipo de otorgamiento implícito. En este caso, usaremos el tipo de otorgamiento de contraseña para generar el token. Como puedes observar, el truco para realizar este trabajo es pasar un encabezado de solicitud de autorización con una política de JavaScript.
Primero, veamos la política de muestra:
<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 estableces esta política en el flujo de respuesta, fallará con un error 401 de falta de autorización, aunque los parámetros de acceso correctos se especifiquen en la política. Para solucionar este problema, debes configurar un encabezado de solicitud de autorización.
El encabezado de autorización debe contener un esquema de acceso básico codificado con Base64 client_id:client_secret.
Puedes agregar este encabezado con una política de JavaScript colocada justo antes de la política de OAuthV2, de la siguiente manera. Las variables “local_clientid” y “local_secret” deben estar configuradas y 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 Codifica las credenciales de autenticación básica.
Referencia de elementos
La referencia de política describe los elementos y atributos de la política OAuthV2.
La política de muestra que se presenta a continuación es una de las muchas configuraciones posibles. En esta muestra, se presenta una política de OAuthV2 configurada para la operación GenerateAccessToken. Incluye elementos obligatorios y opcionales. Consulta las descripciones de los elementos en esta sección para obtener más detalles.
<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 de <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 principales de las políticas:
Atributo | Descripción | Predeterminado | Presencia |
---|---|---|---|
name |
El nombre interno de la política. El valor del atributo De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
falso | Opcional |
enabled |
Configúralo como Configúralo como |
true | Opcional |
async |
Este atributo dejó de estar disponible. |
falso | Obsoleta |
Elemento <DisplayName>
Se usan además del atributo name
para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
<DisplayName>Policy Display Name</DisplayName>
Predeterminada |
N/A Si omites este elemento, se usa el valor del atributo |
---|---|
Presencia | Opcional |
Tipo | String |
Elemento <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
De forma predeterminada, cuando Operation
es VerifyAccessToken
, la política espera que el token de acceso se envíe en el encabezado Authorization
como un token del portador. es decir, con un prefijo “Bearer” seguido de un espacio en blanco.
Puedes cambiar ese valor predeterminado con este elemento y especificar el nombre de una variable que contiene el token de acceso que se verificará. Cuando usas este elemento, la política predeterminada no busca un prefijo en el contenido de la variable. Si deseas 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 pasar 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 pasar el token con curl, puedes usar el siguiente comando:
curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"
En el que API_ENDPOINT es el dominio que se usa para acceder a tus APIs, como se configuró en tu sistema Apigee.
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: |
cualquier nombre de variable |
Usadas con operaciones: |
|
Elemento <AccessTokenPrefix>
<AccessTokenPrefix>Prefix</AccessTokenPrefix>
De forma predeterminada, cuando Operation
es VerifyAccessToken
, la política espera que el token de acceso se envíe en el encabezado Authorization
como un token del portador. es decir, con un prefijo “Bearer” seguido de un espacio en blanco.
Si usas el elemento AccessToken
a fin de especificar una ubicación diferente para el token de acceso entrante, también puedes usar este elemento, AccessTokenPrefix
, a fin de especificar otro, prefijo no estándar.
Por ejemplo:
<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.header.token</AccessToken> <AccessTokenPrefix>KEY</AccessTokenPrefix> </OAuthV2>
Luego, la política extraerá el token de acceso entrante desde el encabezado de la solicitud token
, de esta manera: si el encabezado comienza con la palabra “KEY” seguida de un espacio, la política quitará ese prefijo y espacio y, luego, interpretar el valor restante como el token de acceso. Si el prefijo especificado no está presente en el encabezado, la política arrojará una falla.
Si especificas el elemento AccessToken
y no especificas el elemento AccessTokenPrefix
, la política interpretará todo el valor de la variable especificada dentro del elemento AccessToken
como el token de acceso.
Este elemento es efectivo solo cuando también se usa el elemento AccessToken
.
Predeterminado: |
-ninguno- |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: |
cualquier cadena |
Usadas con operaciones: |
|
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Especifica el algoritmo de encriptación que se usa para firmar un token de acceso JWT. Los algoritmos RSA (RS*) usan un par de claves públicas/secretas, mientras que los algoritmos HMAC (HS*) usan 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 | String |
Valores válidos | HS256, HS384, HS512, RS256, RS384, RS512 |
Elemento <AppEndUser>
<AppEndUser>request.queryparam.app_enduser</AppEndUser>
En los casos en los que se debe enviar el ID de usuario final de la aplicación al servidor de autorización, este elemento te permite especificar dónde Apigee debe buscar el ID de usuario final. Por ejemplo, podría enviarse como parámetro de consulta o en un encabezado HTTP.
Por ejemplo, request.queryparam.app_enduser
indica que AppEndUser debe estar presente como un parámetro de consulta, por ejemplo, ?app_enduser=ntesla@theramin.com
. Para solicitar el AppEndUser en un encabezado HTTP, por ejemplo, configura este valor como request.header.app_enduser
.
Proporcionar esta configuración te permite incluir un ID de usuario final de la app en el token de acceso. Esta función es útil si deseas recuperar o revocar tokens de acceso de OAuth 2.0 por ID de usuario final. Para obtener más información, consulta Habilita la recuperación y revocación de tokens de acceso de OAuth 2.0 por ID de usuario final, ID de LA app o ambos.
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: |
Cualquier variable de flujo accesible para la política en el entorno de ejecución. |
Se usa con tipos de otorgamiento: |
|
<Atributos/Atributo>
<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>
Usa este elemento para agregar atributos personalizados a un token de acceso o código de autorización. Por ejemplo, es posible que desees incorporar un ID de usuario o identificador de sesión en un token de acceso que se puede extraer y verificar en el entorno de ejecución.
Este elemento te permite especificar un valor en una variable de flujo o desde una string literal. Si especificas una variable y una string, se usa el valor especificado en la variable de flujo. Si la variable no se puede resolver, la string es la predeterminada.
Si deseas obtener más información para usar este elemento, consulta Personaliza tokens y códigos de autorización.
Muestra u oculta atributos personalizados en la respuesta
Recuerda que si configuras el elemento GenerateResponse de esta política como true, la representación JSON completa del token se mostrará en la respuesta, incluidos los atributos personalizados que establezcas. En algunos casos, te recomendamos ocultar algunos o todos tus atributos personalizados en la respuesta para que no sean visibles para las apps cliente.
De forma predeterminada, los atributos personalizados aparecen en la respuesta. Si deseas ocultarlos, puedes establecer el parámetro display en false. 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 es persistente. Supongamos que generas un token de acceso con atributos personalizados que deseas ocultar en la respuesta generada. Establecer display=false
logra 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 aparecerán en la respuesta del token de actualización. Esto se debe a que Apigee no recuerda que el atributo display
se estableció originalmente en false
en la política de token de acceso, el atributo personalizado es solo una parte de los metadatos del token de acceso.
Verás el mismo comportamiento si agregas atributos personalizados a un código de autorización: cuando se genera un token de acceso con ese código, esos atributos personalizados se mostrarán en la respuesta del token de acceso. Una vez más, es posible que este no sea el comportamiento que pretendes.
Para ocultar los atributos personalizados en estos casos, tienes las siguientes opciones:
- Restablece de forma explícita los atributos personalizados de la política de token de actualización y configura su pantalla como false. En este caso, es posible que debas recuperar los valores personalizados originales del token de acceso original con la política GetOAuthV2Info.
- Usa una política de procesamiento posterior de JavaScript para extraer de forma manual cualquier atributo personalizado que no desees ver en la respuesta.
Consulta también Personaliza tokens y códigos de autorización.
Predeterminado: |
|
Presencia: |
Opcional |
Valores válidos: |
|
Se usa con tipos de otorgamiento: |
|
Elemento <CacheExpiryInSeconds>
<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Este elemento aplica el TTL en la caché, lo que permite la personalización del período para el vencimiento del token de acceso almacenado en caché. El rango admitido es de entre 1 y 180 segundos. Puedes proporcionar una variable de flujo y una variable predeterminada. Si se proporciona, el valor de la variable de flujo tiene prioridad sobre el valor predeterminado especificado.
Este elemento solo se puede usar con la operación VerifyAccessToken
.
Predeterminado | N/A
Si omites este elemento, el período de vencimiento predeterminado para el token de acceso almacenado en caché es de 180 segundos. |
---|---|
Presencia | Opcional |
Tipo | Entero |
Valores válidos | Cualquier número entero positivo que no sea cero. Especifica el tiempo de vencimiento en segundos. |
Atributos
En la siguiente tabla, se describen los atributos del elemento <CacheExpiryInSeconds>
Atributo | Descripción | Predeterminado | Presencia |
---|---|---|---|
ref |
Una referencia a la variable de flujo que contiene el valor 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 app cliente debe enviar el ID de cliente al servidor de autorización. Este elemento te permite especificar dónde Apigee debe buscar el ID de cliente. La única ubicación válida que puedes establecer es la ubicación predeterminada, la variable de flujo request.formparam.client_id
. No se puede configurar ClientId
en cualquier otra variable.
Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.client_id (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | La variable de flujo: request.formparam.client_id |
Se usa con tipos de otorgamiento: |
También se puede usar con la operación GenerateAuthorizationCode. |
Elemento <Code>
<Code>request.queryparam.code</Code>
En el flujo de tipo de autorización de autorización, el cliente debe enviar un código de autorización al servidor de autorización (Apigee). Este elemento te permite especificar dónde Apigee debe buscar el código de autorización. Por ejemplo, podría enviarse como un parámetro de consulta, un encabezado HTTP o un parámetro de forma (predeterminado).
La variable request.queryparam.auth_code
indica que el código de autorización debe estar presente como un parámetro de consulta, por ejemplo, ?auth_code=AfGlvs9
. Para solicitar el código de autorización en un encabezado HTTP, por ejemplo, establece este valor en request.header.auth_code
. Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.code (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
opcional |
Tipo: | String |
Valores válidos: | Cualquier variable de flujo accesible para la política en el entorno de ejecución |
Se usa con tipos de otorgamiento: | authorization_code |
elemento <ExpiresIn>
<ExpiresIn>10000</ExpiresIn>
Aplica la hora de vencimiento de los tokens de acceso y códigos de autorización en milisegundos. (Para los tokens de actualización, usa <RefreshTokenExpiresIn>
). El valor de la hora de vencimiento es un valor generado por el sistema y el valor <ExpiresIn>
. Si <ExpiresIn>
se configura como -1, el token o el código vence según el vencimiento máximo del token de acceso OAuth. Si no se especifica <ExpiresIn>
, el sistema aplica un valor predeterminado configurado a nivel del sistema.
La hora de vencimiento también se puede configurar en el entorno de ejecución con un hard-coded, un valor predeterminado o mediante la referencia a una variable de flujo. Por ejemplo, puedes almacenar un valor de vencimiento de token en un mapa de par 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 caché durante un mínimo de 180 segundos después de acceder a las entidades.
- Tokens de acceso de OAuth. Esto significa que el elemento
ExpiresIn
de la política OAuth v2 no podrá hacer expirar un token de acceso en menos de 180 segundos. - Entidades del servicio de administración de claves (KMS) (apps, desarrolladores, productos de API).
- Atributos personalizados de entidades de KMS y tokens de OAuth.
En la siguiente estrofa, se especifica una variable de flujo y, también, 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 admite una forma de forzar el vencimiento de un token después de su creación. Si necesitas forzar el vencimiento del token (por ejemplo, basado en una condición), se describe una solución posible en esta publicación de la comunidad de Apigee.
De forma predeterminada, los tokens de acceso vencidos se borran definitiva y automáticamente del sistema Apigee 3 días después del vencimiento. Consulta también Borrar definitivamente 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: |
|
Se usa con tipos de otorgamiento: |
También se usa con la operación GenerateAuthorizationCode. |
Elemento <ExternalAccessToken>
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
Le indica a Apigee dónde encontrar un token de acceso externo (un token de acceso que no genera Apigee).
La variable request.queryparam.external_access_token
indica que el token de acceso externo debe estar presente como un parámetro de consulta, por ejemplo, ?external_access_token=12345678
. Para solicitar el token de acceso externo en un encabezado HTTP, por ejemplo, establece este valor en request.header.external_access_token
. Consulta también el Usa tokens OAuth de terceros.
Elemento <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
Si este elemento es falso o no está presente, Apigee valida el client_id y client_secret, por lo general, en el almacén de autorización de Apigee. Usa este elemento cuando desees trabajar con tokens OAuth de terceros. Para obtener detalles sobre el uso de este elemento, consulta Usa tokens de OAuth de terceros.
Predeterminado: |
falso |
Presencia: |
Opcional |
Tipo: | Booleano |
Valores válidos: | True o False |
Se usa con tipos de otorgamiento: |
|
Elemento <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Le indica a Apigee dónde encontrar un código de autenticación externo (un código de autenticación que no genera Apigee).
La variable request.queryparam.external_auth_code
indica que el código de autenticación externo debe estar presente como un parámetro de consulta, por ejemplo, ?external_auth_code=12345678
. Para solicitar el código de autenticación externo en un encabezado HTTP, por ejemplo, establece este valor en request.header.external_auth_code
. Consulta también el Usa tokens OAuth de terceros.
Elemento <ExternalRefreshToken>
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
Le 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 un parámetro de consulta, por ejemplo, ?external_refresh_token=12345678
. Para solicitar el token de actualización externo en un encabezado HTTP, por ejemplo, establece este valor en request.header.external_refresh_token
. Consulta también el Usa tokens OAuth de terceros.
Elemento <GenerateResponse>
<GenerateResponse enabled='true'/>
Si se establece en true
o si se omite el atributo enabled
, la política genera y muestra una respuesta. Por ejemplo, para 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 establece en false
o si se omite el elemento <GenerateResponse>
, no se envía ninguna respuesta. En su lugar, un conjunto de variables de flujo se propaga con valores relacionados con la función de la política. Por ejemplo, una variable de flujo llamada oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
se propaga con el nuevo código de autenticación. Ten en cuenta que expires_in se expresa en segundos en la respuesta.
Predeterminado: |
true |
Presencia: |
Opcional |
Tipo: | string |
Valores válidos: | True o False |
Se usa con tipos de otorgamiento: |
|
Elemento <GenerateErrorResponse>
<GenerateErrorResponse enabled='true'/>
Si se configura como true
, la política genera y muestra una respuesta si el atributo ContinueOnError se establece como verdadero. Si false
(el valor predeterminado), no se envía ninguna respuesta. En su lugar, un conjunto de variables de flujo se propaga con valores relacionados con la función de la política.
Predeterminado: |
falso |
Presencia: |
Opcional |
Tipo: | string |
Valores válidos: | True o False |
Se usa con tipos de otorgamiento: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Indica a la política dónde buscar el parámetro de tipo de concesión que se pasa en una solicitud. Según la especificación OAuth 2.0, el tipo de concesión debe proporcionar solicitudes para 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 forma (predeterminado).
Por ejemplo, request.queryparam.grant_type
indica que la contraseña debe estar presente como un parámetro de búsqueda, por ejemplo, ?grant_type=password
.
Para requerir el tipo de concesión en un encabezado HTTP, por ejemplo, establece este valor en request.header.grant_type
. Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.grant_type (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | string |
Valores válidos: | Una variable, como se explicó antes. |
Se usa con tipos de otorgamiento: |
|
Elemento <Operation>
<Operation>GenerateAuthorizationCode</Operation>
La operación de OAuth 2.0 que ejecuta la política.
Predeterminado: |
Si no se especifica |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: |
Operaciones adicionales del token de acceso JWT Si prefieres usar tokens de acceso JWT en lugar de tokens de string opacos, las siguientes operaciones también están disponibles para generar y validar tokens JWT. Para obtener más detalles, consulta Usa operaciones de token de OAuth de JWT:
|
Elemento <PassWord>
<PassWord>request.queryparam.password</PassWord>
Este elemento se usa solo con el tipo de otorgamiento de contraseña. Con el tipo de otorgamiento de contraseña, las credenciales de usuario (contraseña y nombre de usuario) deben estar disponibles para la política de OAuthV2. Los elementos <PassWord>
y <UserName>
se usan para especificar las 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 llamados username
y password
. Si no se encuentran los valores, la política muestra un error. Puedes usar los elementos <PassWord>
y <UserName>
para hacer referencia a cualquier variable de flujo que contenga las credenciales.
Por ejemplo, puedes pasar la contraseña en una solicitud de token con un parámetro de consulta y configurar el elemento de esta manera: <PassWord>request.queryparam.password</PassWord>
.
. Para solicitar la contraseña en un encabezado HTTP, configura este valor en request.header.password
.
La política OAuthV2 no hace nada más con estos valores de credencial. Apigee solo verifica que estén presentes. Depende del desarrollador de la API recuperar la solicitud de valores y enviarla a un proveedor de identidad antes de que se ejecute la política de generación de tokens.
Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.password (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | Cualquier variable de flujo accesible para la política en el entorno de ejecución. |
Se usa con tipos de otorgamiento: | 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 con un algoritmo de RSA.
Usa el atributo ref
para pasar 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 Usa operaciones de token de OAuth de JWT.
Predeterminada | N/A |
Presencia | Obligatorio cuando el valor del elemento Algorithm coincide con HS256, HS384 o HS512. |
Tipo | String |
Valores válidos | Una variable de flujo que contiene una string que representa un valor de clave privada RSA con codificación 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 en un token de acceso con formato JWT firmado con un algoritmo de RSA. Usa el atributo ref
para pasar la clave o el certificado en una variable de flujo. Úsalo solo cuando el valor del elemento Algorithm
sea RS256, RS384 o RS512.
Predeterminada | N/A |
Presencia | Para verificar un JWT firmado con un algoritmo de RSA, debes usar los elementos Certificado, JWKS o Valor. |
Tipo | String |
Valores válidos | Una string o variable de flujo. |
Elemento <RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
Especifica dónde Apigee debe buscar el parámetro redirect_uri
en la solicitud.
Acerca de los URI de redireccionamiento
Los URI de redireccionamiento se usan con el código de autorización y los tipos de concesión implícitos. El URI de redireccionamiento le 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 autenticación) o un token de acceso (para el tipo de concesión implícito). Es importante comprender cuándo se requiere este parámetro, cuándo es opcional y cómo se usa:
-
Si una URL de devolución de llamada está registrada con la app para desarrolladores asociada con las claves de cliente de la solicitud, y
redirect_uri
está presente en la solicitud, entonces ambas deberán coincidir exactamente (obligatorio). Si no coinciden, se muestra un error. Si deseas obtener información para registrar apps para desarrolladores en Apigee y especificar una URL de devolución de llamada, consulta Registra apps y administra claves de API. - Si se registra una URL de devolución de llamada y falta el
redirect_uri
en la solicitud, Apigee redirecciona a la URL de devolución de llamada registrada (opcional). - Si no hay una URL de devolución de llamada registrada, entonces la
redirect_uri
es obligatoria (obligatorio). Tenga en cuenta que, en este caso, Apigee aceptará CUALQUIER URL. Este caso puede presentar un problema de seguridad y, por lo tanto, solo debe usarse con apps cliente confiables. Si las apps cliente no son de confianza, la práctica recomendada es solicitar siempre el registro de una URL de devolución de llamada.
Puedes enviar este parámetro a un parámetro de consulta o en un encabezado. La variable request.queryparam.redirect_uri
indica que RedirectUri debe estar presente como un parámetro de consulta, por ejemplo, ?redirect_uri=login.myapp.com
. Para solicitar el permiso en un encabezado HTTP, por ejemplo, configura este valor como request.header.redirect_uri
. Consulta
también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.redirect_uri (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | Cualquier variable de flujo accesible para la política en el entorno de ejecución. |
Se usa con tipos de otorgamiento: |
También se usa con la operación GenerateAuthorizationCode. |
Elemento <RefreshToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
Cuando solicitas un token de acceso con un token de actualización, debes suministrarlo en la solicitud. Este elemento te permite especificar dónde Apigee debe buscar el token de actualización. Por ejemplo, podría enviarse como un parámetro de consulta, un encabezado HTTP o un parámetro de forma (predeterminado).
La variable request.queryparam.refreshtoken
indica que el token de actualización debe estar presente como un parámetro de búsqueda, por ejemplo, ?refresh_token=login.myapp.com
. Para solicitar el RefreshToken en un encabezado HTTP, por ejemplo, configura este valor como request.header.refresh_token
. Consulta
también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.access_token (una x-www-form-urlencoded y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | Cualquier variable de flujo accesible para la política en el entorno de ejecución. |
Se usa con tipos de otorgamiento: |
|
Elemento <RefreshTokenExpiresIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Aplica el tiempo de vencimiento de los tokens de actualización en milisegundos. El valor de tiempo de vencimiento es un valor generado por el sistema y el valor <RefreshTokenExpiresIn>
. Si <RefreshTokenExpiresIn>
se configura como -1, el token de actualización vence según el vencimiento máximo del token de actualización de OAuth. Si <RefreshTokenExpiresIn>
no se especifica, el sistema aplica el valor predeterminado.
La hora de vencimiento también se puede configurar en el entorno de ejecución con un hard-coded, un valor predeterminado o mediante la referencia a una variable de flujo. Por ejemplo, puedes almacenar un valor de vencimiento de token en un mapa de par clave-valor, recuperarlo, asignarlo a una variable y hacer referencia a él en la política. Por ejemplo, kvm.oauth.expires_in
.
En la siguiente estrofa, se especifica una variable de flujo y, también, un valor predeterminado. Ten en cuenta que el valor de la variable de flujo tiene prioridad sobre el valor predeterminado especificado.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 86400000 <!--value in milliseconds--> </RefreshTokenExpiresIn>
Predeterminado: |
2592000000 ms (30 días) (vigente a partir del 31 de mayo de 2023) |
Presencia: |
Opcional |
Tipo: | Entero |
Valores válidos: |
|
Se usa con tipos de otorgamiento: |
|
Elemento <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Este elemento informa a Apigee el tipo de otorgamiento que solicita la app cliente. Solo se usa con el código de autorización y los flujos de tipos de otorgamiento implícito.
De forma predeterminada, Apigee busca el valor del tipo de respuesta en un parámetro de consulta response_type
. Si deseas anular este comportamiento predeterminado, usa el elemento <ResponseType> para configurar una variable de flujo que contenga el valor del tipo de respuesta. Por ejemplo, si configuras este elemento como request.header.response_type
, Apigee busca que el tipo de respuesta se pase en el encabezado de la solicitud. Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.response_type (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional. Usa este elemento si deseas anular el comportamiento predeterminado. |
Tipo: | String |
Valores válidos: | code (para el tipo de otorgamiento de código de autorización) o token (para el tipo de otorgamiento implícito) |
Se usa con tipos de otorgamiento: |
|
Elemento <ReuseRefreshToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
Cuando se configura como true
, el token de actualización existente se vuelve a usar hasta que vence. Si es false
, Apigee emite un token de actualización nuevo cuando se presenta un token de actualización válido.
Predeterminado: |
|
Presencia: |
opcional |
Tipo: | boolean |
Valores válidos: |
|
Se usa con el tipo de otorgamiento: |
|
Elemento <RFCCompliantRequestResponse>
<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>
Cuando se establece en true
, la política cumple con los estándares RFC6749 y habilita los siguientes comportamientos compatibles:
- Las respuestas de error y sin error incluirán el campo del encabezado de respuesta HTTP
Cache-Control
para cumplir con RFC2616 (Protocolo de transferencia de hipertexto, HTTP/1.1), con un valor deno-store
en cualquier respuesta que contenga tokens, credenciales o cualquier otra información sensible, así como el campo de encabezado de respuestaPragma
con un valor deno-cache
. - La propiedad
expires_in
estará en formato alfanumérico. Por motivos de coherencia, el valorrefresh_token_expires_in
también será alfanumérico. - Las respuestas de OAuthV2 para la generación de tokens incluirán el campo de encabezado
Bearer
compatible con RFC en lugar deBearerToken
. - Los mensajes de error en las cargas útiles de la respuesta tendrán el siguiente formato:
{"error" : "xxx", "error_description" :"yyy"}
para los errores de token de actualización.
Predeterminado: |
|
Presencia: |
Opcional |
Tipo: | Booleano |
Valores válidos: | true o false |
Se usa con tipos de otorgamiento: | Todos |
<SecretKey>/<Value>
<SecretKey> <Value ref="your-variable-name"/> </SecretKey>
Proporciona la clave secreta usada para verificar o firmar tokens de acceso con formato JWT con un algoritmo HMAC. Úsalo solo cuando el algoritmo coincida con HS256, HS384 o HS512. Usa el atributo ref
para pasar la clave en una variable de flujo. Para obtener más información, consulta Usa operaciones de token de OAuth de JWT.
Apigee aplica una seguridad de clave mínima para los algoritmos HS256/HS384/HS512. La longitud mínima de la clave de HS256 es de 32 bytes, para HS384 es de 48 bytes, y para HS512 es de 64 bytes. El uso de una clave de baja intensidad provoca un error en el entorno de ejecución.
Predeterminada | N/A |
Presencia | Obligatorio para los algoritmos HMAC. |
Tipo | String |
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 qué permisos otorgar el token o el código. Por lo general, estos valores se pasan a la política en una solicitud desde una aplicación cliente. Puedes configurar el elemento para que tome una variable de flujo, lo que te brinda la opción de elegir cómo se pasan los permisos en una solicitud. En el siguiente ejemplo, request.queryparam.scope
indica que el permiso debe estar presente como un parámetro de consulta, por ejemplo, ?scope=READ
. Para solicitar el permiso en un encabezado HTTP, por ejemplo, configura este valor como request.header.scope
.
Si este elemento aparece en una política "VerifyAccessToken", se usa para especificar los permisos que debe cumplir la política. En este tipo de política, el valor debe ser un nombre de permiso "codificado". No puedes usar variables. Por ejemplo:
<Scope>A B</Scope>
Consulta también Trabaja con alcances de OAuth2 y Obtén tokens de OAuth 2.0.
Predeterminado: |
Sin permiso |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: |
Si se usa con políticas Generate*, una variable de flujo. Si se usa con VerifyAccessToken, una lista de nombres de permisos separada por espacios (strings). |
Se usa con tipos de otorgamiento: |
|
Elemento <State>
<State>request.queryparam.state</State>
En los casos en los que la app cliente debe enviar la información de estado al servidor de autorización, este elemento te permite especificar dónde Apigee debe buscar los valores de estado. Por ejemplo, podría enviarse como parámetro de consulta o en un encabezado HTTP. Por lo general, el valor del estado se usa como una medida de seguridad para evitar ataques del CSRF.
Por ejemplo, request.queryparam.state
indica que el estado debe estar presente como un parámetro de consulta, por ejemplo, ?state=HjoiuKJH32
. Para solicitar el permiso en un encabezado HTTP, por ejemplo, configura este valor como request.header.state
. Consulta también los tokens de OAuth 2.0.
Predeterminado: |
Sin estado |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | Cualquier variable de flujo accesible para la política en el entorno de ejecución |
Se usa con tipos de otorgamiento: |
|
Elemento <StoreToken>
<StoreToken>true</StoreToken>
Establece este elemento en true
cuando el elemento <ExternalAuthorization>
es true
. El elemento <StoreToken>
le 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: | True o False |
Se usa con tipos de otorgamiento: |
|
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 compatibles con un extremo de token de OAuth en Apigee. Un extremo puede admitir varios tipos de otorgamiento (es decir, un solo extremo se puede configurar a fin de distribuir tokens de acceso para varios tipos de otorgamiento). Para obtener más información sobre los extremos, consulta Comprende los extremos de OAuth. El tipo de concesión se pasa en solicitudes de token en un parámetro grant_type
.
Si no se especifican tipos de otorgamiento de acceso compatibles, los únicos tipos de otorgamiento permitidos son authorization_code
y implicit
. Consulta también el elemento <GrantType> (un elemento de nivel superior que se usa para especificar dónde debe Apigee buscar el parámetro grant_type
que se pasa en una solicitud de cliente). Apigee se asegurará de que el valor del parámetro grant_type
coincida con uno de los tipos de otorgamiento compatibles).
Predeterminado: |
authorization _code e implicit |
Presencia: |
Obligatorio |
Tipo: | String |
Valores válidos: |
|
Elemento <Tokens>/<Token>
Se usa con las operaciones InvalidToken e InvalidateToken. Consulta también Aprueba y revoca tokens de acceso. El elemento <Token> identifica la variable de flujo que define la fuente del token que se revocará. Si se espera que los desarrolladores envíen tokens de acceso como parámetros de consulta llamados access_token
, usa request.queryparam.access_token
.
Elemento <UserName>
<UserName>request.queryparam.user_name</UserName>
Este elemento se usa solo con el tipo de otorgamiento de contraseña. Con el tipo de otorgamiento de contraseña, las credenciales de usuario (contraseña y nombre de usuario) deben estar disponibles para la política de OAuthV2. Los elementos <PassWord>
y <UserName>
se usan para especificar las 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 llamados username
y password
. Si no se encuentran los valores, la política muestra un error. Puedes usar los elementos <PassWord>
y <UserName>
para hacer referencia a cualquier variable de flujo que contenga las credenciales.
Por ejemplo, puedes pasar el nombre de usuario en un parámetro de consulta y configurar el elemento <UserName>
de la siguiente manera: <UserName>request.queryparam.username</UserName>
.
Para solicitar el nombre de usuario en un encabezado HTTP, configura este valor en request.header.username
.
La política OAuthV2 no hace nada más con estos valores de credencial. Apigee solo verifica que estén presentes. Depende del desarrollador de la API recuperar la solicitud de valores y enviarla a un proveedor de identidad antes de que se ejecute la política de generación de tokens.
Consulta también Obtén tokens de OAuth 2.0.
Predeterminado: |
request.formparam.username (una x-www-form-url codificada y especificada en el cuerpo de la solicitud) |
Presencia: |
Opcional |
Tipo: | String |
Valores válidos: | Cualquier configuración variable. |
Se usa con tipos de otorgamiento: | contraseña |
Verifica tokens de acceso
Una vez que se configura un extremo de token para un proxy de API, una política de OAuthV2 correspondiente que especifica la operación VerifyAccessToken
se adjunta al flujo que expone el recurso protegido.
Por ejemplo, para garantizar que las solicitudes a una API estén autorizadas, la siguiente política aplica la verificación de token de acceso:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
La política se adjunta al recurso de la API que se protegerá. Para garantizar que se verifiquen todas las solicitudes a una API, adjunta la política a la solicitud de PreFlow de solicitud de extremo del proxy de la siguiente manera:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
Los siguientes elementos opcionales se pueden usar para anular la configuración predeterminada de la operación VerifyAccessToken.
Name | Descripción |
---|---|
Permiso |
Una lista de alcances delimitados por espacios. La verificación se realizará de forma correcta si al menos uno de los alcances enumerados está presente en el token de acceso. Por ejemplo, la siguiente política verificará el token de acceso para asegurarse de que contenga al menos uno de los alcances enumerados. Si están presentes READ o WRITE, la verificación se realizará de forma correcta. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | Es la variable donde se espera que se coloque el token de acceso. Por ejemplo request.queryparam.accesstoken . De forma predeterminada, la app presenta el token de acceso en el encabezado HTTP de Autorización, de acuerdo con la Especificación de OAuth 2.0. Usa esta configuración si se espera que el token de acceso se presente en una ubicación no estándar, como un parámetro de búsqueda o en un encabezado HTTP con un nombre que no sea la autorización. |
Consulta también Verifica tokens de acceso y Obtén tokens de OAuth 2.0.
Especifica ubicaciones de variables de solicitud
Para cada tipo de concesión, la política hace suposiciones sobre la ubicación o la información requerida 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 para cada parámetro. Por ejemplo, cuando se controla un código de autorización, puedes especificar la ubicación del código de autorización, el ID de cliente, el URI de redireccionamiento y el alcance. Estos se pueden especificar como encabezados HTTP, parámetros de búsqueda o parámetros de formulario.
El siguiente ejemplo demuestra cómo puedes especificar la ubicación de los parámetros de código de autorización requeridos 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> ...
O bien, si es necesario para admitir tu base de apps cliente, puedes mezclar y combinar encabezados y parámetros de consulta:
... <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 propagan cuando se ejecutan las políticas de OAuth correspondientes. Por lo tanto, están disponibles para otras políticas o aplicaciones que se ejecutan en el flujo de proxy de API.
Operación VerifyAccessToken
Cuando la operación VerifyAccessToken se ejecuta, se propaga una gran cantidad de variables de flujo en el contexto de ejecución del proxy. Estas variables te otorgan propiedades relacionadas con el token de acceso, la app para desarrolladores y el desarrollador. Puedes usar una política de 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 fines de depuración.
Variables específicas de token
Variables | Descripción |
---|---|
organization_name |
El nombre de la organización en la que se ejecuta el proxy. |
developer.id |
El ID del desarrollador o de AppGroup asociado con la app cliente registrada. |
developer.app.name |
El nombre del desarrollador o la app de AppGroup asociada con la app cliente registrada. |
client_id |
El ID de cliente de la app cliente registrada. |
grant_type |
El tipo de otorgamiento asociado a la solicitud. No es compatible con 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 expresado en tiempo Unix en milisegundos. |
expires_in |
La hora de vencimiento del token de acceso. expresado en segundos. Aunque el elemento ExpiresIn establece el vencimiento en milisegundos, en la respuesta del token y las variables de flujo, el valor se expresa en segundos. |
status |
El estado del token de acceso (p. ej., aprobado o revocado). |
scope |
El permiso (si existe) asociado con el token de acceso. |
apiproduct.<custom_attribute_name> |
Un atributo personalizado con nombre del producto de API asociado con la app cliente registrada. |
apiproduct.name |
El nombre del producto de API asociado con la app cliente registrada. |
revoke_reason |
(Solo Apigee híbrido) Indica por qué se revoca el token de acceso. No es compatible con la operación El valor puede ser |
Variables específicas de la app
Estas variables están relacionadas con la app para desarrolladores asociada con el token.
Variables | Descripción |
---|---|
app.name |
|
app.id |
|
app.accessType |
|
app.callbackUrl |
|
app.status |
aprobado o revocado |
app.scopes |
|
app.appFamily |
|
app.apiproducts |
|
app.appParentStatus |
|
app.appType |
Por ejemplo: Desarrolladores |
app.appParentId |
|
app.created_by |
|
app.created_at |
|
app.last_modified_at |
|
app.last_modified_by |
|
app.{custom_attributes} |
Un atributo personalizado con nombre de la app cliente registrada. |
Variables específicas de AppGroup
Las siguientes variables de flujo que contienen información sobre el AppGroup para el token y se propagan mediante la política. Estos atributos de AppGroup solo se propagan si verifyapikey.{policy_name}.app.appType
es “AppGroup”.
Variables | Descripción |
---|---|
appgroup.displayName |
El nombre visible de AppGroup. |
appgroup.name |
Nombre del AppGroup. |
appgroup.id |
El ID de AppGroup. |
appOwnerStatus |
El estado del propietario de la aplicación: "active", "inactive" o "login_lock". |
created_at |
La marca de fecha y hora cuando se creó el AppGroup. |
created_by |
La dirección de correo electrónico del desarrollador que creó el AppGroup. |
last_modified_at |
La marca de fecha y hora de la última modificación del AppGroup. |
last_modified_by |
La dirección de correo electrónico 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 para desarrolladores
Si app.appType
es “Desarrollador”, se propagarán los atributos del desarrollador.
Variables | Descripción |
---|---|
Variables específicas para desarrolladores | |
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} |
Un atributo personalizado con nombre del desarrollador. |
Operación GenerateAuthorizationCode
Estas variables se configuran cuando la operación GenerateAuthorizationCode se ejecuta de forma correcta:
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 |
El URI de redireccionamiento asociado a la app cliente registrada. |
scope |
El permiso opcional de OAuth que se pasó en la solicitud del cliente. |
client_id |
El ID de cliente que se pasó en la solicitud del cliente. |
Operaciones de GenerateAccessToken y RefreshAccessToken
Estas variables se configuran cuando las operaciones GenerateAccessToken y RefreshAccessToken se ejecutan de forma correcta. Ten en cuenta que las variables de token de actualización no se aplican para el flujo de tipos de otorgamiento de credenciales de cliente.
Prefijo: oauthv2accesstoken.{policy_name}.{variable_name}
Ejemplo: oauthv2accesstoken.GenerateTokenPolicy.access_token
Nombre de la variable | Descripción |
---|---|
access_token |
El token de acceso que se generó. |
client_id |
El ID de cliente de la app de desarrollador asociada con este token. |
expires_in |
El valor de vencimiento del token. Consulta el elemento <ExpiresIn> para obtener más información. Ten en cuenta que en la respuesta, expires_in se expresa en segundos. |
scope |
Lista de permisos disponibles configurados para el token. Consulta Trabaja con permisos de OAuth2. |
status |
approved o revoked |
token_type |
Se configura como BearerToken . |
developer.email |
La dirección de correo electrónico del desarrollador registrado que es propietario de la app de desarrollador asociada con el token. |
organization_name |
La organización donde se ejecuta el proxy. |
api_product_list |
Una lista de los productos asociados con la aplicación de desarrollador correspondiente del token. |
refresh_count |
|
refresh_token |
El token de actualización que se generó. Ten en cuenta que los tokens de actualización no se generan para el tipo de concesión de credenciales de cliente. |
refresh_token_expires_in |
La duración del token de actualización, en segundos. |
refresh_token_issued_at |
Este valor de tiempo es la representación de string de la cantidad de marcas de tiempo de 32 bits correspondientes. Por ejemplo, "Miércoles, 21 de agosto de 2013, 19:16:47 UTC" corresponde al valor de la marca de tiempo de 1377112607413. |
refresh_token_status |
approved o revoked |
GenerateAccessTokenImplicitGrant
Estas variables se configuran cuando la operación GenerateAccessTokenImplicit se ejecuta de manera correcta para el flujo de tipo de otorgamiento implícito.
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 |
El valor de vencimiento del token, en segundos. Consulta el elemento <ExpiresIn> para obtener más información. |
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ó. |
|
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. |
|
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 |
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\ |
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 |
|
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 |
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:
- Si el contexto del flujo es la generación o actualización de tokens, consulta Códigos de error para los flujos de generación y actualización de tokens de JWT a continuación.
- Para el flujo de verificación de tokens, consulta Códigos de error para flujos de verificación de tokens a continuación.
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. |
|
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. |
|
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 |
|
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. |
|
oauth.v2.JWTDecodingFailed |
401 |
La política no pudo decodificar el JWT. Es posible que el JWT esté dañado. |
|
oauth.v2.MissingMandatoryClaimsInJWT |
401 |
Ocurre cuando las reclamaciones obligatorias no están presentes en el token de acceso de JWT. |
|
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. |
|
oauth.v2.InvalidTypeInJWTHeader |
401 |
Ocurre cuando el tipo de JWT no es at+Jwt . |
|
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 |
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 |
InvalidOperation |
Debes especificar una operación válida en esta política con el elemento |
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 | Estos son los parámetros: | 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 verdadero.
Si <GenerateResponse>
es verdadero, 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 verdadero, 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>
A los tokens del almacenamiento se les genera un hash
Si usas Apigee Hybrid o Apigee, los tokens de acceso y de actualización de OAuthV2 tienen un hash de forma predeterminada cuando se almacenan en la base de datos de Cassandra del entorno de ejecución. La codificación hash evita que se usen los tokens si la base de datos estuviera comprometida.
Trabaja con la configuración de OAuth predeterminada
Cada organización (incluso una organización de prueba gratuita) en Apigee se aprovisiona con un extremo del token de OAuth. El extremo está preconfigurado con políticas en el proxy de API llamado oauth. Puedes comenzar a usar el extremo del token en cuanto crees una cuenta en Apigee. Para obtener más detalles, consulta Información sobre los extremos de OAuth.
Borra definitivamente tokens de acceso
De forma predeterminada, los tokens de OAuth2 se borran de forma definitiva del sistema de Apigee 3 días (259,200 segundos) después del vencimiento del token de acceso y el de actualización (si existen).
Comportamiento que no cumple con RFC
De forma predeterminada, la política OAuthV2, con la operación GenerateAccessToken, muestra una respuesta de token que contiene ciertas propiedades que no cumplen con RFC. En la siguiente tabla, se muestran las propiedades que no cumplen con las políticas que se muestran en la política OAuthV2 y las que cumplen con los requisitos correspondientes.
En OAuthV2 se muestra: | La propiedad que cumple con RFC es la siguiente: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
(El valor compatible es un número, no una string). |
Además, la respuesta de error de un token de actualización vencido cuando grant_type = refresh_token
es este:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
Sin embargo, la respuesta compatible con RFC es la siguiente:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}