SSO SAML 2.0

Autenticación federada mediante SAML 2.0. Permite a los usuarios de una organización acceder al admin de OmniBuy usando sus credenciales corporativas.

Flujo de autenticación

1. Usuario → GET /sso/saml/login?tenant_id=xxx
2. OmniBuy → Redirect al IdP (Identity Provider)
3. Usuario → Se autentica en el IdP
4. IdP → POST /sso/saml/callback?tenant_id=xxx (con SAMLResponse)
5. OmniBuy → Valida assertion, crea sesión, retorna JWT

Configuración

POST /api/v1/admin/sso

{
  "provider": "okta",
  "idp_metadata_xml": "<EntityDescriptor>...</EntityDescriptor>",
  "entity_id": "https://app.omnibuy.net/sso/saml/metadata",
  "acs_url": "https://app.omnibuy.net/sso/saml/callback",
  "attribute_email": "email",
  "attribute_role": "role",
  "default_role": "staff"
}

Campo	Tipo	Requerido	Descripción
provider	string	Sí	Proveedor: okta, azure, google, onelogin, custom
idp_metadata_xml	string	Sí	XML de metadata del IdP (contiene certificados y endpoints)
entity_id	string	Sí	Entity ID de OmniBuy (SP)
acs_url	string	Sí	Assertion Consumer Service URL
attribute_email	string	No	Nombre del atributo SAML para el email (default: email)
attribute_role	string	No	Nombre del atributo SAML para el rol
default_role	string	No	Rol por defecto si el IdP no envía rol: owner, admin, staff, viewer

Endpoints

Obtener configuración

GET /api/v1/admin/sso

Eliminar configuración

DELETE /api/v1/admin/sso

Iniciar login SSO (público)

GET /sso/saml/login?tenant_id=uuid

Redirige al usuario al IdP para autenticación.

Callback SAML (público)

POST /sso/saml/callback?tenant_id=uuid

Recibe la respuesta SAML del IdP (form-encoded: SAMLResponse, RelayState).

Respuesta exitosa 200 OK:

{
  "data": {
    "email": "[email protected]",
    "name": "Juan Pérez",
    "role": "admin",
    "tenant_id": "uuid"
  }
}

Proveedores soportados

Provider	Configuración
okta	Crear SAML App en Okta Admin Console
azure	Enterprise Application en Azure AD
google	SAML App en Google Admin Console
onelogin	SAML Custom Connector
custom	Cualquier IdP compatible con SAML 2.0

Errores

Código	HTTP	Descripción
SSO_NOT_CONFIGURED	404	SSO no configurado para este tenant
SSO_DISABLED	403	SSO configurado pero deshabilitado
INVALID_METADATA	422	XML de metadata del IdP inválido
INVALID_ASSERTION	401	Assertion SAML inválida o expirada
EMAIL_NOT_FOUND	422	Email no encontrado en la assertion