OAuth2 JWT bearer
APIs que autentican con una clave privada RSA en nombre de un usuario, como la firma electrónica de DocuSign. Qué es cada campo y cómo leer los errores.
Cuándo. La documentación habla de JWT Grant, JWT bearer o service integration con un par de claves RSA. En vez de un secreto compartido, el proveedor tiene tu clave pública y vos guardás la privada; con ella Nxar firma un pedido que dice “soy esta aplicación, actuando en nombre de este usuario”. Es el esquema de DocuSign y de varias APIs corporativas.
Qué hace Nxar. Antes de llamar a la API, si no tiene un token vigente:
- Arma un JWT con el Client ID como emisor, el User ID como el usuario en cuyo nombre actúa, la Audiencia y el Scope, válido por una hora.
- Lo firma con la Clave privada (PEM) (RS256).
- Lo cambia por un token en la Token URL (grant
urn:ietf:params:oauth:grant-type:jwt-bearer). - Llama a la API con
Authorization: Bearery ese token, y lo reusa hasta que vence. Al vencer, firma uno nuevo.
No hay un servicio público de prueba para este tipo: necesitás una aplicación dada de alta en el proveedor. Los ejemplos usan el ambiente de prueba de DocuSign, que es el caso más común.
Un workspace con el escenario ya armado, que se borra solo a las 48 h. Estamos terminándolo.
Creá la integración con la URL de la API
ConfiguraciónIntegraciones y APIIntegrationsNueva Integration: Etiqueta Firma electrónica (JWT), Nombre firma_jwt, Método GET, y en URL la dirección base de la API que vas a usar (la de tu cuenta en el proveedor). Crear.
Completá los seis campos
Editar. En Autenticación, Tipo: OAuth2 (JWT bearer):
| Campo | Qué va | Ejemplo (DocuSign, prueba) |
|---|---|---|
| Token URL | El endpoint de tokens del proveedor | https://account-d.docusign.com/oauth/token |
| Client ID | El identificador de tu aplicación (en DocuSign, la integration key) | |
| User ID (impersonado) | El usuario del proveedor en cuyo nombre actúa Nxar | |
| Audiencia | A quién va dirigido el JWT; lo dice la documentación | account-d.docusign.com |
| Scope (opcional) | Los permisos que pedís, separados por espacios | signature impersonation |
| Clave privada (PEM) | La clave privada RSA, completa, con las líneas BEGIN y END |
Guardar, volvé a la lista y reabrí la integración: Autenticación dice OAuth2 (JWT bearer) seguido del User ID.
Probala contra un endpoint real
En Test, con Path (opcional) apuntando a un endpoint de lectura de la API, Ejecutar Test.
Mientras editás, la Clave privada (PEM) se ve en texto plano en la pantalla. Cargala sin nadie mirando ni pantalla compartida. Una vez guardada, se guarda cifrada y en su lugar queda ***.
Cómo saber si funcionó
- 200 con datos: la firma y el token están bien.
- Un error en rojo en vez de un resultado: falló el pedido del token. Desde una automation, los Logs de ejecución muestran el motivo completo, que empieza con
OAuth2 JWT-bearer token request failed (HTTP 400): …y sigue con la respuesta del proveedor. Los motivos más comunes:consent_required(DocuSign): el usuario impersonado todavía no autorizó la aplicación. Se hace una sola vez, desde el navegador, con el enlace de consentimiento que explica la documentación del proveedor.invalid_grant: el User ID, la Audiencia o la Token URL no corresponden al mismo ambiente (prueba contra producción es el error clásico), o la clave privada no es la pareja de la pública que cargaste en el proveedor.
- Si falta alguno de los cinco campos obligatorios (todos menos Scope), el error lo dice:
JWT-bearer config incompleta.
Los ambientes de prueba y de producción de un proveedor suelen tener Token URL y Audiencia distintas. Si pasás a producción, cambiá las dos juntas.
Cómo saber que te salió
Ejecutar Test contra un endpoint de lectura de la API devuelve 200. Si falla, el primer error a descartar es el consentimiento del usuario impersonado.
¿Te funcionó?