Problema

En entornos self‑hosted es habitual confiar en que una funcionalidad crítica, como SAML o OpenID Connect (OIDC), esté disponible sin coste adicional. Cuando un proveedor decide mover esa funcionalidad a una edición de pago, la actualización automática rompe la integración de SSO y obliga a los usuarios a migrar a planes más caros o a buscar alternativas. El patrón se repite en varias aplicaciones: una versión gratuita incluye SSO, una actualización posterior la elimina o la restringe, y el administrador se queda sin acceso de autenticación única. El problema no es aislado; cualquier stack que dependa de SSO está expuesto a regresiones de características cuando los proyectos cambian su modelo de negocio o su hoja de ruta.

Causa

  1. Cambios de licencia o modelo de negocio – Los mantenedores pueden decidir monetizar SAML/OIDC para financiar desarrollo. La decisión suele anunciarse en notas de versión o en la página de precios, pero a menudo pasa desapercibida entre los usuarios que actualizan automáticamente.

  2. Actualizaciones automáticas sin revisión – Herramientas como docker compose pull, apt upgrade o helm upgrade descargan la última imagen o paquete sin validar si la funcionalidad SSO sigue presente. Cuando la nueva versión elimina SSO, el servicio vuelve a iniciar sin la capacidad de autenticación externa.

  3. Falta de pruebas de integración en el pipeline – Los pipelines CI/CD suelen validar que el contenedor arranca, pero rara vez comprueban que los endpoints de SAML/OIDC siguen respondiendo o que la configuración sigue siendo válida.

  4. Documentación dispersa – La información sobre la disponibilidad de SSO se encuentra en la página de precios, en la documentación de la versión o en el changelog. Si el equipo de operaciones no rastrea todas esas fuentes, el cambio se pierde.

Solución

Adoptar un proceso de auditoría y mitigación que pueda aplicarse a cualquier aplicación self‑hosted que dependa de SSO.

1. Inventario centralizado de dependencias SSO

Crea un archivo sso-audit.yaml que liste cada servicio, la versión actual y la URL de la página de precios o del changelog donde se verifica la disponibilidad de SAML/OIDC.

services:
  - name: grafana
    image: grafana/grafana:10.2.0
    sso: true
    doc_url: https://grafana.com/docs/grafana/latest/enterprise/saml/
  - name: metabase
    image: metabase/metabase:v0.49.7
    sso: true
    doc_url: https://www.metabase.com/docs/latest/enterprise/saml
  # añadir más servicios aquí

Mantén este archivo bajo control de versiones. Cada vez que actualices un contenedor, revisa la URL y confirma que la columna sso sigue siendo true. Si la página indica “Enterprise only”, cambia el flag a false y planifica una acción correctiva.

2. Bloqueo de versiones (version pinning)

En lugar de seguir la última etiqueta, fija la versión que sabes que incluye SSO. Usa la sintaxis de tu orquestador para bloquear la etiqueta.

docker pull grafana/grafana:10.2.0
docker tag grafana/grafana:10.2.0 grafana/grafana:stable-sso
docker-compose up -d grafana

En docker-compose.yml:

services:
  grafana:
    image: grafana/grafana:stable-sso
    restart: unless-stopped

Cuando necesites actualizar, crea una rama de pruebas, actualiza la etiqueta y vuelve a validar el sso-audit.yaml.

3. Pruebas de integración de SSO en CI/CD

Añade un job que intente iniciar una autenticación SAML/OIDC contra el endpoint del servicio. Un ejemplo con curl y xmlstarlet para validar la metadata de SAML:

#!/usr/bin/env bash
METADATA_URL="https://sso.example.com/saml/metadata"
SERVICE_URL="http://localhost:3000/api/auth/saml/metadata"

curl -s "$SERVICE_URL" -o /tmp/service-metadata.xml
curl -s "$METADATA_URL" -o /tmp/expected-metadata.xml

if diff -q /tmp/service-metadata.xml /tmp/expected-metadata.xml >/dev/null; then
  echo "SAML metadata coincide"
else
  echo "SAML metadata no coincide – posible regresión"
  exit 1
