OAuth2 / OIDC — conectar un servicio a Omniscol

Lo que hace Omniscol como servidor OAuth2

Un servicio externo — un agente de IA, un conector, un tablero de control — se convierte en un cliente declarado en su cuenta; un usuario de la escuela aprueba su acceso mediante una pantalla de consentimiento; el servicio recibe entonces un token de acceso de vida corta, cuyo alcance está limitado a los scopes concedidos y a los derechos del usuario.

Este mecanismo es distinto del SSO de usuario descrito en OIDC / SSO, donde Omniscol es, por el contrario, cliente de su proveedor de identidad para conectar a sus usuarios. Aquí, Omniscol está del lado servidor: son los servicios los que se conectan a él.

Dos integraciones de Omniscol consumen este servidor:

• MCP — la autenticación estándar de un agente de IA pasa por este servidor OAuth2 (véase MCP — conectar un agente de IA externo);
• OneRoster — el productor OneRoster se autentica mediante un token OAuth2 de máquina a máquina emitido por este mismo servidor (véase OneRoster).

Cualquier otro servicio conforme a OAuth2 / OIDC puede conectarse de la misma manera.

Descubrimiento y puntos de acceso del protocolo

Omniscol publica sus metadatos de descubrimiento en las direcciones estándar .well-known, servidas en la raíz del dominio de su cuenta (por ejemplo https://su-escuela.omniscol.com). Un cliente conforme encuentra allí por sí solo todos los puntos de acceso, sin configuración manual:

• /.well-known/oauth-authorization-server — metadatos del servidor de autorización (RFC 8414);
• /.well-known/openid-configuration — metadatos OpenID Connect (contenido idéntico al anterior);
• /.well-known/jwks.json — claves públicas de verificación (JWKS), que permiten verificar la firma de los id_token;
• /.well-known/oauth-protected-resource — metadatos de recurso protegido (RFC 9728).

Estos metadatos anuncian los puntos de acceso del protocolo:

• /oauth/authorize — solicitud de autorización (pantalla de inicio de sesión y luego de consentimiento);
• /oauth/token — intercambio del código por un token, y renovación;
• /oauth/register — registro dinámico de clientes (RFC 7591);
• /oidc/userinfo — información sobre el usuario conectado (OIDC);
• /oauth/revoke — revocación de un token (RFC 7009).

Estos puntos de acceso del protocolo son públicos: no están reservados a las cuentas Premium y no hay que abrirlos manualmente. Solo la pantalla de gestión de clientes descrita más abajo corresponde a Premium.

Los flujos de autorización

Omniscol admite tres flujos OAuth2:

• Código de autorización con PKCE — el flujo por defecto para un servicio que actúa en nombre de un usuario. El servicio redirige al usuario hacia /oauth/authorize; tras el inicio de sesión y el consentimiento, Omniscol devuelve un código de autorización (válido 5 minutos) que el servicio intercambia en /oauth/token. El método PKCE admitido es S256, y el único response_type aceptado es code.
• Renovación (refresh_token) — para prolongar un acceso delegado sin volver a pasar por el consentimiento.
• Client credentials — flujo de máquina a máquina, sin usuario, utilizado en particular por los consumidores OneRoster. El cliente se autentica directamente y recibe un token de acceso.

En el intercambio, el servidor emite un token de acceso (Bearer, válido 1 hora) y, para los flujos de usuario, un token de renovación (válido 30 días). Cuando se solicita el scope openid, se emite también un id_token OIDC firmado; su firma se verifica mediante /.well-known/jwks.json. El flujo client_credentials solo emite un token de acceso, sin renovación ni id_token.

El token de acceso se presenta después en el encabezado HTTP Authorization: Bearer <token>. En cada llamada, Omniscol verifica su firma, comprueba que el cliente sigue activo, que el usuario sigue existiendo y posee el rol requerido, y que los scopes del token cubren efectivamente el punto de acceso llamado — de lo contrario la llamada es rechazada.

Los scopes y el consentimiento

Los scopes que usted gestiona en un cliente son:

• read:basic — lectura de los horarios, tableros de control y consultas (módulos Página de inicio, Horario, Tablero de control, Gestión horarios);
• read:user — lectura de la lista de usuarios;
• write:data — escritura sobre esos mismos módulos de consulta;
• admin — acceso de administración (módulos Administración, Gestión de ausencias, Gestión horarios).

El servidor conoce también los scopes OIDC (openid, email, profile) y los scopes OneRoster de solo lectura (prefijo imsglobal.org). Estos últimos son privilegiados: un cliente no puede autoasignárselos mediante el registro dinámico; deben ser aprovisionados por un administrador en la ficha del cliente.

El scope efectivamente concedido es la intersección de lo que el cliente solicita y de lo que le está registrado: un cliente nunca obtiene más que lo que figura en su ficha. Durante el flujo de usuario, la pantalla de consentimiento (/oauth/consent) muestra el nombre y el logotipo del servicio solicitante, así como la lista legible de los scopes solicitados, con los botones Aceptar y Rechazar. Aprobar emite el código de autorización y devuelve al usuario al servicio; rechazar lo devuelve con un error access_denied.

El registro dinámico de clientes

El punto de acceso /oauth/register implementa el registro dinámico (Dynamic Client Registration, RFC 7591): un servicio conforme puede declararse por sí solo como cliente, sin intervención manual previa. Es lo que permite a un agente MCP configurarse a partir únicamente de la URL del servidor.

El registro dinámico no puede asignarse un scope privilegiado (los scopes OneRoster): estos se descartan silenciosamente, y si no queda ningún scope válido, se concede read:basic por defecto. Los scopes privilegiados quedan reservados a un aprovisionamiento por un administrador.

La pantalla de gestión de clientes OAuth2

En las cuentas Premium, usted administra los clientes desde Administración → Importar, exportar, sección OAuth2, con el botón OAuth2. El acceso exige primero la contraseña de administrador — una confirmación adicional antes de abrir la pantalla.

La pantalla enumera los clientes registrados y, para cada uno, muestra su estado (activo / inactivo), su nombre, sus scopes, sus contactos y sus URIs (sitio, logotipo, URIs de redirección). Usted puede:

• Registrar un cliente — indique el nombre, un software_id opcional, los scopes, los contactos, el sitio, el logotipo y las URIs de redirección. En la creación, Omniscol muestra una sola vez el client_id y el client_secret.
• Modificar un cliente — solo son modificables campos seguros: nombre, scopes, contactos, sitio y logotipo. Las URIs de redirección, el software_id y el secreto no se modifican aquí.
• Activar o desactivar un cliente — un cliente desactivado ve sus tokens rechazados desde la siguiente llamada.
• Eliminar un cliente — la eliminación es definitiva.

El secreto del cliente

El client_secret se muestra una sola vez, en el registro. Omniscol conserva a su lado únicamente una huella del secreto, nunca el secreto en claro: no puede volver a mostrarse ni recuperarse después. Cópielo de inmediato en un gestor de secretos.

El client_id, en cambio, es determinista: deriva del nombre de la cuenta, del nombre del cliente y de una huella de sus metadatos técnicos. Dos registros estrictamente idénticos recaen así sobre el mismo identificador.

Renovar el secreto (rotación)

La rotación del secreto existe: emite un nuevo secreto, conserva únicamente la nueva huella, y devuelve este nuevo secreto una sola vez. Se realiza mediante el punto de acceso de gestión del registro dinámico (/oauth/register/<client_id>/rotation) y supone presentar el token de registro entregado al cliente durante su registro dinámico. Por tanto, no se activa desde la pantalla de gestión anterior, que no manipula ese token.

OAuth2 o clave de API: cuál elegir

Omniscol ofrece dos mecanismos de acceso de máquina, con modelos de confianza diferentes:

• OAuth2 (esta página) — un tercero registrado obtiene, tras el consentimiento de un usuario, un token de vida corta (1 h), limitado a los scopes concedidos, renovable y revocable (al desactivar el cliente). El flujo client_credentials cubre además la máquina a máquina sin usuario. Es el modo adaptado a un servicio de terceros identificado, a MCP y a OneRoster.
• Clave de API (véase API de Omniscol) — un token autónomo firmado por el servidor, que incorpora una lista de puntos de acceso autorizados y que usted mismo entrega al sistema externo: sin tercero registrado, sin pantalla de consentimiento, sin renovación. Es una delegación, por parte del administrador, de sus propios derechos a un sistema que controla.

En resumen: la clave de API conviene cuando usted mismo entrega un acceso a un sistema que controla; OAuth2 conviene cuando un servicio de terceros identificado debe obtener un acceso delegado, con scopes y revocable, o cuando el protocolo lo impone (MCP, OneRoster).