Política VerifyAPIKey

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

Consulta la documentación de Apigee Edge.

Icono de política

Información general

La política Verify API Key te permite aplicar la verificación de claves de API en el entorno de ejecución, de forma que solo las aplicaciones con claves de API aprobadas puedan acceder a tus APIs. Esta política asegura que las claves de API sean válidas, no se hayan revocado y estén aprobadas para consumir los recursos específicos asociados a tus productos de API.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Para ver un tutorial sobre cómo crear un proxy de API que utilice la política Verify API Key, consulta Proteger una API solicitando claves de API.

Ejemplos

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 estándar de Apigee que se rellena con el valor de un parámetro de consulta que se ha enviado en la solicitud del cliente.

El siguiente comando curl envía la clave de API en un parámetro de consulta:

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 estándar de Apigee que se rellena con el valor de un encabezado enviado en la solicitud del cliente.

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

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

Clave en variable

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

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

Tú decides cómo se rellena esa variable. Por ejemplo, puede usar la política Extract Variables para rellenar requestAPIKey.key a partir de un parámetro de consulta 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 la política 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>

Apigee rellena automáticamente un conjunto de variables de flujo al ejecutar la política Verify API Key para una clave de API válida. Puedes usar estas variables para acceder a información como el nombre de la aplicación, el ID de la aplicación e información sobre el desarrollador o la empresa que registró la aplicación. En el ejemplo anterior, se usa la política Asignar mensaje para acceder al nombre, los apellidos y la dirección de correo del desarrollador después de que se ejecute la política Verificar clave de API.

Todas estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}

En este ejemplo, el nombre de la política de verificación de la clave de API es "verify-api-key". Por lo tanto, debes hacer referencia al nombre del desarrollador que hace la solicitud accediendo a la variable verifyapikey.verify-api-key.developer.firstName..

Aprender a usar Apigee

Acerca de la política Verificar clave de API

Cuando un desarrollador registra una aplicación en Apigee, Apigee genera automáticamente un par de clave de consumidor y secreto. Puedes ver el par de clave y secreto de consumidor de la aplicación en la interfaz de Apigee o acceder a ellos desde la API de Apigee.

En el momento de registrar la aplicación, el desarrollador selecciona uno o varios productos de API para asociarlos a la aplicación. Un producto de API es una colección de recursos a los que se puede acceder a través de proxies de API. A continuación, el desarrollador envía la clave de API (clave de consumidor) como parte de cada solicitud a una API de un producto de API asociado a la aplicación. Consulta más información en el resumen de publicación.

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

Apigee rellena automáticamente un conjunto de variables de flujo al ejecutar la política Verify API Key. Consulta Variables de flujo más abajo para obtener más información.

Referencia de elemento

A continuación, se indican los elementos y atributos que puede 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 de <VerifyAPIKey>

En el ejemplo siguiente 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 superiores de la política:

Atributo Descripción Predeterminado Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

Elemento <APIKey>

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

Predeterminado N/A
Presencia Obligatorio
Tipo Cadena

Atributos

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

Atributo Descripción Predeterminado Presencia
ref

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 transfiere en parámetros y en un encabezado llamado x-apikey.

Como parámetro de consulta:

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

Como encabezado HTTP:

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

Como parámetro de formulario HTTP:

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

Elemento <CacheExpiryInSeconds>

Este elemento aplica un TTL a la caché, lo que permite personalizar el periodo de vencimiento del token de acceso almacenado en caché. El intervalo 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 omite este elemento, el periodo de vencimiento predeterminado del token de acceso almacenado en caché será de 180 segundos.
Presencia Opcional
Tipo Entero
Valores válidos Cualquier número entero positivo distinto de cero. Especifica el tiempo de vencimiento en segundos.

Atributos

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

Atributo Descripción Predeterminado Presencia
ref

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

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

 N/A Opcional

Esquemas

Variables de flujo

Cuando se aplica una política de verificación de claves de API a una clave de API válida, Apigee rellena un conjunto de variables de flujo. Estas variables están disponibles para las políticas o el código que se ejecutan más adelante en el flujo y se suelen usar para realizar un procesamiento personalizado basado en atributos de la clave de API, como el nombre de la aplicación, el producto de API usado para autorizar la clave o los atributos personalizados de la clave de API.

La política rellena varios tipos de variables de flujo, entre los que se incluyen los siguientes:

  • General
  • Aplicación
  • Desarrollador
  • Analytics
  • Monetización

Cada tipo de variable de flujo tiene un prefijo diferente. Todas las variables son escalares, excepto las que se indican específicamente como matrices.

Variables de flujo generales

En la siguiente tabla se enumeran las variables de flujo generales que rellena la política Verificar clave de API. Todas estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}

Por ejemplo: verifyapikey.{policy_name}.client_id

Entre las variables disponibles se incluyen las siguientes:

