Endpoint de Metadatos SP

Referencia técnica del endpoint de metadatos del Proveedor de Servicio de EKB utilizado durante la configuración de SAML SSO.

El backend de EKB expone un endpoint público de metadatos del Proveedor de Servicio (SP) SAML que los Proveedores de Identidad (IdPs) pueden consumir para establecer automáticamente confianza con la aplicación. Esto elimina la necesidad de que los administradores intercambien manualmente detalles de configuración SP durante la configuración de SSO.

​

Endpoint

GET /saml/well-known/sp-metadata

Propiedad	Valor
Autenticación	Ninguna (accesible públicamente)
Content-Type	application/samlmetadata+xml
Content-Disposition	inline; filename="sp_metadata.xml"

​

Propósito

Al configurar SAML SSO entre un IdP (por ejemplo, Okta, Azure AD, OneLogin) y EKB, el IdP necesita conocer varias cosas sobre el SP:

• Entity ID — un identificador único para el SP.
• URL del Assertion Consumer Service (ACS) — donde el IdP debe enviar por POST las respuestas SAML.
• Formato NameID soportado — cómo debe identificar el IdP al usuario.
• Certificado de firma (si aplica) — la clave pública que el IdP puede usar para verificar AuthnRequests firmados.

En lugar de requerir que un administrador copie y pegue cada uno de estos valores individualmente, este endpoint los proporciona todos en un solo documento XML de metadatos SAML 2.0 compatible con estándares. Los administradores pueden dirigir su IdP directamente a esta URL o descargar el XML y subirlo al IdP.

Para instrucciones paso a paso sobre cómo usar este endpoint durante la configuración, consulte la Guía de Configuración de Metadatos SSO.

​

Formato de Respuesta

El endpoint retorna un documento EntityDescriptor SAML 2.0. A continuación se muestra un ejemplo representativo:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://api.example.com/user/generic/sso/saml/acs/admin">
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIC...certificado-en-base64...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                Location="https://api.example.com/user/generic/sso/saml/acs/admin"
                                index="0"
                                isDefault="true" />
  </md:SPSSODescriptor>
</md:EntityDescriptor>

​

Componentes Garantizados vs. Opcionales

​

Garantizados (siempre presentes)

Elemento / Atributo XML	Descripción
<md:EntityDescriptor entityID="...">	El Entity ID del SP. Se predetermina a la URL ACS a menos que CUSTOM_ENTITY_ID_FOR_GENERIC_SSO esté establecido, en cuyo caso se usa ese valor.
<md:SPSSODescriptor>	Contenedor para toda la información del descriptor SSO del SP. Siempre incluye WantAssertionsSigned="true" y protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol".
Atributo AuthnRequestsSigned	Siempre presente en SPSSODescriptor. Se establece a "true" cuando se configura un certificado de firma SP, "false" de lo contrario.
<md:NameIDFormat>	Siempre urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. EKB espera que el IdP proporcione la dirección de correo electrónico del usuario como NameID.
<md:AssertionConsumerService>	El endpoint ACS. Siempre usa enlazamiento HTTP-POST, índice 0 y isDefault="true". El Location se deriva de la URL raíz del backend de EKB: {BACKEND_ROOT_URL}/user/generic/sso/saml/acs/admin.

​

Opcionales (condicionalmente presentes)

Elemento / Atributo XML	Condición	Descripción
<md:KeyDescriptor use="signing">	Solo presente cuando el servidor está configurado con un certificado y clave de firma SP válidos a través de SAML_SP_CERT_FILE y SAML_SP_KEY_FILE.	Contiene el certificado de firma X.509 del SP para que el IdP pueda verificar AuthnRequests firmados. Cuando está ausente, las AuthnRequests se envían sin firmar y AuthnRequestsSigned es "false".

​

Variables de Entorno Relacionadas

Variable	Efecto en los Metadatos
CUSTOM_ENTITY_ID_FOR_GENERIC_SSO	Si está establecida, anula el entityID predeterminado (que es la URL ACS).
SAML_SP_CERT_FILE	Ruta al certificado X.509 codificado en PEM del SP. Cuando se establece junto con SAML_SP_KEY_FILE, el bloque KeyDescriptor se incluye y AuthnRequestsSigned se convierte en "true".
SAML_SP_KEY_FILE	Ruta a la clave privada codificada en PEM del SP. Requerida junto con SAML_SP_CERT_FILE para que se habilite la firma de solicitudes.