Política de VerifyAPIKey

Estás viendo la documentación de Apigee Edge.
Ve a 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 de Edge estándar que se propaga con el valor de un parámetro de consulta que se pasó 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 estándar de Edge que se propaga con el valor de un encabezado que se pasó 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 ejecuta la Verify API Key. 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.

Conoce Edge

Acerca de la política Verificar clave de API

Cuando un desarrollador registra una app en Edge, Edge genera automáticamente una clave de consumidor y par secreto. Puedes ver la clave de consumidor y el par secreto 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 ejecuta la política Verify API Key. 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 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.

 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

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>

Esquemas

Variables de flujo

Cuando se aplica una política de Verificar clave de API a una clave de API válida, Edge propaga un conjunto de flujos variables. 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
  • Análisis

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 productos de la API se completan automáticamente si los productos de la API se configurados con entornos, proxies y recursos válidos (derivados de el proxy.pathsuffix). Si deseas obtener instrucciones para configurar productos de API, consulta Cómo usar el perímetro Management de Google a las APIs de Publish.

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 app, como "Empresa" o "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 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 falla 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 estás usando tiene un inactivo. Cuando el estado de una empresa se establece como inactiva, no puede acceder a la desarrolladores o aplicaciones asociados con esa Empresa. Un administrador de la organización puede cambiar el estado de una empresa con la API de Management. Consulta Establece el estado de una Empresa.
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 y no puede invocar ninguna API administrada por Apigee Edge. Un administrador de la organización puede cambiar el estado de una app de desarrollador usando la API de administración Consulta Aprobar o Revocar la App de Desarrollador
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 Edge recibió una clave de API, pero no es válida. Cuando Edge busca la clave en su debe coincidir exactamente con el 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 Registra apps y administra la API claves.
oauth.v2.InvalidApiKeyForGivenResource 401 Edge recibió una clave de API que es válida. Sin embargo, no coincide con un 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 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>

Temas relacionados