Ir al contenido principal

OpenID Connect

Esta sección describe cómo configurar la autenticación OpenID Connect (OIDC) en Sync-in.

Sync-in implementa el flujo de Código de autorización, en línea con las recomendaciones de OAuth 2.0 para aplicaciones web.

La configuración reside en environment.yaml, consulte la sección OIDC.

Requisitos previos​

Antes de habilitar OIDC en Sync-in, se debe crear un cliente OAuth/OIDC en su proveedor de identidad (IdP).
Las etiquetas pueden variar según el proveedor, pero la lógica es similar.

Crear una aplicación (cliente)​

  • El tipo de proveedor debe ser OpenID Connect.
  • El tipo de cliente debe ser Confidential.
  • El tipo de aplicación debe ser Web.
  • El tipo de concesión debe ser Authorization Code.

Esta configuración proporciona el ID del cliente (clientId) y el secreto asociado (clientSecret) que debe copiar en la configuración.

Configurar URI de redireccionamiento​

Los URI de redireccionamiento deben declararse en el IdP.
Permiten que el IdP redirija al usuario nuevamente a Sync-in después de una autenticación exitosa.

Iniciar sesión desde un navegador web​

Para la autenticación de la interfaz de usuario web, declare el siguiente URI:

  • https://DOMINIO:PUERTO/api/auth/oidc/callback
información

Este URI corresponde al parámetro de configuración redirectUri.
Debe terminar en /api/auth/oidc/callback.

Iniciar sesión desde aplicaciones de escritorio​

Las aplicaciones de escritorio utilizan el navegador predeterminado del sistema para realizar la autenticación.
Después de iniciar sesión, el navegador redirige al usuario a un URI local para pasar el resultado de la autenticación a la aplicación.

Para permitir esto, declare los siguientes URI locales:

  • http://127.0.0.1:49152/oidc/callback
  • http://127.0.0.1:49153/oidc/callback
  • http://127.0.0.1:49154/oidc/callback

Este enfoque mejora la compatibilidad con los IdP y coincide con los mecanismos de autenticación ya implementados en entornos empresariales (SSO, MFA, políticas de seguridad, etc.).

información

Cuando se utiliza OIDC, se espera que el proveedor de identidad aplique MFA. Sync-in no añade un desafío de 2FA local después del callback de OIDC. La 2FA de Sync-in sigue pudiendo configurarse desde el perfil del usuario durante una sesión OIDC; los flujos para habilitarla, restablecerla y deshabilitarla verifican la contraseña local de Sync-in.

Configuración​

Ejemplo mínimo:

auth:
  provider: oidc
  oidc:
    issuerUrl: 'https://auth.example.com/realms/my-realm'
    clientId: 'OIDCClientId'
    clientSecret: 'OIDCClientSecret'
    redirectUri: 'https://sync-in.domain.com/api/auth/oidc/callback'

⚠️ redirectUri debe coincidir exactamente con el URI declarado en el IdP.

Flujo de autenticación​

Hay dos métodos de autenticación disponibles en la pantalla de inicio de sesión de Sync-in.

Autenticación local​

  • Cuentas de invitado, cuentas de administrador y cuentas con contraseñas de aplicación pueden iniciar sesión con su identificador y contraseña.
  • Para esta ruta de inicio de sesión, se aplica la 2FA local de Sync-in cuando está habilitada para el usuario.
  • Otros usuarios pueden utilizar su contraseña local solo si:
    • options.enablePasswordAuth está habilitado;
    • conocen su contraseña local de Sync-in.
  • Esta configuración preserva el acceso administrativo de emergencia sin deshabilitar la autenticación OIDC.

Se recomienda configurar y mantener disponible una contraseña local de Sync-in para las cuentas de administrador, a fin de poder utilizarla como acceso de emergencia.

De forma predeterminada, la autenticación mediante contraseña local para los usuarios estándar de OIDC está deshabilitada. Habilite options.enablePasswordAuth solo si desea permitir expresamente esta alternativa.

Los usuarios creados mediante OIDC comienzan con una contraseña interna aleatoria. Mientras están autenticados mediante OIDC, pueden definir una contraseña local conocida desde su perfil. Esa contraseña podrá utilizarse para la autenticación local cuando esté habilitada y para la comprobación adicional con contraseña cuando no haya ningún secreto TOTP activo. También es necesaria para habilitar, restablecer o deshabilitar la 2FA de Sync-in desde una sesión OIDC en el navegador.

Contraseñas de aplicación​

Generar y revocar contraseñas de aplicación requiere la verificación reforzada habitual de Sync-in: TOTP cuando está habilitado o, en caso contrario, la confirmación mediante la contraseña local.

