Política de VerifyAPIKey

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

Consulta la documentación de Apigee Edge.

Descripción general

La política VerifyAPIKey te permite aplicar la verificación de las claves de API en el entorno de ejecución, de modo que solo las apps con claves de API aprobadas accedan a tus API. Esta política garantiza que las claves de API sean válidas, no se hayan revocado y estén aprobadas para consumir los recursos específicos asociados con los productos de la API.

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.

Para ver un instructivo en el que se muestra cómo crear un proxy de API que usa la política Verificar clave de API, consulta Protege una API mediante la solicitud de claves de API.

Muestras

Clave en el parámetro de consulta

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

En este ejemplo, la política espera encontrar la clave de API en una variable de flujo llamada request.queryparam.apikey. La variable request.queryparam.{name} es una variable de flujo de Apigee estándar que se propaga con el valor de un parámetro de búsqueda que se pasa en la solicitud del cliente.

En el siguiente comando de curl, se pasa la clave de API en un parámetro de búsqueda:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Clave en el encabezado

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

En este ejemplo, la política espera encontrar la clave de API en una variable de flujo llamada request.header.x-apikey. La variable request.header.{name} es una variable de flujo de Apigee estándar que se propaga con el valor de un encabezado que se pasa en la solicitud del cliente.

En el siguiente cURL, se muestra cómo pasar la clave de API en un encabezado:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

Clave en una variable

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

La política puede hacer referencia a cualquier variable que contenga la clave. En este ejemplo, la política extrae la clave de API de una variable llamada requestAPIKey.key.

La forma en que esa variable se propague depende de ti. Por ejemplo, podrías usar la política de extracción de variables para propagar requestAPIKey.key desde un parámetro de búsqueda llamado myKey, como se muestra a continuación:

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Variables de flujo de políticas de acceso

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Cuando ejecutas la política VerifyAPIKey para una clave de API válida, Apigee propaga automáticamente un conjunto de variables de flujo. Puedes usar estas variables para acceder a información, como el nombre de la app, el ID de la app y la información sobre el desarrollador o la empresa que registró la app. En el ejemplo anterior, puedes usar la política de asignación de mensajes para acceder al nombre, apellido y dirección de correo electrónico del desarrollador después de que se ejecuta la clave de API de verificación.

Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}

En este ejemplo, el nombre de la política VerifyAPIkey es “verify-api-key”. Por lo tanto, debes hacer referencia al nombre del desarrollador que realiza la solicitud mediante la variable verifyapikey.verify-api-key.developer.firstName.

Más información sobre Apigee

Acerca de la política Verificar clave de API

Cuando un desarrollador registra una app en Apigee, se genera de forma automática una clave de consumidor y un par de secretos. Puedes ver el par de clave y secreto del consumidor de la aplicación en la IU de Apigee o acceder a ellos desde la API de Apigee.

En el momento del registro de la app, el desarrollador selecciona uno o más productos de API para asociarlos con la app, en el que un producto de la API es un grupo de recursos. accesible a través de proxies de API. Luego, el desarrollador pasa la clave de API (clave del consumidor) como parte de cada solicitud a una API en un producto de la API asociado con la app. Consulta Descripción general de la publicación para obtener más información.

Las claves de API se pueden usar como tokens de autenticación o se pueden usar para obtener tokens de acceso de OAuth. En OAuth, las claves de API se denominan “ID de cliente”. Los nombres se pueden usar de forma indistinta. Consulta la página principal de OAuth para obtener más información.

Cuando se ejecuta la política VerifyAPIKey, Apigee propaga automáticamente un conjunto de variables de flujo. Consulta Variables de flujo a continuación para obtener más información.

Referencia de elementos

A continuación, se describen los elementos y los atributos que puedes configurar en esta política:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

Atributos <VerifyAPIKey>

En el siguiente ejemplo, se muestran los atributos de la etiqueta <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

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 `name` puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
`continueOnError`	Configúralo como `false` para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como `true` para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	falso	Opcional
`enabled`	Configúralo como `true` para aplicar la política. Configúralo como `false` para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	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

