OAuth y autorización de apps

OAuth es el intercambio que permite que una aplicación actúe sobre una cuenta de AppBO sin tener nunca la contraseña del dueño de la cuenta. De un lado está tu aplicación: registrada una sola vez, con un identificador de cliente y un secreto de cliente. Del otro está el dueño de la cuenta o el administrador de la agencia, que pasa por una pantalla de consentimiento y le otorga a tu app un conjunto definido de permisos sobre una cuenta específica. Lo que vuelve es un token de acceso de corta duración, un token de renovación de duración más larga y un registro de exactamente qué cuenta y qué alcances cubre la autorización.

Esto se conecta siempre que más de una cuenta vaya a usar tu integración, o siempre que lo que se conecta sea un producto y no un script de una sola vez. Una sola clave privada escrita directamente en una tarea programada (cron) sirve para tu propia cuenta; deja de funcionar en cuanto un segundo cliente la necesita, porque le estarías pidiendo a ese cliente que entregue credenciales que no se pueden limitar ni revocar de forma independiente.

Vale la pena distinguir dos formas de autorización. Una autorización de subcuenta (ubicación) autoriza a tu app sobre los datos de una sola cuenta. Una autorización de agencia autoriza a tu app a nivel superior, y después puede obtener tokens para las cuentas que dependen de ella. Las autorizaciones de agencia son el modelo correcto para un producto que atiende a toda la cartera de clientes de una agencia; también son las que más fácilmente quedan con alcances mal definidos, porque los permisos son más amplios y el radio de daño de un token filtrado son todos los clientes de esa agencia.

1. Registra la aplicación en el área de desarrolladores de la plataforma. Anota el identificador de cliente y el secreto de cliente, y guarda el secreto en un gestor de secretos desde el principio, no en un repositorio, en el código del frontend ni en una app móvil.
2. Decide si la app se autoriza por subcuenta o a nivel de agencia, y configura la aplicación en consecuencia. Esta decisión define qué alcances están disponibles y qué dice la pantalla de consentimiento.
3. Elige los alcances que tu app de verdad usa. Toma los identificadores exactos de los alcances de la referencia de la API; no los deduzcas de los nombres de los endpoints. Separa los alcances de lectura de los de escritura y pide escritura solo donde escribes.
4. Registra tu URI de redirección exactamente como la va a presentar tu servidor, incluidos el esquema, el host, el puerto y la ruta. Una diferencia en la barra final es un intercambio rechazado.
5. Arma el paso de autorización. Tu app manda al usuario a la URL de autorización de la plataforma con el id de cliente, los alcances solicitados, la URI de redirección, el tipo de respuesta y un valor state que generaste y guardaste asociado a la sesión del usuario.
6. Maneja la redirección. Verifica que el state que vuelve coincida con el que guardaste y después descártalo. Saltarse esta verificación es lo que hace que un flujo sea vulnerable a la falsificación de solicitudes.
7. Intercambia el código de autorización por tokens, solo del lado del servidor, enviando el código junto con tu id de cliente, tu secreto de cliente y tu URI de redirección. El código es de un solo uso y vence rápido.
8. Guarda lo que recibes: el token de acceso, el token de renovación, el vencimiento, la lista de alcances otorgados, el identificador de la cuenta o ubicación y el identificador de la agencia cuando aplique. Cifra los tokens en reposo.
9. Para una autorización a nivel de agencia, haz el paso adicional que describe la referencia para obtener un token de una subcuenta específica, y guarda esos tokens por cuenta separados de la autorización principal.
10. Llama a un endpoint de lectura para confirmar que el token funciona y que la cuenta a la que corresponde es la que el usuario quería conectar. Muéstrale el nombre de la cuenta al usuario como confirmación. Así detectas el caso en que alguien autorizó la cuenta equivocada.
11. Implementa la renovación anticipada. Renueva según un calendario, con un margen de seguridad antes del vencimiento, dentro de un bloqueo por instalación, y guarda de inmediato el nuevo token de renovación. Trata la renovación como una escritura en tu base de datos, no como una actualización de caché.
12. Implementa un camino de desconexión. Cuando un usuario quita tu app, o detectas que la autorización ya no existe, borra los tokens guardados, marca la instalación como inactiva y detén los procesos que la estaban usando.
13. Maneja a propósito la ampliación de alcances. Si una función nueva necesita un alcance nuevo, necesitas una autorización nueva de cada instalación existente: los tokens existentes no ganan permisos en silencio. Arma un aviso para volver a dar el consentimiento en lugar de dejar que las llamadas fallen.
14. Verifica el flujo completo contra una cuenta de prueba desde una sesión limpia del navegador: autoriza, confirma la cuenta, fuerza una renovación, revoca desde el lado de la plataforma y confirma que tu app se degrada con elegancia en lugar de quedarse en un ciclo.
15. Monitorea en producción: configura alertas para los intercambios de tokens fallidos, para las fallas de renovación por instalación y para cualquier 403 que indique un alcance que creías tener.