Autenticación OpenID Connect (OIDC)​

  • El usuario inicia la sesión mediante el botón OIDC.
  • Se le redirige al IdP para autenticarse.
  • El proveedor de identidad aplica MFA, cuando es necesario, durante este paso.
  • Después de la validación, el usuario es redirigido automáticamente a Sync-in.
  • Sync-in recupera información del usuario y sincroniza la cuenta local.
  • Si no existe una cuenta local y autoCreateUser está habilitado, se crea una cuenta local con una contraseña aleatoria.
  • El rol de administrador se aplica automáticamente si está configurado.
  • La cuota de almacenamiento se sincroniza desde options.storageQuotaClaim cuando el perfil OIDC proporciona un valor válido en bytes. Un claim ausente o un claim con valor 0 establece almacenamiento ilimitado.

El perfil OIDC debe proporcionar una dirección de correo electrónico. Las cuentas nuevas inicializan su identificador local a partir de preferred_username y, si este claim no está presente, a partir de la parte local del correo electrónico. El identificador se asigna una sola vez y no cambia en los inicios de sesión OIDC posteriores.

Vinculación y sincronización de cuentas​

Sync-in utiliza el claim sub del token de ID validado como identidad externa estable y lo almacena en la cuenta de usuario local. Durante el inicio de sesión, las cuentas se resuelven en este orden:

  1. Coincidencia entre la identidad externa almacenada y el claim sub del token de ID.
  2. Búsqueda por correo electrónico únicamente para las cuentas existentes que aún no tienen una identidad externa.
  3. Registro del sub sin modificar en esa cuenta después de la primera coincidencia de compatibilidad correcta.
  4. Creación de una cuenta local cuando no existe ninguna coincidencia y autoCreateUser está habilitado.

Una vez vinculada una cuenta, los cambios de correo electrónico en el IdP ya no interrumpen el inicio de sesión, porque Sync-in resuelve el usuario mediante sub. Si el identificador derivado ya está en uso durante la creación automática de la cuenta, Sync-in añade un sufijo determinista derivado de sub; el valor sub sin procesar no se expone en el identificador.

Para los usuarios existentes, Sync-in puede sincronizar el correo electrónico, el nombre, el apellido, el rol, la cuota de almacenamiento y el avatar desde OIDC. El identificador local, la contraseña y los permisos no se sincronizan después de la creación de la cuenta.

Roles de administrador​

Si se establece options.adminRoleOrGroup, Sync-in comprueba si este valor está presente en los claims groups o roles devueltos por el IdP. El rol de administrador se concede si se encuentra una coincidencia.

Si no se establece options.adminRoleOrGroup, las cuentas de administrador existentes mantienen su rol y no pueden ser degradadas a través de OIDC.

Disponibilidad y errores​

Los errores de configuración o de acceso al IdP provocan que falle la autenticación.
Si el IdP no está disponible, solo es posible la autenticación local (consulte Flujo de autenticación).

Seguridad​

Sync-in utiliza automáticamente el mecanismo PKCE (Proof Key for Code Exchange) cuando el proveedor de identidad lo admite y está habilitado en la configuración mediante el parámetro security.supportPKCE (habilitado de forma predeterminada).

PKCE fortalece el flujo del Código de autorización agregando prueba criptográfica durante el intercambio del código de autorización, mejorando la seguridad para los clientes web y nativos.

Esta implementación se alinea con las recomendaciones de seguridad actuales de OAuth.

información

La compatibilidad con PKCE puede impedir la autenticación con ciertos proveedores de identidad como PocketID, en cuyo caso se puede desactivar.

La opción security.tokenEndpointAuthMethod admite client_secret_basic y client_secret_post. Utilice el valor esperado por su IdP; client_secret_basic es el valor predeterminado para clientes web confidenciales. El campo clientSecret es obligatorio en la configuración de Sync-in.

Las solicitudes de token y descubrimiento de OIDC requieren HTTPS de forma predeterminada. La opción security.allowInsecureRequests solo debe habilitarse para desarrollo local o proveedores heredados confiables.

La opción security.requireVerifiedEmail está habilitada de forma predeterminada. Sync-in exige que el claim de UserInfo email_verified sea exactamente true antes de vincular la cuenta o sincronizar el perfil. Deshabilítela solo si su IdP no proporciona un claim fiable de correo electrónico verificado.

Cuando options.autoSyncAvatar está habilitado, Sync-in puede sincronizar el avatar del usuario a partir del claim OIDC picture. Las descargas de avatares desde rangos de IP privados o internos permanecen bloqueadas, salvo que security.allowPrivateIpAvatarDownload esté habilitado explícitamente.