OIDC / Inicio de sesión único

SnapOtter admite OpenID Connect (OIDC) para el inicio de sesión único. Los usuarios pueden iniciar sesión con un proveedor de identidad externo como Keycloak, Authentik, Google o Microsoft Entra ID en lugar de (o junto a) la autenticación local con usuario y contraseña.

Consulta también

SAML SSO | Aprovisionamiento SCIM | Usuarios, roles y permisos

Inicio rápido

Añade estas variables de entorno a tu docker-compose.yml:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

La URI de redirección para tu proveedor es siempre:

${EXTERNAL_URL}/api/auth/oidc/callback

Por ejemplo, si EXTERNAL_URL es https://photos.example.com, configura la URI de redirección de tu proveedor como https://photos.example.com/api/auth/oidc/callback.

Referencia de configuración

Variable	Predeterminado	Descripción
OIDC_ENABLED	false	Habilita el inicio de sesión OIDC. Aparece un botón "Iniciar sesión con SSO" en la página de inicio de sesión.
OIDC_ISSUER_URL		URL del emisor del proveedor. Debe admitir OIDC Discovery (/.well-known/openid-configuration).
OIDC_CLIENT_ID		ID de cliente OAuth registrado en tu proveedor.
OIDC_CLIENT_SECRET		Secreto de cliente OAuth.
OIDC_SCOPES	openid profile email	Lista de scopes a solicitar separados por espacios.
OIDC_AUTO_CREATE_USERS	true	Crea automáticamente una cuenta de usuario local en el primer inicio de sesión OIDC.
OIDC_DEFAULT_ROLE	user	Rol asignado a los usuarios OIDC creados automáticamente. Uno de admin, editor o user.
OIDC_AUTO_LINK_USERS	false	Vincula una identidad OIDC a un usuario local existente si la dirección de correo electrónico coincide.
OIDC_PROVIDER_NAME		Nombre visible que se muestra en el botón de inicio de sesión (p. ej. "Keycloak", "Google"). Si está vacío, el botón muestra "SSO".
OIDC_CLOCK_TOLERANCE	30	Tolerancia de desfase de reloj en segundos para la validación de tokens.
OIDC_USERNAME_CLAIM	preferred_username	Claim del token de ID usado como nombre de usuario para las cuentas nuevas.
EXTERNAL_URL		La URL pública donde SnapOtter es accesible. Necesaria para que OIDC construya la URI de redirección correcta.
COOKIE_SECRET	autogenerado	Secreto para firmar las cookies de sesión. Defínelo explícitamente al ejecutar varias réplicas.

Guías de proveedores

Keycloak

1. Crea un realm nuevo (o usa uno existente).
2. Ve a Clients y crea un cliente nuevo:
   • Client ID: snapotter
   • Client authentication: On (confidencial)
   • Authentication flow: Standard flow (Authorization Code)
