Protege una API mediante la solicitud de claves de API

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

Qué aprenderás

En este instructivo, aprenderás a realizar lo siguiente:

  • Cómo crear un proxy de API que requiera una clave de API.
  • Agrega un producto de API.
  • Agrega un desarrollador y registra una app.
  • Cómo llamar a tu API con una clave de API.

Es importante proteger tu API del acceso no autorizado. Una forma de hacerlo es con claves de API (también llamadas claves públicas, claves de consumidor o claves de app).

Cuando una app realiza una solicitud a tu API, debe proporcionar una clave válida. En el entorno de ejecución, la política Verificar clave de API verifica que la clave de API proporcionada realice las siguientes acciones:

  • Es válida.
  • No se revocó.
  • Hace coincidir la clave de API del producto de API que expone los recursos solicitados.

Si la clave es válida, se permite la solicitud. Si la clave no es válida, la solicitud generará un error de autorización.

En este instructivo, crearás un proxy de API que requiere una clave de API válida para acceder a él.

Requisitos

  • Una cuenta de Apigee Edge Si aún no tienes una, puedes registrarte con las instrucciones de Crea una cuenta de Apigee Edge.
  • Un navegador web para realizar una llamada a la API.
  • (Para la sección de crédito adicional, no es necesario) tener instalado cURL en tu máquina a fin de realizar llamadas a la API desde la línea de comandos.

Crea el proxy de API

Acerca del destino ficticio

El servicio mocktarget se aloja en Apigee y muestra datos simples. No requiere una clave de API ni un token de acceso. De hecho, puedes acceder a ella desde un navegador web. Haz clic en los siguientes vínculos para probarlo:

http://mocktarget.apigee.net

El destino muestra Hello, Guest!. Usa el recurso /help para obtener una página de ayuda de otros recursos de API disponibles.

  1. Ve a https://apigee.com/edge y accede.
  2. Para cambiar a la organización que deseas, haz clic en tu nombre de usuario en la parte superior de la barra de navegación lateral para que se muestre el menú de perfil del usuario y, luego, selecciona la organización de la lista.

    seleccionar org en el menú del perfil del usuario
  3. Haz clic en Proxies de API en la página de destino para mostrar la lista de proxies de API.

    Menú de las APIs de Edge
  4. Haz clic en + Proxy.
    Botón para Crear proxy
  5. En la página Crear proxy, selecciona Proxy inverso (más común).
  6. En la página Proxy Details, configura el proxy de la siguiente manera:
    En este campo haz lo siguiente Sigue estas recomendaciones
    Proxy name Ingresa: helloworld_apikey
    Ruta de acceso base del proyecto

    Cambia a: /helloapikey

    La ruta base del proyecto es parte de la URL que se usa para realizar solicitudes al proxy de API.

    Nota: Para obtener recomendaciones de Apigee sobre el control de versiones de API, consulta Control de versiones en el libro electrónico Web API Design: The Missing Link.

    Existing API

    Ingresa: http://mocktarget.apigee.net

    Esto define la URL de destino que invoca Apigee Edge en una solicitud al proxy de API.

    Descripción Ingresa: hello world protected by API key
  7. Presiona Siguiente.
  8. En la página Políticas comunes, en Seguridad: autorización, selecciona Clave de API y, luego, haz clic en Siguiente. Esto agregará dos políticas a tu proxy de API.
  9. En la página Virtual Hosts, selecciona default y secure, y haz clic en Next. Si seleccionas default, podrás llamar a tu API con http://. Si seleccionas segura, podrás llamar a tu API con https://.
  10. En la página Resumen, asegúrate de que el entorno de implementación de pruebas esté seleccionado y, luego, haz clic en Crear e implementar.
  11. Verás una confirmación de que tu nuevo proxy de API y un producto de API se crearon correctamente, y que el proxy de API se implementó en tu entorno de pruebas.
  12. Haz clic en Editar proxy para mostrar la página Descripción general del proxy de API.

