Parámetros seguros: encriptar y enviar como cabecera

Parámetros seguros: encriptar y enviar como cabecera

Resumen

Vor-Tex permite proteger los datos sensibles que viajan en una solicitud de tres maneras, todas configurables desde el editor del método: marcar parámetros para que su valor se encripte antes de llegar al origen de datos, enviar parámetros como cabeceras HTTP en lugar de la query string o el cuerpo, y recibir la llave de acceso de la aplicación en la cabecera Authorization en lugar del parámetro auth_key. En este video se ve cómo activar cada opción sobre un método nuevo y cómo queda la llamada resultante.

Antes de comenzar

  • Las tres opciones se configuran por método, al crearlo o editarlo, y requieren publicar la versión de la API para que apliquen.
  • Para encriptar o enviar como cabecera hace falta que la vista expuesta tenga al menos un parámetro: la tabla de parámetros del método los lista con sus columnas ENCRIPTAR y ENVIAR EN ENCABEZADO.

Encriptar parámetros

Configuración

En la tabla de parámetros del método, marcar el checkbox de la columna ENCRIPTAR en la fila del parámetro y guardar el método con Listo.

Comportamiento

El cliente envía el valor en claro, como siempre. El gateway lo encripta con la clave de la plataforma antes de pasarlo al origen de datos, de modo que la vista, el pipeline o el origen de escritura reciben el valor cifrado. Es útil para tokens, contraseñas, claves de terceros u otros datos confidenciales que se almacenan o reenvían desde el origen y no deben quedar en claro. Como el valor llega cifrado, no sirve para parámetros que el origen usa para filtrar o comparar contra datos en claro.

Columnas de la tabla de parámetros

  • PARÁMETRO: nombre del parámetro que se envía en la solicitud.
  • POR DEFECTO: valor que toma el parámetro si no se envía uno.
  • VARIABLES DE CONTEXTO: variable de contexto asociada al parámetro, si la hay.
  • DESCRIPCIÓN: texto descriptivo, visible en el portal.
  • ENCRIPTAR: checkbox para encriptar el valor del parámetro.
  • ENVIAR EN ENCABEZADO: indica si el parámetro se envía como cabecera HTTP.

Enviar parámetros como cabeceras HTTP

Configuración

Debajo de la tabla de parámetros, hacer clic en Configurar. Se abre la ventana Configuración de parámetros, con una fila por parámetro. Marcar el checkbox de la columna Enviar en encabezado del parámetro deseado y confirmar con Listo. En la tabla, la columna ENVIAR EN ENCABEZADO muestra un tilde para ese parámetro.

Comportamiento

El portal para desarrolladores, los fragmentos de código y la documentación OpenAPI muestran el parámetro como una cabecera con el nombre del parámetro, y el gateway lo toma de la cabecera de la solicitud. Es útil para parámetros de autenticación como tokens o claves, identificadores de sesión o de inquilino, y metadatos que deben viajar como cabeceras estándar. Es posible activar ENCRIPTAR y Enviar en encabezado en el mismo parámetro.

Llave de acceso en la cabecera Authorization

En el bloque Seguridad del método, bajo Autenticación protegida usando una llave de acceso, elegir En una cabecera. A partir de la publicación, la llave de acceso de la aplicación debe enviarse como valor de la cabecera Authorization, y el gateway rechaza con 401 las solicitudes que la envían como parámetro auth_key. Con Como un parámetro, la opción por defecto, ocurre lo contrario.

Resultado esperado

Con la llave en la cabecera y el parámetro region marcado para enviarse como cabecera, la llamada del video es:

curl -H "Authorization: YOUR_AUTH_KEY" -H "region: Sur" "https://api.example.com/demo-ventas/v1/ventas-seguro.json"

La respuesta trae en meta.parameters el valor recibido por cabecera y, en el resultado, solo las filas de esa región. La URL no contiene ni la llave ni el parámetro.

Errores frecuentes

  • 401 al enviar auth_key en la URL: el método espera la llave en la cabecera Authorization. Revisar el bloque Seguridad.
  • El parámetro por cabecera no cambia el resultado: la respuesta anterior sigue en la caché del método, que se identifica por la URL. Esperar a que venza el tiempo de caché definido en los límites de la API, o reducirlo.
  • El origen recibe un valor ilegible: el parámetro está marcado como ENCRIPTAR. Desmarcarlo si el origen necesita el valor en claro.
  • La cabecera definida en el origen no llega al origen: definirla en la pestaña de cabeceras del origen solo la declara como parámetro. Para que viaje como cabecera HTTP hay que marcar Enviar en encabezado en la Configuración de parámetros del método.
  • El cambio no se ve en el portal: falta publicar la versión de la API después de guardar el método.

Artículos relacionados