Variable Descripción
client_id La clave de consumidor (también conocida como clave de API o clave de aplicación) proporcionada por la aplicación que realiza la solicitud.
client_secret El secreto del consumidor asociado a la clave del consumidor.
redirection_uris Los URIs de redirección de la solicitud.
developer.app.id

ID del desarrollador o de la aplicación AppGroup que hace la solicitud.
developer.app.name Nombre de la aplicación del desarrollador o de la aplicación AppGroup que hace la solicitud.
developer.id

ID del desarrollador o del AppGroup registrado como propietario de la aplicación que hace la solicitud.
developer.{custom_attrib_name} Cualquier atributo personalizado derivado del perfil de clave de aplicación.
DisplayName Valor del atributo <DisplayName> de la política.
failed Se asigna el valor "true" cuando falla la validación de la clave de API.
{custom_app_attrib} Cualquier atributo personalizado derivado del perfil de la aplicación. Especifica el nombre del atributo personalizado.
apiproduct.name* Nombre del producto de la API usado 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 API, si lo hay.
apiproduct.developer.quota.interval* El intervalo de cuota definido en el producto de API, si lo hay.
apiproduct.developer.quota.timeunit* Unidad de tiempo de la cuota definida en el producto de API, si la hay.
* Las variables de producto de API se rellenan automáticamente si los productos de API se configuran con un entorno, proxies y recursos válidos (derivados de proxy.pathsuffix). Para obtener instrucciones sobre cómo configurar productos de API, consulta Gestionar productos de API.

Variables de flujo de aplicaciones

La política rellena las siguientes variables de flujo, que contienen información sobre la aplicación. Todas estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.app.

Por ejemplo:

verifyapikey.{policy_name}.app.name

Entre las variables disponibles se incluyen las siguientes:

Variable Descripción
name Nombre de la aplicación.
id ID de la aplicación.
accessType No lo usa Apigee.
callbackUrl La URL de retrollamada de la aplicación. Normalmente, solo se usa para OAuth.
DisplayName El nombre visible de la aplicación.
status El estado de la aplicación, como "aprobada" o "revocada".
apiproducts Es una matriz que contiene la lista de productos de API asociados a la aplicación.
appFamily Cualquier familia de aplicaciones que contenga la aplicación o "default".
appParentStatus El estado de la aplicación principal, como "activa" o "inactiva".
appType El tipo de aplicación "Desarrollador".
appParentId ID de la aplicación principal.
created_at Marca de fecha y hora en la que se creó la aplicación.
created_by La dirección de correo del desarrollador que creó la aplicación.
last_modified_at Marca de fecha y hora de la última actualización de la aplicación.
last_modified_by La dirección de correo del desarrollador que actualizó la aplicación por última vez.
{app_custom_attributes} Cualquier atributo de aplicación personalizado. Especifica el nombre del atributo personalizado.

Variables de flujo de AppGroup

La política rellena las siguientes variables de flujo, que contienen información sobre los AppGroups. Estos atributos de AppGroup solo se rellenan si verifyapikey.{policy_name}.app.appType es "AppGroup".

Todas estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.appgroup.

Por ejemplo:

verifyapikey.{policy_name}.appgroup.name

Entre las variables disponibles se incluyen las siguientes:

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

Variables de flujo de desarrollador

La política rellena las siguientes variables de flujo, que contienen información sobre el desarrollador. Todas estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.developer

Por ejemplo:

verifyapikey.{policy_name}.developer.id

Entre las variables disponibles se incluyen las siguientes:

Variable Descripción
id Devuelve {org_name}@@@{developer_id}
userName Nombre de usuario del desarrollador.
firstName Nombre del desarrollador.
lastName El apellido del desarrollador.
email La dirección de correo del desarrollador.
status El estado del desarrollador (activo, inactivo o login_lock).
apps Matriz de aplicaciones asociadas al desarrollador.
created_at Marca de fecha y hora en la que se creó el desarrollador.
created_by La dirección de correo electrónico del usuario que creó el desarrollador.
last_modified_at 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 de desarrollador personalizado. Especifica el nombre del atributo personalizado.

Variables de Analytics

Las siguientes variables se rellenan automáticamente en Analytics cuando se aplica una política de verificación de claves de API a una clave de API válida. Estas variables solo se rellenan con la política Verify API Key y las políticas de OAuth.

Las variables y los valores se pueden usar como dimensiones para crear informes de Analytics y obtener información sobre los patrones de consumo de los desarrolladores y las aplicaciones.

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

Variables de flujo de monetización

Después de autenticar al usuario, la política VerifyAPIKey comprueba todos los planes de tarifas publicados para determinar cuál, si hay alguno, está activo en función de sus horas de activación y caducidad. Si se encuentra un plan de tarifas publicado activo, se rellenan 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 del plan de tarifas.
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:
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.

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

{  
   "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>