Visualiza las políticas

  1. En el editor de proxy de API haga clic en la pestaña Desarrollar. Verás que se agregaron dos políticas al flujo de solicitudes del proxy de API:
    • Verificar clave de API: Comprueba la llamada a la API para asegurarse de que haya una clave de API válida (enviada como un parámetro de consulta).
    • Quitar la clave de API del parámetro de consulta: Es una política deAssignMessage que quita la clave de API después de verificarla, de modo que no se transmita ni se exponga de forma innecesaria.
  2. Haz clic en el ícono de verificación de la política de clave de API en la vista de flujo y observa la configuración XML de la política en la vista de código inferior. El elemento <APIKey> le indica a la política dónde debe buscar la clave de API cuando se realiza la llamada. De forma predeterminada, busca la clave como un parámetro de consulta llamado apikey en la solicitud HTTP:

    <APIKey ref="request.queryparam.apikey" />
    

    El nombre apikey es arbitrario y puede ser cualquier propiedad que contenga la clave de API.

Intenta llamar a la API

En este paso, realizarás una llamada a la API de forma correcta directamente en el servicio de destino y, luego, realizarás una llamada incorrecta al proxy de API para ver cómo las políticas lo protegen.

  1. Listo

    En un navegador web, ve a la siguiente dirección. Este es el servicio de destino al que el proxy de API está configurado para reenviar la solicitud, pero lo llegarás directamente por ahora:

    http://mocktarget.apigee.net
    

    Deberías obtener la respuesta correcta: Hello, Guest!

  2. Falla

    Ahora, intenta llamar a tu proxy de API:

    http://ORG_NAME-test.apigee.net/helloapikey
    

    reemplaza ORG_NAME por el nombre de la organización de Edge.

    Sin la política Verificar clave de API, esta llamada te brindaría la misma respuesta que la anterior. Sin embargo, en este caso, deberías obtener la siguiente respuesta de error:

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
    

    lo que significa, correctamente, que no pasaste una clave de API válida (como parámetro de consulta).

En los próximos pasos, agregarás un producto de API.

Agrega un producto de API

Para agregar un producto de API mediante la IU de Apigee, sigue estos pasos:

  1. Selecciona Publicar > Productos de API.
  2. Haz clic en +API Product.
  3. Ingresa los Detalles del producto de tu producto de API.

    Campo Descripción
    Nombre Nombre interno del producto de API. No especifiques caracteres especiales en el nombre.
    Nota: No puedes editar el nombre una vez que se crea el producto de API. Por ejemplo, helloworld_apikey-Product.
    Nombre visible Nombre visible del producto de API. El nombre visible se usa en la IU y puedes editarlo en cualquier momento. Si no se especifica, se usará el valor de Nombre (Name). Este campo se completa automáticamente con el valor Nombre; puedes editar o borrar su contenido. El nombre visible puede incluir caracteres especiales. Por ejemplo, helloworld_apikey-Product.
    Descripción Descripción del producto de API. Por ejemplo, Test product for tutorial.
    Entorno Entornos a los que el producto de API permitirá el acceso Por ejemplo, test o prod.
    Acceso Selecciona Público.
    Aprueba de manera automática las solicitudes de acceso Habilita la aprobación automática de solicitudes de claves para este producto de API desde cualquier app.
    Cuota Ignora este instructivo.
    Permisos de OAuth permitidos Ignora este instructivo.
  4. En la sección API resources, selecciona el proxy de API que acabas de crear. Por ejemplo, helloworld_apikey.
  5. Haz clic en Agregar.
  6. En la sección Rutas, agrega la ruta "/".
  7. Haz clic en Agregar.
  8. Haz clic en Guardar.

En los próximos pasos, obtendrás la clave de API necesaria.

Agrega un desarrollador y una app a tu organización

A continuación, simularemos el flujo de trabajo de un desarrollador que se registra para usar tus APIs. Un desarrollador tendrá una o más apps que llamen a tus APIs y cada una obtendrá una clave de API única. Esto te brinda como proveedor de API un control más detallado del acceso a tus APIs, así como informes más detallados sobre el tráfico de API por app.

Cree un desarrollador

