SSO Enterprise: SAML, OIDC y SCIM 2.0

Prerrequisitos

• Plan Enterprise (verificado en la ruta /api/auth/sso/[tenantSlug] — otros planes devuelven 403)
• Dominio configurado (white-label opcional pero recomendado)
• Acceso de administrador al IdP (Okta, Azure AD, Google Workspace, Ping, OneLogin, etc.)

SAML 2.0

Configuración

Settings > SSO > Add Provider > SAML

Campos:

• Display name — nombre mostrado en el botón "Sign in with..."
• Metadata XML URL O Metadata XML pegado — proporcionado por el IdP
• SP-initiated o IdP-initiated — Studeia soporta ambos
• Allowed domains — restringe emails (anti-shadow accounts)

Endpoints expuestos

• ACS (Assertion Consumer Service): /api/auth/sso/[tenantSlug]/saml/callback
• SP metadata: /api/institution/sso/metadata

Validación

La SAML Response se valida mediante node-saml:

• Verificación de XML signature (anti-tampering)
• Validación del namespace XML de SAML (anti-XXE)
• Verificaciones NotBefore/NotOnOrAfter
• Restricción de Audience

OIDC

Configuración

Settings > SSO > Add Provider > OIDC

Campos:

• Discovery URL — https://idp.com/.well-known/openid-configuration (auto-fetch)
• Client ID + Client Secret (cifrado AES-256-GCM)
• Scopes — por defecto: openid profile email
• PKCE — siempre activado (método de desafío S256)

Flujo

1. El alumno hace clic en "Sign in with [IdP]" → /api/auth/sso/[tenantSlug]/oidc
2. Redirección al IdP con PKCE challenge + state firmado con HMAC + nonce en Redis (TTL 15min anti-replay)
3. El IdP autentica → callback /api/auth/sso/[tenantSlug]/oidc/callback
4. Studeia valida state + nonce, intercambia el código por tokens (PKCE verifier)
5. Endpoint Userinfo → JIT provisioning (crea User si no existe) → sesión Supabase

SCIM 2.0

14 endpoints RFC 7644

GET    /api/scim/v2/ServiceProviderConfig
GET    /api/scim/v2/ResourceTypes
GET    /api/scim/v2/Schemas

GET    /api/scim/v2/Users           (list, con filter)
POST   /api/scim/v2/Users           (create)
GET    /api/scim/v2/Users/{id}
PUT    /api/scim/v2/Users/{id}      (replace full)
PATCH  /api/scim/v2/Users/{id}      (partial — Microsoft Graph compat)
DELETE /api/scim/v2/Users/{id}      (soft-delete: User.status=suspended)

GET    /api/scim/v2/Groups          (list)
POST   /api/scim/v2/Groups
GET    /api/scim/v2/Groups/{id}
PUT    /api/scim/v2/Groups/{id}
PATCH  /api/scim/v2/Groups/{id}
DELETE /api/scim/v2/Groups/{id}

Configuración en Azure AD (ejemplo)

1. Azure Portal > Enterprise Applications > Studeia > Provisioning
2. Provisioning Mode: Automatic
3. Tenant URL: https://suapp.studeia.com/api/scim/v2
4. Secret Token: generado en Studeia en Settings > SSO > SCIM Token (Bearer, cifrado en la base de datos)
5. Test Connection
6. Mappings: atributos estándar (compatible con Microsoft Graph)
7. Settings > Scope: "Sync only assigned users and groups"
8. Start provisioning

Group → Course mapping

Permite la matrícula automática cuando el IdP agrega un usuario a un grupo:

1. Configure el mapping en Settings > SSO > Groups
2. Para cada SsoGroup, elija el Course de destino
3. Cuando SCIM agrega un miembro al grupo → Studeia crea una Enrollment activa en el curso
4. Cuando lo elimina → cancela la matrícula (status=cancelled)
5. Grupos grandes (>50 miembros): procesamiento mediante BullMQ (cola scim-group-sync), Respuesta 202 + jobId

Seguridad

Tokens

• SCIM Bearer token: cifrado AES-256-GCM en TenantSsoConfig.scimToken — NUNCA en texto plano
• Tokens OAuth (integración con Google Workspace): mismo estándar
• State OAuth: HMAC-SHA256 con OAUTH_STATE_SECRET + nonce Redis (TTL 15min)

JIT provisioning

• allowedDomains valida el email antes de crear el usuario
• Atributos del IdP mapeados mediante SsoAttributeMapping
• Role por defecto configurable (student o teacher)

Auditoría

ScimAuditLog registra:

• Toda operación SCIM (Create/Update/Delete) con timestamp + IP + actor (IdP) + usuario/grupo afectado + payload (redactado)
• AdminAuditLog para cambios en SsoConfig por el administrador institucional

Limitaciones

• LDAP directo (sin SAML/OIDC) no soportado de forma nativa — en el roadmap
• Just-in-time deprovisioning mediante SAML SLO (Single Logout) parcial — se recomienda usar SCIM para un desaprovisionamiento confiable
• Autenticación multifactor delegada al IdP (Studeia no gestiona MFA propio cuando SSO está activo)
• Group nesting (grupos dentro de grupos) soportado parcialmente — se recomienda aplanar la estructura en el IdP

Ver también

• Multi-tenancy
• API pública