Predeterminada	N/A Si omites este elemento, se usa el valor del atributo `name` de la política.
Presencia	Opcional
Tipo	String

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional

Tipo String

Elemento <APIKey>

Este elemento especifica la variable de flujo que contiene la clave de API. Por lo general, el cliente envía la clave de API en un parámetro de búsqueda, un encabezado HTTP o un parámetro de formulario. Por ejemplo, si la clave se envía en un encabezado llamado x-apikey, la clave se encontrará en la variable: request.header.x-apikey.

Predeterminado	NA
Presencia	Obligatorio
Tipo	Cadena

Atributos

En la siguiente tabla, se describen los atributos del elemento <APIKey>

Atributo	Descripción	Predeterminado	Presencia
ref	Una referencia a la variable que contiene la clave de API Solo se permite una ubicación por política.	N/A	Obligatorio

Ejemplos

En estos ejemplos, la clave se pasa en los parámetros y en un encabezado llamado x-apikey.

Como un parámetro de búsqueda:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

Como un encabezado HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

Como un parámetro de formulario HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

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

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

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

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

Esquemas

Variables de flujo

Cuando se aplica una política VerifyAPIKey en una clave de API válida, Apigee propaga un conjunto de variables de flujo. Estas variables están disponibles para políticas o códigos ejecutados más adelante en el flujo y suelen usarse a fin de realizar un procesamiento personalizado según los atributos de la clave de API, como el nombre de la app, el producto de la API que se usa para autorizar la clave o los atributos personalizados de la clave de API.

La política propaga varios tipos diferentes de variables de flujo, que incluyen las siguientes:

General
App
Desarrollador
Analytics
Monetización

Cada tipo de variable de flujo tiene un prefijo diferente. Todas las variables son escalares, excepto aquellas indicadas específicamente como arreglos.

Variables generales de flujo

En la siguiente tabla, se enumeran las variables generales del flujo propagadas por la política VerifyAPIKey. Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}

Por ejemplo: verifyapikey.{policy_name}.client_id

Las variables disponibles incluyen las siguientes:

Variable	Descripción
`client_id`	La clave de consumidor (también conocida como clave de API o clave de app) que proporciona la app solicitante.
`client_secret`	El secreto del consumidor asociado con la clave de consumidor.
`redirection_uris`	Cualquier URI de redireccionamiento en la solicitud.
`developer.app.id`	El ID del desarrollador o la app de AppGroup que realiza la solicitud. Nota: No uses la variable `developer.app.id` para ninguno de los siguientes fines: Identificador para la política de cuotas Claves de mapa de clave-valor (KVM) Identificadores enviados a los destinos que se usarán en la lógica empresarial del backend Apigee genera este ID de manera interna y no se garantiza que permanezca igual con el tiempo. Por ejemplo, Apigee puede cambiar el formato o la longitud de esta variable.
`developer.app.name`	El nombre de la app del desarrollador o la app de AppGroup que realiza la solicitud.
`developer.id`	El ID del desarrollador o AppGroup registrado como el propietario de la app que realiza la solicitud. Nota: No uses la variable `developer.id` para ninguno de los siguientes fines: Identificador de cuota Claves KVM Identificadores enviados a los destinos que se usarán en la lógica empresarial del backend Apigee genera este ID de manera interna y no se garantiza que permanezca igual con el tiempo. Por ejemplo, Apigee puede cambiar el formato o la longitud de esta variable.
`developer.{custom_attrib_name}`	Cualquier atributo personalizado derivado del perfil de clave de la app.
`DisplayName`	El valor del atributo <DisplayName> de la política.
`failed`	Configúralo en “true” cuando la validación de la clave de API falla.
`{custom_app_attrib}`	Cualquier atributo personalizado derivado del perfil de la app. Especifica el nombre del atributo personalizado.
`apiproduct.name*`	El nombre del producto de la API que se usa para validar la solicitud.
`apiproduct.{custom_attrib_name}*`	Cualquier atributo personalizado derivado del perfil de producto de la API.
`apiproduct.developer.quota.limit*`	El límite de cuota establecido en el producto de la API, si corresponde.
`apiproduct.developer.quota.interval*`	El intervalo de cuota establecido en el producto de la API, si corresponde.
`apiproduct.developer.quota.timeunit*`	La unidad de tiempo de cuota establecida en el producto de la API, si existe.
* Las variables del producto de la API se propagan automáticamente si los productos de la API se configuran con entornos, proxies y recursos válidos (derivados de `proxy.pathsuffix`). Para obtener instrucciones sobre cómo configurar productos de la API, consulta Administra productos de la API.

