Política de VerifyAPIKey

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

Consulta la documentación de Apigee Edge.

ícono de política

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 Configuración predeterminada Presence
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:

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

 false Obsoleto

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>
Configuración predeterminada

N/A

Si omites este elemento, se usa el valor del atributo name de la política.
Presence 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
Presence Obligatorio
Tipo String

Atributos

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

Atributo Descripción Predeterminado Presence
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.
Presence 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 Presence
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
  • Aplicación
  • 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.
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.
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 Es el nombre del AppGroup.
id El ID de AppGroup.
displayName El nombre visible 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 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:
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>