API de SSO Empresarial

El SSO Empresarial (Single Sign-On) permite a los miembros de una organización autenticarse usando el proveedor de identidad existente de su empresa en lugar de un nombre de usuario y contraseña. Auris admite los protocolos SAML 2.0 y OIDC, respaldados internamente por el broker de IdP de Keycloak.

El flujo de SSO funciona de la siguiente manera:

1. Un administrador crea una conexión SSO para una organización, proporcionando la configuración de su IdP (metadatos SAML o URL de descubrimiento OIDC).
2. El administrador añade y verifica uno o más dominios de correo electrónico (p. ej., acme-corp.com) mediante registros DNS TXT.
3. Una vez activada la conexión, los usuarios con un correo electrónico en un dominio verificado son redirigidos automáticamente al IdP cuando intentan iniciar sesión.
4. En el primer inicio de sesión SSO, Auris realiza el aprovisionamiento Just-In-Time (JIT) — creando la cuenta de usuario, vinculándola a la organización y emitiendo tokens de Auris — todo de forma transparente.

Todos los endpoints de SSO para administradores requieren la cabecera x-tenant y un Bearer token válido.

Conexiones SSO

Parámetros de consulta

Respuesta exitosa

{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "name": "Acme Corporate IdP",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml-abc123",
      "domains": ["acme-corp.com", "acme.io"],
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-02-01T14:30:00Z"
    }
  ]
}

Estados de conexión SSO:

Configuración SAML 2.0

Para SSO basado en SAML, proporciona los metadatos del Proveedor de Identidad. Puedes indicar una metadataUrl (recomendado — Auris la obtendrá y analizará automáticamente) o proporcionar los campos individuales de forma manual.

Cuerpo de la solicitud — SAML con URL de metadatos

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Cuerpo de la solicitud — SAML con configuración manual

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----"
  }
}

Configuración OIDC

Para SSO basado en OIDC, proporciona la URL de descubrimiento y las credenciales del cliente emitidas por el IdP.

Cuerpo de la solicitud — OIDC

{
  "type": "oidc",
  "name": "Acme OIDC Provider",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client-id",
    "clientSecret": "auris-sp-client-secret"
  }
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Códigos de error

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "ACTIVE",
    "keycloakIdpAlias": "acme-saml-abc123",
    "config": {
      "entityId": "https://idp.acme-corp.com",
      "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpD..."
    },
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "spEntityId": "https://api.altovar.net",
    "domains": ["acme-corp.com"],
    "createdAt": "2025-01-20T09:00:00Z",
    "updatedAt": "2025-02-01T14:30:00Z"
  }
}

Cuerpo de la solicitud

{
  "name": "Acme Corporate SAML (Updated)",
  "config": {
    "ssoUrl": "https://new-idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEnD..."
  }
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML (Updated)",
    "status": "ACTIVE",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Respuesta exitosa

{
  "ok": true,
  "data": { "deleted": true }
}

Activar y Desactivar

Solicitud: No se requiere cuerpo.

Respuesta exitosa

{
  "ok": true,
  "data": {
    "activated": true,
    "status": "ACTIVE"
  }
}

Códigos de error

Solicitud: No se requiere cuerpo.

Respuesta exitosa

{
  "ok": true,
  "data": {
    "deactivated": true,
    "status": "DISABLED"
  }
}

Verificación de Dominio

La verificación de dominio demuestra que controlas un dominio de correo electrónico antes de habilitar la redirección automática basada en SSO para ese dominio. La verificación se realiza mediante un registro DNS (TXT o CNAME). Una vez verificado un dominio, cualquier usuario que inicie sesión con una dirección de correo en ese dominio es redirigido automáticamente al proveedor SSO de la organización.

Respuesta exitosa

{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z",
      "createdAt": "2025-01-20T10:00:00Z"
    },
    {
      "id": "dom_def456",
      "domain": "acme.io",
      "status": "PENDING",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-ghi789jkl012",
      "verifiedAt": null,
      "createdAt": "2025-02-10T08:00:00Z"
    }
  ]
}

Estados de verificación de dominio:

Cuerpo de la solicitud

{
  "domain": "acme-corp.com"
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "dom_ghi789",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-mno345pqr678",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-mno345pqr678"
    }
  }
}

