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 o Google 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).

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.

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