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 su ficha de aplicación externa. 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. Es la alternativa al registro dinámico (POST /api/oauth/register) cuando quieres clave secreta, enlaces legales o dominios autorizados para llamar desde el navegador.

Activar OAuth

1. Abre la aplicación externa

   Ve a Gestión de proyectos › Integraciones, necesitas entrar con tu cuenta y abre la aplicación, o crea una con Nueva aplicación. Si no ves Integraciones en el menú, pide a un administrador que revise el plan y tus permisos.

2. Entra en la pestaña OAuth

   En la ficha de la aplicación, pulsa OAuth. 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.

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 pestaña 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 la pestaña Ajustes de la aplicación, apartado Avanzado › Dominios autorizados; si no, el navegador bloqueará las peticiones por CORS.

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.