Añade el registro DNS que se muestra en dnsRecord en tu registrador de dominios y luego llama al endpoint de verificación para confirmar.

Códigos de error

Solicitud: No se requiere cuerpo.

Respuesta exitosa — verificado

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Respuesta exitosa — aún no propagado

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "PENDING",
    "message": "TXT record not found yet. DNS propagation can take up to 48 hours."
  }
}

Respuesta exitosa — fallido

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "FAILED",
    "message": "DNS lookup completed but the verification token was not found in any TXT records."
  }
}

Endpoints SSO Públicos

Estos endpoints son utilizados por la página de inicio de sesión alojada de Auris y el SDK para ejecutar el flujo SSO. No requieren autenticación.

Cuerpo de la solicitud

{
  "email": "[email protected]"
}

Respuesta — SSO disponible

{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/acme-saml-abc123"
  }
}

Respuesta — sin SSO

{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

La respuesta siempre es 200 OK independientemente de si el dominio tiene SSO configurado, para evitar la fuga de información sobre qué organizaciones usan SSO.

Este endpoint es una redirección del navegador, no una llamada de API. El flujo típico:

1. El cliente detecta SSO mediante POST /api/auth/sso/detect
2. El cliente redirige el navegador a la loginUrl de la respuesta de detección
3. Auris redirige a la página de inicio de sesión del IdP
4. El usuario se autentica en el IdP
5. El IdP redirige de vuelta al endpoint de callback de Auris
6. Auris emite tokens y redirige a la URL de callback de la aplicación

Parámetros de consulta

Este endpoint es llamado por el Proveedor de Identidad, no por tu aplicación directamente.

Aprovisionamiento JIT (Just-In-Time)

Cuando un usuario se autentica mediante SSO por primera vez y aún no tiene cuenta en Auris, Auris automáticamente:

1. Crea una nueva cuenta de usuario usando los atributos de la aserción SSO (correo electrónico, nombre, apellido)
2. Vincula al usuario a la organización propietaria de la conexión SSO
3. Asigna el rol de miembro predeterminado (MEMBER)
4. Emite los tokens de acceso y refresh estándar de Auris

En los inicios de sesión posteriores, el registro de usuario existente se localiza por correo electrónico y los tokens se emiten directamente.

Redirección en caso de éxito

Tras una autenticación exitosa, el usuario es redirigido a la URL de callback registrada de la aplicación con un código de autorización:

https://app.tudominio.com/callback?code=auth_code_xxx&state=original_state

El código de autorización puede entonces canjearse por tokens usando el endpoint estándar POST /api/auth/token con grant_type=authorization_code.

Gestión de errores

Si la aserción SSO es inválida o el IdP devuelve un error, el usuario es redirigido al callback de la aplicación con parámetros de error:

https://app.tudominio.com/callback?error=sso_failed&error_description=SAML+assertion+validation+failed&state=original_state

Referencia de Permisos

Notas de Implementación

Broker de IdP de Keycloak: Internamente, Auris crea y gestiona configuraciones de Proveedor de Identidad de Keycloak. Cada conexión SSO corresponde a un IdP de Keycloak con un alias único. El realm de Keycloak para la conexión está determinado por el campo keycloakRealm en el registro de la conexión. Esto es un detalle de implementación — tu aplicación solo interactúa con la API de Auris.

Rotación de Certificados: Para las conexiones SAML, actualiza el campo certificate en la configuración de la conexión cuando el IdP rote su certificado de firma. Auris no detecta automáticamente los cambios de certificado. Durante la rotación, puedes mantener temporalmente los certificados nuevo y antiguo actualizando la conexión antes de que el antiguo expire.

Caché del Descubrimiento OIDC: Al usar OIDC, Auris almacena en caché el documento de descubrimiento. Si el IdP cambia sus endpoints, actualiza la discoveryUrl o espera a que la caché expire (aproximadamente 1 hora).

Relacionado

• Guía de SSO Empresarial — Configura conexiones SAML 2.0 y OIDC
• Single Sign-On — Tutorial de integración SSO
• SSO Empresarial — Configura conexiones SSO desde la Consola
• API de Organizaciones — Endpoints de organizaciones a las que pertenecen las conexiones SSO