Política de VerifyAPIKey

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

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.

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 perimetral estándar que se propaga con el valor de un parámetro de consulta 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 perimetral 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>

Edge propaga automáticamente un conjunto de variables de flujo cuando se ejecuta la política Verificar clave de API para una clave de API válida. 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.

Aprende Edge


Acerca de la política Verificar clave de API

Cuando un desarrollador registra una app en Edge, esta genera automáticamente un par secreto y una clave de consumidor. Puedes ver el par de secreto y clave de consumidor de la app en la IU de Edge o acceder a ellos desde la API de Edge.

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.

Edge propaga automáticamente un conjunto de variables de flujo cuando se ejecuta la política Verificar clave de API. 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"/>
</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 Predeterminada 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.

No disponible Obligatorias
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.

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 Funciones obsoletas

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

No disponible

Si omites este elemento, se usa 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. 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.

Predeterminada N/A
Presencia Obligatorias
Tipo Cadena

Atributos

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

Atributo Descripción Predeterminada Presencia
ref

Una referencia a la variable que contiene la clave de API Solo se permite una ubicación por política.

No disponible Obligatorias

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>

Esquemas

Variables de flujo

Cuando se aplica una política de verificación de clave de API en una clave de API válida, Edge 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
  • Programador
  • Empresa
  • Analytics

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 de la app de desarrollador que realiza la solicitud.

developer.app.name El nombre de la app de desarrollador que realiza la solicitud
developer.id

El ID del desarrollador registrado como el propietario de la app que lo solicita

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 de producto de la API se propagan automáticamente si los productos de API están configurados con entornos, proxies y recursos válidos (derivados de proxy.pathsuffix). Si deseas obtener instrucciones para configurar productos de API, consulta Cómo usar la API de Edge Management para publicar 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 Indica el tipo de app, ya sea "Company" o "Developer".
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 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.
Company El nombre de la empresa, si existe alguno, asociado con el desarrollador.

Variables de flujo de la empresa

La política propaga las siguientes variables de flujo que contienen información sobre la empresa que propaga la política. Estas variables tienen el siguiente prefijo:

verifyapikey.{policy_name}.company

Por ejemplo:

verifyapikey.{policy_name}.company.name

Las variables disponibles incluyen las siguientes:

Variable Descripción
name El nombre de la empresa
displayName El nombre visible de la empresa.
id

El ID de la empresa

apps Un arreglo que contiene la lista de apps de la empresa.
appOwnerStatus
El estado del propietario de la app, como activo, inactivo o login_lock.
created_at La marca de fecha y hora de cuando se creó la empresa
created_by La dirección de correo electrónico del usuario que creó la empresa.
last_modified_at La marca de fecha y hora de la última modificación de la empresa
last_modified_by La dirección de correo electrónico del usuario que modificó la empresa por última vez.
{company_custom_attributes} Cualquier atributo personalizado de la empresa 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

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge 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.CompanyStatusNotActive 401 La empresa asociada con la app de desarrollador que tiene la clave de API que usas tiene un estado inactivo. Cuando el estado de una empresa se establece como inactivo, no puedes acceder a los desarrolladores o las apps asociados con esa empresa. Un administrador de la organización puede cambiar el estado de una empresa con la API de Management. Consulta cómo establecer el estado de una empresa.
keymanagement.service.DeveloperStatusNotActive 401

El desarrollador que creó la app de desarrollador que tiene la clave de API que estás usando tiene el estado inactivo. Si el estado de un desarrollador de apps se establece como inactivo, se desactivarán todas las apps para desarrolladores que haya creado 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 ninguna API administrada por Apigee Edge. Un administrador de la organización puede cambiar el estado de una app de desarrollador con la API de administración. Consulta Aprobar o revocar apps de desarrollador.
oauth.v2.FailedToResolveAPIKey 401 La política espera encontrar la clave de API en una variable que se especifique en el elemento <APIKey> de la política. Este error se produce cuando la variable esperada no existe (no se puede resolver).
oauth.v2.InvalidApiKey 401 Edge recibió una clave de API, pero no es válida. Cuando Edge busca la clave en su base de datos, debe coincidir exactamente con el que se envió en la solicitud. Si la API funcionó anteriormente, asegúrate de que no se haya vuelto a generar la clave. Si se volvió a generar la clave, verás este error cuando intentes usar la clave anterior. Para obtener más información, consulta Registra apps y administra claves de API.
oauth.v2.InvalidApiKeyForGivenResource 401 Edge recibió una clave de API y esta es válida. Sin embargo, no coincide con una clave aprobada en la app de desarrollador asociada con tu 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 o 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

Respuestas de error de ejemplo

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

Temas relacionados