Del navegador a la plataforma

• La solicitud de autorización: identificador de cliente, alcances solicitados, URI de redirección, tipo de respuesta y tu valor opaco state.
• La decisión de consentimiento del dueño de la cuenta y su elección de qué cuenta autorizar.

De la plataforma a tu servidor

• El código de autorización de un solo uso, en tu URI de redirección registrada, junto con tu valor state.
• En el intercambio: un token de acceso, un token de renovación, la duración del token, los alcances otorgados, el tipo de token y el identificador de la cuenta o ubicación que cubre la autorización. Las autorizaciones de agencia también identifican a la cuenta superior.
• En las renovaciones siguientes: un token de acceso nuevo y, por lo común, un token de renovación rotado que reemplaza al anterior.

De tu servidor a la plataforma

• El intercambio del código, con el id de cliente, el secreto de cliente, el código y la URI de redirección.
• Las solicitudes de renovación, con el token de renovación vigente.
• Cada llamada a la API que sigue, con el token de acceso como credencial de tipo bearer.

Lo que no se mueve

• La contraseña del dueño de la cuenta. Tu app nunca la ve, y ese es justamente el punto.
• Cualquier dato fuera de los alcances otorgados: el token es una llave para puertas específicas, no para todo el edificio.
• Cualquier cuenta que la autorización no cubra. Un token de subcuenta no llega a las subcuentas hermanas.
• Los permisos agregados al registro de tu app después de emitida una autorización. Los tokens existentes conservan los alcances con los que se emitieron.
• La información de facturación o del plan de la cuenta que autoriza.

Escenario: una agencia instala tu producto de reportes una sola vez a nivel superior, y después tu producto lee los datos de oportunidades de cinco subcuentas de clientes.

1. El administrador de la agencia hace clic en Conectar en tu producto. Tu servidor genera un state aleatorio, lo guarda asociado a su sesión y lo redirige a la URL de autorización de la plataforma con tu id de cliente, tus alcances de nivel agencia y tu URI de redirección.
2. El administrador ya tiene la sesión iniciada en la plataforma, así que llega directo a la pantalla de consentimiento. Ahí aparecen los permisos que pidió tu app. Los aprueba.
3. La plataforma redirige su navegador a tu URL de retorno registrada con un código de un solo uso y tu valor state.
4. Tu servidor compara el state que volvió con el que guardó, confirma que coinciden y lo borra.
5. Del lado del servidor, intercambias el código por un token de acceso, un token de renovación y un vencimiento, junto con el identificador de la agencia. Cifras y guardas todo como una sola fila de instalación.
6. Listas las subcuentas que cubre la autorización y se las muestras al administrador, que marca los cinco clientes de los que quiere reportes.
7. Para cada subcuenta elegida, haces el paso documentado para obtener un token limitado a esa cuenta, y guardas esos cinco juegos de tokens como filas hijas de la instalación.
8. Tu proceso nocturno arranca, encuentra cada token guardado dentro de su margen de renovación, los renueva bajo un bloqueo por fila y guarda los tokens de renovación rotados antes de hacer cualquier otra cosa.
9. El proceso lee las oportunidades de cada una de las cinco cuentas y arma el reporte. Una cuenta devuelve 403 en un endpoint de pipelines, lo que te dice que ese alcance nunca se otorgó; marcas esa cuenta en la interfaz con un aviso de Reconectar para activar en lugar de publicar en silencio un reporte incompleto.
10. Dos meses después, la agencia quita tu app. La siguiente renovación falla con un error de autorización inválida. Tu manejador marca la instalación como inactiva, detiene su proceso nocturno, borra los tokens guardados y le envía un email al administrador avisando que los reportes se detuvieron, en lugar de reintentar para siempre.