Para crear un desarrollador, haz lo siguiente:

  1. Selecciona Publicar > Desarrolladores en el menú.
  2. Haz clic en + Desarrollador.
  3. En la ventana New Developer, ingrese lo siguiente:

    En este campo haz lo siguiente ingresar
    Nombre Keyser
    Apellido Soze
    Nombre de usuario keyser
    Correo electrónico keyser@example.com
  4. Haz clic en Crear.

Registra una aplicación

Para registrar una app de desarrollador, sigue estos pasos:

  1. Selecciona Publicar > Apps.
  2. Haga clic en + Aplicación.
  3. En la ventana New App, ingresa lo siguiente:

    p
    En este campo haz lo siguiente Sigue estas recomendaciones
    Nombre y Nombre visible Ingresa: keyser_app
    Empresa/Programador Selecciona: Developer
    Desarrollador Selecciona: Keyser Soze (keyser@example.com)
    URL de devolución de llamada y Notas Déjelo en blanco
  4. En la sección Credenciales, selecciona Nunca en el menú Vencimiento. Las credenciales para esta app no expirarán nunca.
  5. En Productos, haz clic en Agregar producto.
  6. Selecciona helloworld_apikey-Product.
  7. Haz clic en Agregar.
  8. Haz clic en Crear arriba y a la derecha de la sección Detalles de la app para guardar tu trabajo.

Obtenga la clave de API

Para obtener la clave de API, sigue estos pasos:

  1. En la página Apps (Publicar > Apps), haz clic en keyser_app.
  2. En la página keyser_app, haz clic en Mostrar junto a Clave en la sección Credenciales. En la sección Producto, ten en cuenta que la clave está asociada con helloworld_apikey.

  3. Selecciona y copia la Clave. La necesitarás en el próximo paso.

Llama a la API con una clave

Ahora que tienes una clave de API, puede usarla para llamar al proxy de API. Ingresa lo siguiente en tu navegador web. Sustituye el nombre de tu organización de Edge por ORG_NAME y la clave de API por API_KEY a continuación. Asegúrate de que no haya espacios adicionales en el parámetro de consulta.

http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY

Ahora, cuando llames al proxy de API, deberías obtener esta respuesta: Hello, Guest!

¡Felicitaciones! Creaste un proxy de API y lo protegiste, ya que solicitaste que se incluya una clave de API válida en la llamada.

Ten en cuenta que, en general, no es recomendable pasar una clave de API como parámetro de consulta. Deberías considerar pasarla en el encabezado HTTP en su lugar.

Práctica recomendada: Pasa la clave en el encabezado HTTP

En este paso, modificarás el proxy para buscar la clave de API en un encabezado llamado x-apikey.

  1. Edita el proxy de la API. Selecciona Develop > API Proxies > helloworld_apikey y ve a la vista Develop.
  2. Selecciona la política Verify API Key y modifica el XML de la política para indicarle a la política que busque en header en lugar de queryparam:

    <APIKey ref="request.header.x-apikey"/>
    
  3. Guarda el proxy de API para implementar el cambio.
  4. Realiza la siguiente llamada a la API con cURL para pasar la clave de API como un encabezado llamado x-apikey. No olvides reemplazar el nombre de tu organización.

    curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
    

Ten en cuenta que, para completar el cambio por completo, también tendrías que configurar la política AssignMessage a fin de quitar el encabezado, en lugar del parámetro de consulta. Por ejemplo:

<Remove>
<Headers>
    <Header name="x-apikey"/>
</Headers>
</Remove>

Temas relacionados

Aquí hay algunos temas que se relacionan directamente con este instructivo:

Profundizar un poco más y proteger las API con claves de API es solo una parte de la historia. A menudo, la protección de las APIs implica seguridad adicional, como OAuth.

OAuth es un protocolo abierto que, en pocas palabras, intercambia credenciales (como nombre de usuario y contraseña) por tokens de acceso. Los tokens de acceso son cadenas largas y aleatorias que se pueden pasar por una canalización de mensajes, incluso de una app a otra, sin comprometer las credenciales originales. Los tokens de acceso suelen tener vidas cortas, de manera que siempre se generan nuevos.