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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`keymanagement.service.consumer_key_missing_api_product_association`	`400`	The application credential is missing an API product association. Please associate the key's application with an API product. Note that this applies for all application types, such as developer apps and AppGroup apps.
`keymanagement.service.DeveloperStatusNotActive`	`401`	The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways: Apigee API: Set Developer Status Apigee UI: In Register app developers, see the instructions for deactivating (and activating) a developer.
`keymanagement.service.invalid_client-app_not_approved`	`401`	The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee. An org admin can change the status of a Developer App using the Apigee API. See Generate Key Pair or Update Developer App Status.
`oauth.v2.FailedToResolveAPIKey`	`401`	The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
`oauth.v2.InvalidApiKey`	`401`	An API key was received by Apigee, but it is invalid. When Apigee looks up the key in its database, it must exactly match the one that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Controlling access to your APIs by registering apps.
`oauth.v2.InvalidApiKeyForGivenResource`	`401`	An API key was received by Apigee, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Note: Currently, Apigee does not report the ApiKeyNotApproved error accurately. Instead, if a key is not approved (its status is set to revoked or pending), you will get the FailedToResolveAPIKey error instead. For more information and a possible workaround, see Verify api key not reporting api key not approved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`SpecifyValueOrRefApiKey`	The `<APIKey>` element does not have a value or key specified.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "FailedToResolveAPIKey"`
`oauthV2.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`oauthV2.VK-VerifyAPIKey.failed = true`

Example error responses

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

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

Example fault rule

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