Activar OAuth en tu aplicación

Para que las personas de tu organización entren en tu aplicación con su cuenta de UTILIA OS, activa OAuth en la ficha de su aplicación externa. El cliente que nace así es de tu organización: solo lo autorizan sus personas. El panel te da el identificador y la clave secreta, y te deja fijar a dónde vuelve la persona tras autorizar y qué enlaces legales ve.

Si tu aplicación es para personas de cualquier organización, el camino es el registro dinámico (POST /api/oauth/register), y la diferencia importa: está en Quién puede autorizar tu aplicación.

Activar OAuth

1. Abre la aplicación externa

   Abre la aplicación en Ajustes, Creadas por tu empresa. Si no tienes ninguna, créala con Nueva aplicación. Si no ves Creadas por tu empresa en Ajustes, pide a un administrador que revise el plan (Integraciones) y tus permisos.

2. Entra en Configuración › Inicio de sesión

   En la ficha de la aplicación, pulsa Configuración y, en la fila de debajo, Inicio de sesión. Verás el bloque «Inicio de sesión con UTILIA OS». Activa el interruptor Activar OAuth.

3. Rellena «Cómo se conecta»

   • Direcciones de vuelta: la dirección de tu aplicación a la que UTILIA OS devuelve a la persona tras autorizar, por ejemplo https://tu-app.com/callback. Escríbela y pulsa Añadir; puedes añadir varias (una por entorno). Hace falta al menos una.
   • Tipo de aplicación: Con servidor propio (recomendado) si tu aplicación tiene un servidor que guarda la clave secreta, o Sin servidor (web o móvil) si se ejecuta entera en el navegador o en el móvil y no puede guardar secretos.

4. Opcional: lo que ve la persona al autorizar

   Términos de servicio, Política de privacidad y Correo de contacto. Los dos enlaces aparecen en el pie de la pantalla de consentimiento.

5. Pulsa «Activar OAuth» y guarda las credenciales

   Aparecen el Identificador público (tu client_id) y la Clave secreta (tu client_secret), cada uno con su botón Copiar. Cópialos y marca He guardado las credenciales para continuar.

Quién puede autorizar tu aplicación

Un cliente OAuth puede nacer de dos formas, y cada una decide quién puede autorizarlo:

El registro dinámico es el que usan los asistentes de IA y las herramientas que se conectan a muchas organizaciones. Si eliges ese camino y tu aplicación no es para todo el mundo, filtra tú quién entra: el id_token y userinfo traen org_id, la organización de la persona. Admite solo las organizaciones o los sub que quieras y rechaza los demás; nunca decidas por el correo, que solo es único dentro de una organización. Lo cuenta Lo que los claims no dicen.

Si una persona de otra organización intenta autorizar un cliente de la ficha de tu aplicación, UTILIA OS lo rechaza (unauthorized_client) en una página propia que le explica que la aplicación es de otra empresa, y la persona no vuelve a tu aplicación.

Un cliente del registro dinámico también puede tener clave secreta, si la pide al registrarse, pero no tiene ficha: no se renueva ni se gestiona desde el panel.

Qué es cada dato

• Identificador público (client_id): dice a UTILIA OS qué aplicación pide acceso. No es secreto; empieza por utilia_.
• Clave secreta (client_secret): demuestra que quien canjea el código es de verdad tu aplicación. Va solo en tu servidor, en variables de entorno o en un gestor de secretos; nunca en el código que llega al navegador ni en un repositorio.
• Direcciones de vuelta: UTILIA OS solo devuelve a la persona a una dirección de esta lista, y la redirect_uri de cada petición tiene que coincidir carácter por carácter, incluidos el protocolo, el puerto y la barra final.
• Tipo de aplicación: con servidor propio, tu aplicación se identifica con la clave secreta en la cabecera Authorization: Basic (client_secret_basic); sin servidor, se identifica solo con PKCE (none).

En el panel no se eligen scopes: tu aplicación los pide en cada autorización, en el parámetro scope. Para un inicio de sesión basta con openid profile email. El catálogo está en Scopes y recursos.

Cambiar la configuración

Con OAuth activo, la pantalla muestra un resumen (sesiones abiertas, tipo y fecha de activación) y estos bloques, cada uno con su botón Editar:

• Credenciales: el identificador público. La clave secreta ya no se puede ver.
• Direcciones de vuelta: añade o quita direcciones. Sin ninguna, nadie puede completar el inicio de sesión.
• Lo que ve el usuario: los enlaces legales y el correo de contacto.
• Tipo de aplicación: con o sin servidor propio.
• Desactivar OAuth: elimina el cliente y cierra en el acto todas las sesiones abiertas con él. No se puede deshacer.

Si tu aplicación de navegador llama a UTILIA OS directamente, añade su dominio en Configuración › Ajustes de la aplicación, pestaña Avanzado, bloque Dominios autorizados; si no, el navegador bloqueará las peticiones por CORS. Ten en cuenta que con dominios autorizados la clave de API de esa aplicación pasa a contar como publicada en páginas web y solo admite los permisos del navegador: lo explica Claves dentro de una página web.

Buenas prácticas

• Usa https en todas las direcciones de vuelta de producción.
• Crea una aplicación por entorno (desarrollo, pruebas, producción) en lugar de compartir credenciales.
• Pide solo los scopes que necesites.
• Si crees que la clave secreta se ha filtrado, desactiva OAuth y actívalo de nuevo cuanto antes, y actualiza tu aplicación con las credenciales nuevas.

Siguiente paso: Iniciar sesión con UTILIA en Next.js o en Flask.