Límites de uso

Los endpoints de tokens tienen límites de uso como cualquier otro, y un error que renueva en cada llamada a la API en lugar de hacerlo con un temporizador va a alcanzar ese límite y tumbar toda tu integración. Renueva una vez por instalación en cada ventana, detrás de un bloqueo. Las llamadas a la API que se hacen con el token resultante cuentan contra el presupuesto normal de API de la cuenta, así que una app de nivel agencia que atiende muchas cuentas debe repartir el trabajo a lo largo de la ventana en lugar de lanzar la sincronización de todas las cuentas a medianoche.

Reintentos e idempotencia

Los códigos de autorización son de un solo uso. Reintentar un intercambio fallido con el mismo código falla, y si el primer intento en realidad funcionó acabas de tirar un par de tokens válido, así que guarda los tokens antes de devolverle una respuesta al navegador. Los tokens de renovación suelen rotar al usarse: si reintentas una renovación con el token anterior después de una rotación exitosa, te van a decir que la autorización es inválida, lo que se ve exactamente igual que una revocación. Haz que la renovación sea atómica y guarda antes de reutilizar.

Trampas al mapear campos

Los identificadores de los alcances son cadenas literales y no son intercambiables con los nombres de los endpoints. Lectura y escritura son alcances distintos para el mismo recurso. Guarda la lista de alcances otorgados y compárala en el código, para que un permiso faltante aparezca como un error claro en tus propios registros y no como un 403 opaco en producción.

Instalaciones duplicadas

Nada impide que la misma cuenta se autorice dos veces: un usuario vuelve a hacer clic en Conectar, o dos miembros del equipo conectan cada uno por su lado. Usa el identificador de la cuenta como clave de tus registros de instalación y trata una segunda autorización como un reemplazo, o vas a correr dos sincronizaciones contra una misma cuenta y crear registros por duplicado.

Pruebas contra producción

Usa un registro de app distinto por entorno, con su propio secreto de cliente y su propia URI de redirección. Apuntar una app de staging a una cuenta de producción es como los datos de prueba terminan en el pipeline de un cliente, y compartir un mismo registro entre entornos significa que no puedes revocar uno sin romper el otro.

Vencimiento y revocación de la autorización

Los tokens de acceso vencen en minutos u horas; los tokens de renovación duran más, pero no son permanentes. Una autorización muere cuando el usuario desconecta la app, cuando un administrador quita la instalación, cuando se cierra la cuenta o cuando la plataforma la invalida. Distingue un 401 (el token venció, renuévalo) de un error de autorización inválida al renovar (la autorización ya no existe, pídele a una persona que vuelva a conectar). Quedarse en un ciclo con el segundo caso es la falla más común en producción.

Lo que se rompe con más frecuencia

• URIs de redirección que dejan de coincidir después de un cambio de dominio o de ruta.
• Un state sin validar, o validado contra una cookie que se perdió en una redirección entre sitios.
• Tokens de renovación rotados que no se guardan, así que la siguiente renovación usa un token muerto.
• El secreto de cliente filtrado en el código del frontend o en un repositorio público.
• Una función nueva lanzada con un alcance nuevo, sin un camino para volver a dar el consentimiento en las instalaciones existentes.
• Tokens de nivel agencia usados donde se necesitaba un token limitado a la cuenta, o al revés.