Integración de SSO en MinDoc mediante Protocolos CAS y SAML

MinDoc es un sistema de gestión de documentación ligero desarrollado en Golang, diseñado para simplificar el despliegue y uso por parte de usuarios comunes. Ofrece una solución eficiente y segura para administrar documentos. Este artículo explica cómo integrar la autenticación Single Sign-On (SSO) en MinDoc utilizando los protocolos CAS y SAML, permitiendo una autenticación unificada para mejorar la seguridad y experiencia del usuario.

Arquitectura Base de SSO en MinDoc

La funcionalidad SSO de MinDoc se basa en el marco del protocolo OAuth2.0, con un diseño modular que soporta múltiples métodos de autenticación. En el directorio utils/auth2/, se proporcionan interfaces y implementaciones completas para integraciones como WeChat Work o DingTalk.

Interfaz Central de Autenticación

MinDoc define una interfaz unificada AuthenticationClient que todas las implemantaciones de autenticación deben seguir:

type AuthenticationClient interface { RetrieveAccessToken(ctx context.Context) (IAccessToken, error) StoreAccessToken(token IAccessToken) GenerateAuthURL(callback string, mobileApp bool) string VerifyCallback(state string) error FetchUserProfile(ctx context.Context, authorizationCode string) (UserProfile, error) }

<p>Esta interfaz, ubicada en <code>utils/auth2/auth2.go</code>, establece métodos esenciales para gestionar tokens, URLs de autorización y datos de usuario.</p>

<h2>Integración del Protocolo CAS</h2>
<h3>Preparación del Entorno</h3>
<p>Antes de iniciar, asegúrese de:</p>

Desplegar un servidor CAS y obtener su dirección URL.
Configurar el acceso de MinDoc al servidor CAS.
Registrar la aplicación MinDoc en el servidor CAS para obtener credenciales.

Modificación del Archivo de Configuración

Agregue las siguientes entradas en el archivo de configuración de MinDoc:

[auth2]
cas_enabled = true
cas_endpoint = https://su-servidor-cas.com/cas
cas_identifier = SU_IDENTIFICADOR_CLIENTE
cas_credential = SU_SECRETO_CLIENTE
cas_callback_url = https://su-mindoc.com/auth2/callback/cas

Implementación del Cliente CAS

Cree una implementación del cliente CAS inspirada en ejemplos existentes como WeChat Work:

// Crear en utils/auth2/cas/cas.go
package cas

import (
    "context"
    "github.com/mindoc-org/mindoc/utils/auth2"
)

type CASAuthenticator struct {
    endpoint     string
    identifier   string
    credential   string
    callbackURL  string
}

func InitAuthenticator(endpoint, identifier, credential string) auth2.AuthenticationClient {
    return &CASAuthenticator{
        endpoint:    endpoint,
        identifier:  identifier,
        credential:  credential,
    }
}

// Implementar todos los métodos de auth2.AuthenticationClient aquí

Guía para Integrar el Protocolo SAML

Visión General de SAML

SAML (Security Assertion Markup Language) es un estándar abierto basado en XML para intercambiar datos de autenticación y autorización. Proporciona mecanismos de federación flexibles, adecuados para integraciones complejas en entornos empresariales.

Pasos de Integración

Paso 1: Obtener Metadatos SAML

Adquiera el archivo XML de metadatos del proveedor de identidad (IdP), que incluye su ID de entidad, URL de SSO y certificados.

Paso 2: Configurar el Cliente SAML en MinDoc

Edite la configuración de MinDoc con los parámetros SAML:

[saml]
enabled = true
idp_metadata_source = https://su-idp.com/metadatos.xml
sp_entity_identifier = https://su-mindoc.com/saml/metadata
assertion_consumer_url = https://su-mindoc.com/auth2/callback/saml
name_id_policy = urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Paso 3: Implementar el Flujo de Autenticación SAML

Las rutas de MinDoc ya están definidas para manejar callbacks de autenticación:

// En routers/router.go
web.Router("/auth2/redirect/:app", &controllers.AccountController{}, "*:Auth2Redirect")
web.Router("/auth2/callback/:app", &controllers.AccountController{}, "*:Auth2Callback")

Implemente la lógica de procesamiento de SAML en controllers/AccountController.go para analizar respuestas y completar la autenticación.

Mapeo de Usuarios y Roles

Después del SSO exitoso, mapee la información del usuario desde SAML o CAS a los roles de MinDoc. El sistema ofrece gestión de permisos configurable desde la interfaz administrativa.

Extienda el método de vinculación en models/Auth2Account.go para incluir el mapeo de atributos:

func (m *ExternalAccount) LinkUserProfile(db orm.Ormer, profile auth2.UserProfile, systemUser *User) error {
    // Lógica de vinculación y asignación de roles
}

Solución de Problemas Comunes

Falla en el Inicio de Sesión SSO

Manifestación: Los usuarios son redirigidos al IdP pero reciben un error al regresar a MinDoc.

Solución:

Verifique que la URL de callback coincida con la registrada en el IdP.
Revise los registros de MinDoc para errores específicos.
Asegure la sincronización de tiempo entre servidores.

Información de Usuario Incompleta

Manifestación: Los datos del usuario están parciales después del inicio de sesión.