Proveedor de seguridad de clave API en Jitterbit App Builder

El proveedor de seguridad API Key permite a los administradores proteger las API REST de App Builder usando un código de clave API generado por App Builder. El consumidor pasa la clave API a App Builder al hacer solicitudes de API REST. Como cada clave API se asocia con un usuario individual, esto proporciona tanto autenticación como autorización.

Definición y casos de uso

Las claves API de App Builder constan de un número criptográficamente aleatorio de 128 bits. Las claves están codificadas en base64url. A continuación se muestra un ejemplo de una clave API:

DLOo9sPS5slJEMHpXBFt3g

Las claves API tienen las siguientes ventajas sobre la autenticación estándar de nombre de usuario/contraseña:

• Tienen mayor entropía que las combinaciones de nombre de usuario y contraseña.
• Pueden sobrevivir a un cambio de contraseña.
• Se pueden revocar fácilmente.
• Se pueden rotar.
• Son más rápidas. Las contraseñas deben procesarse mediante hash, lo que es intencionalmente lento.

Las desventajas o debilidades de las claves API incluyen la gestión de su distribución y el riesgo de filtraciones. Algunos de los casos de uso donde las claves API pueden ser el método de autenticación más adecuado incluyen:

• Cuentas de nivel de servicio
• Comunicación de aplicación a aplicación
• Comunicación de servidor a servidor
• Acceso de solo lectura
• Información no sensible

Agregar un proveedor de seguridad de clave API

Para agregar un nuevo proveedor de seguridad de clave API, sigue estos pasos:

1. Ve a IDE > Security Providers. Se abre la página Security.

2. Haz clic en + Security Provider. Aparece la página Provider:

   

3. En la sección Settings, completa estos campos:

   1. Name: Ingresa un nombre para identificar tu proveedor de seguridad de clave API.

   2. Type: En el menú desplegable, selecciona API Key como el tipo de proveedor de seguridad que estás creando. Esto alterará los campos restantes que se muestran en el diálogo.

   3. Priority: Ingresa un número para establecer el orden en que los proveedores de seguridad aparecen en el formulario de inicio de sesión.

   4. Enabled: Haz clic en esta casilla de verificación para activar el nuevo proveedor de seguridad.

   5. Identifier: App Builder genera este campo automáticamente.

4. En la sección Keys, completa estos campos:

   1. Default Expiry: Ingresa cuántos minutos para la vida útil predeterminada de las claves nuevas. (Alterar este campo no afecta las claves existentes).

   2. Max Expiry: Ingresa cuántos minutos para la vida útil máxima de las claves nuevas. (Alterar este campo no afecta las claves existentes).

   3. Length: Ingresa la longitud (en bytes) de las claves nuevas. (Alterar este campo no afecta las claves existentes).

5. Haz clic en Save.

Después de guardar un nuevo proveedor de seguridad de clave API, volverás a la página Security, donde el panel Security Providers mostrará el nuevo que acabas de crear. Al hacer clic en el icono al final de su fila, puedes seguir configurándolo.

Configurar un proveedor de seguridad de clave API

Para configurar tu proveedor de seguridad de clave API, ve a IDE > Security Providers. Localízalo en el panel Security Providers y haz clic en el icono al final de su fila. Se mostrará la página Provider, donde puedes agregar configuraciones adicionales. El panel Provider a la izquierda muestra los mismos parámetros y claves que se muestran cuando creaste el proveedor de seguridad. El panel Properties a la derecha te permite configurar algunos parámetros adicionales, descritos a continuación.

Para agregar una nueva propiedad, haz clic en el botón + Property. Esto abrirá el diálogo Properties, que contiene los campos Parameter y Value. Los siguientes parámetros están disponibles:

• AllowApiKeyInQueryString: Usa este parámetro para permitir que la clave de API se pase en la cadena de consulta en lugar de en el encabezado HTTP (consulta la sección Pasar una clave de API). El valor predeterminado es False.

• AllowInsecureHttp: Usa este parámetro para permitir que la clave de API se pase a través de una solicitud HTTP insegura en lugar de una solicitud HTTPS segura (consulta la sección Pasar una clave de API). El valor predeterminado es False.

• HttpHeaderName: Usa este parámetro para cambiar el nombre del encabezado HTTP que pasará la clave de API del valor predeterminado X-API-Key.

• QueryStringParameterName: Cuando también hayas usado la opción AllowApiKeyInQueryString para pasar la clave de API a través de uno de los parámetros de cadena de consulta, puedes usar esta opción para cambiar el nombre del parámetro del nombre predeterminado apiKey (consulta la sección Pasar una clave de API).

Haz clic en Guardar y cierra el diálogo Propiedades. El nuevo parámetro que hayas agregado se mostrará en la tabla Propiedades.

Generar una clave de API

Cuando tengas un proveedor de seguridad de clave de API configurado, puedes generar claves de API asociadas con usuarios siguiendo estos pasos:

1. Ve a IDE > Runtime > Gestión de usuarios.

2. El panel Usuarios muestra todos los usuarios. Localiza el usuario para el que deseas generar una clave de API y haz clic en el icono al final de su fila.

3. En el diálogo Usuario, haz clic en Más > Claves. Se abre el diálogo Claves.

4. Haz clic en Crear. Se abrirá el diálogo Generar clave.

5. En el menú Proveedor, selecciona el proveedor de seguridad de clave de API que creaste.

6. (Opcional) Proporciona una Descripción para esta clave e ingresa un tiempo de vencimiento personalizado en el campo Vence en.

7. Haz clic en Guardar. Se creará la clave de API.

Pasar una clave de API

En la mayoría de los escenarios, Jitterbit recomienda que el cliente pase la clave de API a través de un encabezado personalizado en una conexión HTTPS segura para limitar el riesgo de exposición. El siguiente ejemplo ilustra esto:

GET /Vinyl/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: ABCd0eFG1hiJKLMnOPQr2s

Este es el comportamiento predeterminado, que App Builder selecciona automáticamente. También puedes usar el parámetro HttpHeaderName cuando estés configurando tu clave de API para cambiar el nombre del encabezado HTTP que pasará la clave de API del valor predeterminado X-API-Key.

Los siguientes ejemplos son algunas excepciones a esta recomendación:

1. En algunos escenarios, las conexiones HTTPS pueden terminarse prematuramente. Para solucionar este problema, puedes forzar que App Builder acepte claves de API enviadas a través de conexiones HTTP configurando el parámetro AllowInsecureHttp en True durante la configuración de la clave de API.

2. En casos donde no tengas acceso a los encabezados de solicitud HTTP, también es posible enviar la clave de API a través de los parámetros de cadena de consulta. Para habilitar esta opción, establece AllowApiKeyInQueryString en True en las configuraciones de clave de API. El ejemplo a continuación ilustra cómo se pasa la clave de API en este escenario:

   GET /Vinyl/rest/v1/sales/customers?apiKey=ABCd0eFG1hiJKLMnOPQr2s HTTP/1.1
   HOST: example.com:443
   Accept: application/json
   

   Nota

   En el ejemplo anterior, la clave se envió con el nombre apiKey. Puedes cambiar esto yendo a la configuración de clave de API y agregando el parámetro QueryStringParameterName para elegir un nombre diferente.