fi

Integra este script en tu pipeline; si falla, el despliegue se detiene y el equipo revisa la causa antes de promover la versión.

4. Estrategia de fallback

Mantén una configuración alternativa que permita autenticarse con credenciales locales mientras se resuelve el problema de SSO. En la mayoría de los proyectos, la autenticación local está disponible sin coste. Documenta los pasos para habilitarla y automatiza su activación mediante variables de entorno.

Ejemplo para Grafana (grafana.ini):

[auth.generic_oauth]
enabled = false

[auth.basic]
enabled = true

Al detectar que sso-audit.yaml marca sso: false, ejecuta un script que reescribe la configuración y reinicia el contenedor.

5. Monitoreo de cambios en la documentación oficial

Utiliza un RSS o un webhook de GitHub para recibir notificaciones de cambios en los archivos CHANGELOG.md o en la sección de precios. Un pequeño cron job puede descargar la página y buscar palabras clave como “SAML”, “OIDC”, “Enterprise only”.

#!/usr/bin/env bash
URL="https://grafana.com/docs/grafana/latest/enterprise/saml/"
TMP=$(mktemp)

curl -s "$URL" > "$TMP"
if grep -q "Enterprise" "$TMP"; then
  echo "Posible restricción de SAML en Grafana"
  # actualizar sso-audit.yaml o disparar alerta
fi
rm "$TMP"

Cuándo aplicar esta solución

  • Entornos críticos donde la pérdida de SSO implica interrupciones de servicio o exposición de credenciales.
  • Stacks con múltiples servicios que comparten un IdP (Keycloak, Azure AD, Okta, etc.).
  • Políticas de actualización automática que no incluyen revisión manual de notas de versión.
  • Equipos pequeños que no disponen de un proceso formal de gestión de cambios.

No es necesario cuando:

  • El servicio no depende de SSO y usa exclusivamente autenticación local.
  • La aplicación está bloqueada a una versión específica por razones de compatibilidad y no se planea actualizar.

Código

# Paso 1: clonar el inventario
git clone https://github.com/mi-org/sso-audit.git
cd sso-audit

# Paso 2: validar que todas las versiones actuales siguen ofreciendo SSO
python3 scripts/validate_sso.py

# Paso 3: si alguna falla, aplicar fallback y bloquear la versión
./scripts/apply_fallback.sh grafana
docker pull grafana/grafana:10.2.0
docker tag grafana/grafana:10.2.0 grafana/grafana:stable-sso
docker-compose up -d grafana

Verificación

  1. Comprobar la respuesta del endpoint de metadata – Ejecuta el script de integración; debe devolver “SAML metadata coincide”.
  2. Revisar logs de autenticación – En Grafana, busca login en los logs; la ausencia de errores de SAML indica que la funcionalidad está activa.
  3. Validar la variable de fallback – Asegúrate de que la autenticación básica está habilitada (curl -u admin:admin http://localhost:3000/api/auth/login debe responder 200).
  4. Confirmar que el archivo sso-audit.yaml refleja el estado actual – git diff no debe mostrar cambios inesperados después de la verificación.

Notas adicionales

  • Gestión de licencias: si decides migrar a una edición Enterprise, automatiza la inserción de la licencia en el contenedor mediante un secret de Docker o un ConfigMap de Kubernetes. Evita almacenar la clave en texto plano.
  • Impacto de la caché del IdP: después de un cambio de configuración, algunos IdP mantienen metadata en caché durante 24 h. Forzar una recarga (p.ej., reiniciar el servicio IdP) acelera la detección de problemas.
  • Comunicación con proveedores: abre un ticket o una issue en el repositorio del proyecto cuando detectes una regresión. La mayoría de los mantenedores agradecen la evidencia documental (URL de precios, captura de pantalla) y pueden revertir la decisión o ofrecer un plan gratuito para la comunidad.

Con este proceso, cualquier administrador de sistemas puede anticipar la pérdida de SAML/OIDC, mantener la continuidad del SSO y evitar sorpresas de facturación inesperada al actualizar sus aplicaciones self‑hosted.