Configurar Azure AD para SSO de EKB

Esta guía explica cómo configurar Azure Active Directory (Entra ID) como el Proveedor de Identidad (IdP) para SAML SSO en su instancia on-premise de EKB. Cubre las configuraciones SAML que debe ingresar en Azure AD, cómo obtener sus metadatos de federación y cómo registrar el dominio en EKB para completar la integración.

Nota

El flujo SAML genérico de EKB funciona con Azure AD / Entra ID de forma nativa. Si aún no lo ha hecho, lea la Vista General de SAML SSO para comprender cómo funciona la integración antes de comenzar.

Prerrequisitos

• Tiene acceso de administrador a su tenant de Azure AD / Entra ID.
• Tiene acceso de Super Admin a su instancia on-premise de EKB.
• Conoce el nombre de dominio completamente calificado (FQDN) del host de backend de EKB (por ejemplo, ek-api.corp.acme.com).
• Conoce el dominio de correo electrónico para el que desea habilitar SSO (por ejemplo, acme.com).

Parte 1 — Configurar Azure AD

Crear una Nueva Aplicación Empresarial en Azure AD

1. Crear una nueva aplicación empresarial

   En el portal de Azure, navegue a Azure Active Directory → Enterprise applications y haga clic en New application. Seleccione Create your own application, dé un nombre (por ejemplo, EK SSO) y elija Integrate any other application you don't find in the gallery (Non-gallery).

2. Abrir la configuración SSO

   Una vez creada la aplicación, navegue a Manage → Single sign-on y seleccione SAML como método de inicio de sesión.

3. Ingresar la Configuración Básica de SAML

   En la sección Basic SAML Configuration, ingrese los siguientes valores:

   Campo	Valor
   Identifier (Entity ID)	https://<su-FQDN>/backend/user/generic/sso/saml/acs/admin
   Reply URL (ACS URL)	https://<su-FQDN>/backend/user/generic/sso/saml/acs/admin
   Sign-on URL	Deje vacío
   Relay State	default
   Logout URL	Deje vacío

4. Configurar atributos y reclamaciones

   En la sección Attributes & Claims, confirme o agregue los siguientes mapeos:

   Atributos	Valor
   givenname	user.givenname
   surname	user.surname
   emailaddress	user.mail
   name	user.userprincipalname
   DisplayName	user.displayname
   email	user.mail
   Unique User Identifier (Name ID)	user.userprincipalname

Parte 2 — Obtener los Metadatos de Azure AD

Una vez configurada la aplicación de Azure AD, obtenga la URL de metadatos de federación:

1. Ir a la sección de Certificados SAML

   En su aplicación, navegue a Manage → Single sign-on → SAML Certificates.

2. Copiar la URL de Metadatos de Federación de la Aplicación

   Encuentre y copie la App Federation Metadata URL.

   La ruta es:

   Manage > Single sign-on > SAML Certificates > App Federation Metadata URL

   Necesitará esta URL en la Parte 3.
   

Parte 3 — Registrar el Dominio en EKB

Envíe una solicitud POST al endpoint de registro de dominio:

curl -X POST "https://<su-host-de-backend>/backend/sso/add_new_configuration" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SU_API_KEY" \
  -H "X-API-SECRET: SU_API_SECRET" \
  -d '{
    "enterprise_id": "acme.com",
    "provider": "azure",
    "metadata_url": "https://su-url-de-metadatos-de-federacion-de-azure",
    "backend_root_url": "<su-host-de-backend>/backend"
  }'

Campos Requeridos

Campo	Descripción
enterprise_id	El dominio de correo electrónico de sus usuarios (por ejemplo, acme.com).
provider	"azure"
metadata_url	La App Federation Metadata URL de la Parte 2.
backend_root_url	(Opcional) Requerido solo en configuraciones de proxy para asegurar el enrutamiento correcto.

Autenticación

El endpoint requiere su API Key y Secret de EKB pasados como encabezados X-API-KEY y X-API-SECRET.

En caso de éxito, se crea un registro en la tabla sso_providers en el backend.

Parte 4 — Configurar el Frontend

Una vez registrado el dominio, establezca la variable de entorno del frontend y reinicie el servicio del frontend.

1. Abrir el archivo de entorno del frontend

   En su servidor de implementación on-premise, abra onprem-deployment/.env.web.

2. Agregar la variable de entorno

   Agregue la siguiente línea, reemplazando acme.com con su dominio de correo electrónico real:

   VITE_SSO_ENTERPRISE_ID=acme.com

3. Reiniciar los servicios del frontend

   docker compose -f docker-compose down
   docker compose -f docker-compose up -d

Probar la Integración

Inicie sesión en EKB con un usuario real @<dominio> para confirmar que el flujo funciona de principio a fin. Si el usuario se autentica exitosamente pero se le deniega el acceso, verifique su configuración de Controles de Acceso SAML — consulte la guía Controles de Acceso SAML y Asignación Automatizada de Equipos/Proyectos de EKB.