Variables de flujo de la app

La siguiente variable de flujo contiene información sobre la app que propaga la política. Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.app.

Por ejemplo:

verifyapikey.{policy_name}.app.name

Las variables disponibles incluyen las siguientes:

Variable	Descripción
`name`	El nombre de la app.
`id`	El ID de la app
`accessType`	No utilizado por Apigee.
`callbackUrl`	La URL de devolución de llamada de la app. Por lo general, se usa solo para OAuth.
`DisplayName`	El nombre visible de la app.
`status`	Es el estado de la app, como “aprobado” o “revocado”.
`apiproducts`	Un arreglo que contiene la lista de productos de API asociados con la app.
`appFamily`	Cualquier familia de apps que contenga la app o "predeterminada".
`appParentStatus`	El estado del elemento principal de la app, como “activa” o “inactiva”
`appType`	El tipo de aplicación como “Desarrollador”
`appParentId`	El ID de la app superior.
`created_at`	La marca de fecha y hora cuando se creó la app
`created_by`	La dirección de correo electrónico del desarrollador que creó la app.
`last_modified_at`	La marca de fecha y hora de la última actualización de la app
`last_modified_by`	La dirección de correo electrónico del desarrollador que actualizó la app por última vez.
`{app_custom_attributes}`	Cualquier atributo personalizado de la app Especifica el nombre del atributo personalizado.

Variables de flujo de AppGroup

La política propaga las siguientes variables de flujo que contienen información sobre los AppGroups. Estos atributos de AppGroup solo se propagan si verifyapikey.{policy_name}.app.appType es “AppGroup”.

Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.appgroup.

Por ejemplo:

verifyapikey.{policy_name}.appgroup.name

Las variables disponibles incluyen las siguientes:

Variable	Descripción
`name`	El nombre del AppGroup.
`id`	El ID de AppGroup. Nota: Apigee genera este ID de manera interna y no se garantiza que permanezca igual con el tiempo. Nota: No uses la variable `appgroup.id` para ninguno de los siguientes fines: Identificador de cuota Claves KVM Identificadores enviados a los destinos que se usarán en la lógica empresarial del backend
`displayName`	El nombre visible de AppGroup.
`appOwnerStatus`	El estado del propietario de la aplicación: 'activa', 'inactiva' o 'bloqueo de acceso'.
`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 de flujo del desarrollador

La siguiente variable de flujo contiene información sobre el desarrollador que propaga la política. Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.developer

Por ejemplo:

verifyapikey.{policy_name}.developer.id

Las variables disponibles incluyen las siguientes:

Variable	Descripción
`id`	Muestra {org_name}@@@{developer_id}
`userName`	El nombre de usuario del desarrollador
`firstName`	El nombre del desarrollador
`lastName`	Apellido del desarrollador
`email`	Dirección de correo electrónico del desarrollador
`status`	Es el estado del desarrollador, activo, inactivo o login_lock
`apps`	Un arreglo de apps asociadas con el desarrollador
`created_at`	La marca de fecha y hora de cuando se creó el desarrollador
`created_by`	La dirección de correo electrónico del usuario que creó el desarrollador
`last_modified_at`	La marca de fecha y hora de la última modificación del desarrollador
`last_modified_by`	La dirección de correo electrónico del usuario que modificó el desarrollador
`{developer_custom_attributes}`	Cualquier atributo personalizado del desarrollador Especifica el nombre del atributo personalizado.

Variables de Analytics

Las siguientes variables se propagan automáticamente en Analytics cuando se aplica una política VerifyAPIKey de una clave de API válida. Estas variables solo se propagan mediante la política VerifyAPIKey y las políticas de OAuth.

Las variables y valores se pueden usar como dimensiones para crear informes de estadísticas a fin de obtener visibilidad de los patrones de consumo por parte de desarrolladores y apps.

apiproduct.name
developer.app.name
client_id
developer.id

Variables de flujo de monetización

Después de autenticar al usuario, la política de VerifyAPIKey verifica todos los planes de tarifas publicados para determinar cuál está activo (si hay alguno) en función de su hora de activación y vencimiento. Si se encuentra un plan de tarifas publicado activo, se propagan las siguientes variables de flujo:

Variable	Descripción
`mint.mintng_is_apiproduct_monetized`	`true` si se encuentra un plan de tarifas publicado activo.
`mint.mintng_rate_plan_id`	ID de plan de tarifa.
`mint.rateplan_end_time_ms`	Hora de vencimiento del plan de tarifas. Por ejemplo: `1619433556408`.
`mint.rateplan_start_time_ms`	Hora de activación del plan de tarifas. Por ejemplo: `1618433956209`.

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
`keymanagement.service.consumer_key_missing_api_product_association`	`400`	A la credencial de la aplicación le falta una asociación de producto de API. Asocia la aplicación de la clave a un producto de API. Ten en cuenta que esto se aplica a todos los tipos de aplicación, como las apps para desarrolladores y las apps de AppGroups.
`keymanagement.service.DeveloperStatusNotActive`	`401`	El desarrollador que creó la app de desarrollador que tiene la clave de API que usas tiene un estado inactivo. Cuando el estado del desarrollador de una app se establece como inactivo, se desactivan todas las apps para desarrolladores que creó ese desarrollador. Un usuario administrador con los permisos adecuados (como administrador de la organización) puede cambiar el estado de un desarrollador de las siguientes maneras: API de Apigee: Establecer estado del desarrollador IU de Apigee: Registrar desarrolladores de apps, consulta las instrucciones para desactivar (y activar) un desarrollador.
`keymanagement.service.invalid_client-app_not_approved`	`401`	Se revoca la app de desarrollador asociada con la clave de API. Una app revocada no puede acceder a ningún producto de API ni invocar APIs administradas por Apigee. Un administrador de la organización puede cambiar el estado de una app para desarrolladores con la API de Apigee. Consulta Genera pares de claves o actualizar el estado de las apps para desarrolladores.
`oauth.v2.FailedToResolveAPIKey`	`401`	La política espera encontrar la clave de API en una variable que se especifica en el elemento <APIKey> de la política. Este error surge cuando la variable esperada no existe (no se puede resolver).
`oauth.v2.InvalidApiKey`	`401`	Apigee recibió una clave de API, pero no es válida. Cuando Apigee busca la clave en su base de datos, debe coincidir de forma exacta con la que se envió en la solicitud. Si la API funcionó antes, asegúrate de que no se haya vuelto a generar la clave. Si se volvió a generar la clave, verás este error si intentas usar la clave antigua. Para obtener más información, consulta Controla el acceso a tus APIs mediante el registro de apps.
`oauth.v2.InvalidApiKeyForGivenResource`	`401`	Apigee recibió una clave de API y es válida, pero no coincide con una clave aprobada en la app para desarrolladores asociada con el proxy de API a través de un producto.

Nota: Por el momento, Apigee no informa el error ApiKeyNotApproved con precisión. En su lugar, si una clave no está aprobada (su estado está configurado como revoked o pending), recibirás el error FailedToResolveAPIKey. Para obtener más información y una posible solución, consulta Verifica que la clave de API no informe la clave de API no aprobada.

Errores en la implementación

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

Nombre del error	Causa
`SpecifyValueOrRefApiKey`	El elemento `<APIKey>` no tiene un valor ni una clave especificados.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

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 Matches "FailedToResolveAPIKey"`
`oauthV2.policy_name.failed`	`policy_name` es el nombre especificado por el usuario de la política que generó la falla.	`oauthV2.VK-VerifyAPIKey.failed = true`

Ejemplos de respuesta de errores

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

{
   "fault":{
      "faultstring":"Invalid ApiKey",
      "detail":{
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{
   "fault":{
      "detail":{
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Ejemplo de regla de falla

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>