# Activar OAuth en tu aplicación

Activa el inicio de sesión con UTILIA en una aplicación externa desde el panel: direcciones de vuelta, tipo de aplicación, credenciales y enlaces legales.

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](#quién-puede-autorizar-tu-aplicación).

> **Nota: Qué necesitas**
>
> El aplicativo Integraciones contratado en tu plan y el permiso «Editar aplicaciones externas». Con «Ver aplicaciones externas» puedes consultar la configuración, pero no cambiarla.

## 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](https://os.utilia.ai/docs/developers/oauth/consent-screen).
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.

> **Importante: La clave secreta solo se muestra una vez**
>
> Después no vuelve a salir. Si la pierdes, la única forma de obtener otra es desactivar OAuth y activarlo de nuevo, lo que genera un identificador y una clave nuevos y cierra las sesiones abiertas.

## Quién puede autorizar tu aplicación

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

**Dos formas de crear un cliente OAuth**

### Ficha de tu aplicación (Solo tu organización)

Lo creas aquí, en la ficha de una aplicación de tu organización. Solo lo autorizan personas de tu organización, y trabaja con sus datos.

### Registro dinámico (Cualquier organización)

Lo crea tu código con `POST /api/oauth/register`, sin cuenta. Lo puede autorizar cualquier persona con cuenta en UTILIA OS, y el token trabaja con los datos de la organización de esa persona.

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](https://os.utilia.ai/docs/developers/oauth/oidc-scopes-and-claims#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](https://os.utilia.ai/docs/developers/oauth/scopes-and-resources).

## 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](https://os.utilia.ai/docs/developers/getting-started/rate-limits-and-cors#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](https://os.utilia.ai/docs/developers/oauth/sign-in-nextjs) o [en Flask](https://os.utilia.ai/docs/developers/oauth/sign-in-flask).