3. En la pestaña Settings del cliente, define Valid redirect URIs con tu URL de callback (p. ej. https://photos.example.com/api/auth/oidc/callback).
4. Copia el Client secret de la pestaña Credentials.
5. Define OIDC_ISSUER_URL como https://keycloak.example.com/realms/your-realm.

Authentik

1. En la interfaz de administración, ve a Applications > Providers y crea un nuevo OAuth2/OpenID Provider.
   • Client type: Confidential
   • Redirect URIs: Tu URL de callback
   • Signing key: Selecciona una clave existente o crea una
2. Crea una Application y vincúlala al proveedor.
3. Copia el Client ID y el Client Secret de los ajustes del proveedor.
4. Define OIDC_ISSUER_URL como https://authentik.example.com/application/o/snapotter/ (la barra final importa).

Google

1. Ve a la Google Cloud Console.
2. Crea un proyecto (o selecciona uno existente).
3. Navega a APIs & Services > OAuth consent screen y configúralo.
4. Ve a APIs & Services > Credentials y crea un OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: Tu URL de callback
5. Copia el Client ID y el Client secret.
6. Define OIDC_ISSUER_URL como https://accounts.google.com.
7. Define OIDC_USERNAME_CLAIM como email (Google no proporciona preferred_username).

Azure AD / Entra ID

1. En el portal de Azure, ve a Microsoft Entra ID > App registrations > New registration.
2. Llama a la aplicación "SnapOtter". En Redirect URI, selecciona la plataforma Web e introduce tu URL de callback (p. ej. https://photos.example.com/api/auth/oidc/callback). No elijas Single-page application: SnapOtter se autentica con un secreto de cliente, que Entra ID rechaza en los registros de tipo SPA.
3. Copia el Application (client) ID y el Directory (tenant) ID de la página Overview.
4. Ve a Certificates & secrets > New client secret y copia enseguida el Value del secreto. Solo se muestra una vez, y el Secret ID adyacente no es el secreto.
5. Define OIDC_ISSUER_URL como https://login.microsoftonline.com/<tenant-id>/v2.0, usando el Directory (tenant) ID del paso 3.
6. Deja OIDC_USERNAME_CLAIM en su valor predeterminado. Entra ID proporciona preferred_username, así que aquí no hace falta la sustitución por email de la guía de Google.

Usa siempre el ID de tu tenant en la URL del emisor, no common ni organizations. Esos endpoints multi-tenant anuncian la plantilla literal {tenantid} como su emisor, lo que hace fallar la validación de OIDC Discovery.

WARNING

El claim preferred_username de Entra ID sigue el nombre principal de usuario, que cambia cuando un usuario es renombrado o trasladado a otro tenant. SnapOtter lee el claim una sola vez, en el primer inicio de sesión, así que después la cuenta conserva su nombre de usuario original. El inicio de sesión sigue funcionando en cualquier caso: los usuarios que regresan se identifican por el subject estable del token, no por el nombre de usuario.

Cambiar a Entra ID no desactiva el inicio de sesión con contraseña. Consulta Desactivar el inicio de sesión local.

Okta y otros proveedores

Cualquier proveedor que admita OIDC Discovery funciona de la misma manera: crea un cliente web confidencial con tu URL de callback y apunta OIDC_ISSUER_URL al emisor. Para Okta, crea una aplicación con el método de inicio de sesión OIDC - OpenID Connect y el tipo Web Application, y usa tu dominio de Okta como emisor (p. ej. https://your-company.okta.com).

SnapOtter no asigna los grupos del proveedor de identidad a roles. Los usuarios SSO nuevos reciben OIDC_DEFAULT_ROLE, los administradores cambian los roles en Ajustes > Usuarios, y solicitar claims de grupos mediante OIDC_SCOPES no tiene ningún efecto.

Aprovisionamiento de usuarios

Creación automática

Cuando OIDC_AUTO_CREATE_USERS es true (el valor predeterminado), se crea una cuenta de usuario local la primera vez que alguien inicia sesión mediante OIDC. El nombre de usuario se toma del claim especificado por OIDC_USERNAME_CLAIM, y el rol se establece en OIDC_DEFAULT_ROLE.

Si se produce una colisión de nombre de usuario, se añade un sufijo numérico (p. ej. jane pasa a ser jane_2).

Vinculación automática

Cuando OIDC_AUTO_LINK_USERS es true, SnapOtter vincula una identidad OIDC a una cuenta local existente si las direcciones de correo electrónico coinciden. Esto resulta útil cuando tienes cuentas de usuario creadas de antemano y quieres que empiecen a usar SSO sin perder sus datos.

WARNING

Habilita la vinculación automática solo si confías en que tu proveedor OIDC verifica las direcciones de correo electrónico. Un correo electrónico no verificado podría permitir que alguien se apropie de la cuenta de otro usuario.

Desactivar el inicio de sesión local

OIDC no desactiva el inicio de sesión local con usuario y contraseña. Ambos métodos siguen disponibles. Los administradores aún pueden iniciar sesión con credenciales locales si el proveedor OIDC es inaccesible.

Certificados autofirmados

Si tu proveedor OIDC usa un certificado autofirmado o de una CA privada, monta el paquete de CA en el contenedor y apunta NODE_EXTRA_CA_CERTS a él:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

No definas NODE_TLS_REJECT_UNAUTHORIZED=0. Esto desactiva toda la verificación TLS y supone un riesgo de seguridad.

Emisores con http sin cifrar

SnapOtter solo acepta una URL de emisor http:// cuando EXTERNAL_URL también es http sin cifrar, algo adecuado para una configuración de prueba local o en LAN. En ese caso, el descubrimiento, el intercambio del código de inicio de sesión y los tokens viajan por la red sin cifrar, así que SnapOtter registra una advertencia al arrancar con el host del emisor. Con un EXTERNAL_URL https://, un emisor http se rechaza al iniciar sesión y la advertencia de arranque lo indica. En ambos casos, la solución es servir tu proveedor de identidad por https.

Solución de problemas

Discrepancia de la URI de redirección

El error más común. Comprueba estas diferencias entre lo que espera tu proveedor y lo que envía SnapOtter:

• http frente a https: el esquema debe coincidir exactamente
• Barra final: algunos proveedores son estrictos con esto
• Número de puerto: incluye el puerto si no es estándar
• Ruta: debe ser /api/auth/oidc/callback

Revisa dos veces EXTERNAL_URL. Debe coincidir con la URL que los usuarios escriben en su navegador.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

El proveedor OIDC usa un certificado en el que Node.js no confía. Consulta Certificados autofirmados más arriba.

Errores de desfase de reloj

Si el reloj de tu servidor y el del proveedor OIDC están desincronizados, la validación de tokens puede fallar. Aumenta OIDC_CLOCK_TOLERANCE (el valor predeterminado es 30 segundos). Una solución mejor es ejecutar NTP en ambas máquinas.

"Proveedor OIDC inaccesible"

SnapOtter obtiene el documento de discovery del proveedor al arrancar y durante el inicio de sesión. Comprueba:

• La resolución DNS desde dentro del contenedor Docker (docker exec snapotter nslookup auth.example.com)
• Las reglas del firewall entre el contenedor y el proveedor
• El valor de OIDC_ISSUER_URL: debe ser accesible desde el servidor, no solo desde tu navegador

Claims ausentes

Si los nombres de usuario o los correos electrónicos están vacíos tras el inicio de sesión, es posible que tu proveedor no devuelva los claims esperados. Verifica:

• Los scopes configurados en OIDC_SCOPES incluyen profile y email
• El proveedor está configurado para incluir el claim especificado en OIDC_USERNAME_CLAIM en el token de ID
• Algunos proveedores requieren configuración explícita de mapper/scope para liberar los claims