Saltar a contenido

SAML2

SAML2 (Security Assertion Markup Language 2.0) es un estándar para autenticación y autorización basada en web. Permite a los usuarios iniciar sesión en aplicaciones basándose en su sesión en otro contexto, típicamente un proveedor de identidad (IdP) centralizado.

La configuración de autenticación SAML2 le permite configurar SAML2 para su instancia de Clarive como alternativa al modo de autenticación interna.

Parámetros de Configuración

A continuación se muestran los parámetros de configuración más relevantes que se pueden establecer en Clarive y sus significados:

saml2:
    issuer: 'miappclarive'
    idp_cert: '...'  # cadena de certificado en línea
    idp_cert: '/RUTA/A/idp.pem'  # ruta del certificado al archivo .pem
    entry_point: 'https://idp.ejemplo.com/login'  # url de login del proveedor SAML2
    header: 'SAMLResponse' # ya sea un encabezado o parámetro
    attribute_statement_path: '//saml:Assertion/saml:AttributeStatement'
    attribute_node: './/saml:Attribute'
    attribute_key: 'email'
    active: true

Warning

La mera existencia de la clave saml2 es suficiente para poner Clarive en modo de login SAML2. Asegúrese de nunca dejar el saml2: colgando en su archivo [config].yml, de lo contrario intentará continuamente iniciar sesión usando parámetros/encabezados SAML2.

Parámetros Requeridos

Estos parámetros son requeridos:

  • idp_cert: Una cadena o ruta que representa el certificado del proveedor de identidad (IdP). Puede ser una cadena de una sola línea comenzando como MIIC8DCCAdigAwI... o una cadena multilínea comenzando con -----BEGIN CERTIFICATE--- Si es una ruta a un archivo válido, debe ser el certificado del proveedor de identidad en formato .pem. Este certificado se usa para validar las respuestas SAML.

  • issuer: El nombre del servicio a los ojos del IdP. El issuer es su ID de tenant de Clarive, "el proveedor de servicio" en términos de IdP. Esto está establecido en un valor predeterminado de clarive-saml, pero debe coincidir con el nombre que se haya definido en el IdP o establecer clarive-saml en el IdP.

Parámetros Recomendados

Estos parámetros no son obligatorios, pero se recomiendan ya que cada instalación debe tenerlos

  • entry_point: La URL de la página de inicio de sesión del proveedor de identidad. Este es el endpoint donde el usuario será redirigido solicitando una respuesta de callback a Clarive.

  • service_url: Esta es la URL de punto de entrada principal para la aplicación Clarive, el "servicio" en términos SAML2. Se usa en la solicitud de inicio de sesión XML al IdP. Si no está definida, se usará el parámetro url de [config].yml en su lugar. No está garantizado que sea usado por el IdP, algunos proveedores pueden sobrescribir el valor con su URL definida internamente para el servicio.

  • logout_url: Esta es la URL a la que el usuario será redirigido cuando el usuario presione la opción "Logout" en el menú de usuario en Clarive. Si el valor de logout_url está vacío '' o indefinido, el usuario será llevado a la pantalla de inicio de sesión de Clarive.

  • private_key: un certificado RSA multilínea comenzando con --- BEGIN PRIVATE KEY... o la clave privada como una cadena de una sola línea que comienza como MIIC8DCCAdigAwIBAgIQa... o una ruta a un archivo que contiene la clave privada RSA /mi/ruta/a/key.pem. La clave privada se usa para firmar las solicitudes de autenticación o cierre de sesión que van al IdP.

  • attribute_key: El nombre del atributo que se usará como clave para la identidad del usuario. Por defecto es id que apunta al NameID en el sujeto SAML. El XPath del atributo id se puede configurar usando la configuración XPath opcional nameid_path (ver abajo). Si un AttributeStatement está presente, el attribute_key podría ser cualquiera de los atributos adicionales enviados por el IdP como 'email' o 'username' o cualquier nodo presente en el AttributeStatement.

entry_point

Si el parámetro entry_point no está establecido, Clarive permitirá a los usuarios iniciar sesión usando contraseñas internas, si está establecido Y un IdP para redirigir a los usuarios a Clarive con un encabezado SAMLResponse para SSO.

attribute_key

Clarive verificará el valor de attribute_key contra las columnas email y username en su base de datos interna. El usuario debe existir para que funcione (Clarive no creará usuarios desde SAML2) con campos username o email coincidentes. El valor del atributo es sensible a mayúsculas y minúsculas. Asegúrese de que su base de datos de Clarive contenga valores que coincidan con los datos provenientes del IdP en el SAMLResponse.

Parámetros Opcionales

  • header: El encabezado HTTP (o parámetro de consulta HTTP) donde se encontrará la respuesta SAML. Por defecto es SAMLResponse.

  • nameid_path: El XPath al nodo donde obtener el SignedInfo del SAMLResponse. Valor de ejemplo: //ds:SignedInfo

  • attribute_statement_path: El XPath a la declaración de atributos SAML dentro de la aserción SAML. Esta ruta se usa para localizar la declaración de atributos en la respuesta SAML. Por ejemplo //saml:Assertion/saml:AttributeStatement.

  • attribute_path: El XPath al nombre de cada uno de los atributos SAML dentro del nodo de declaración de atributos SAML. Por ejemplo //saml:Attribute.

  • attribute_value_path: El XPath a los nodos de atributos individuales dentro de la declaración de atributos. Esta ruta se usa para localizar el valor del atributo en la respuesta SAML para cada par de nombres.

  • digest_path: El XPath al nodo donde obtener el DigestValue del SAMLResponse para la verificación de digest. La verificación de digest es opcional por defecto, lo que significa que no detendrá la validación SAML2 de ocurrir. Valor de ejemplo //saml:Assertion//ds:DigestValue

  • signed_info_path: El XPath al nodo donde obtener el nodo SignedInfo del SAMLResponse. Valor de ejemplo: //ds:SignedInfo

  • signature_value_path: El XPath al nodo donde obtener el nodo SignatureValue del SAMLResponse. Valor de ejemplo: //ds:SignatureValue

  • active: Un valor booleano opcional que habilita o deshabilita la autenticación SAML2. Establezca en true para activar la autenticación SAML2, o false para desactivarla.

Ejemplos

Aquí hay un ejemplo de cómo podría verse la configuración SAML2 en su archivo YAML de configuración CLARIVE_BASE/[config].yml. Este ejemplo tiene el certificado público del IdP en línea:

saml2:
    entry_point: 'https://mi.servidor.idp/login'
    attribute_key: username
    idp_cert: |  # cadena de certificado de ejemplo
        -----BEGIN CERTIFICATE-----
        MIIDkjCCAnoCCQD8pdU4gpgmMjANBgkqhkiG9w0BAQsFADCBiTELMAkGA1UEBhMC
        ZXMxDzANBgNVBAgMBm1hZHJpZDEPMA0GA1UEBwwGbWFkcmlkMRAwDgYDVQQKDAdj
        bGFyaXZlMRAwDgYDVQQLDAdjbGFyaXZlMRAwDgYDVQQDDAdjbGFyaXZlMSIwIAYJ
        KoZIhvcNAQkBFhNjbGFyaXZlQGNsYXJpdmUuY29tMCAXDTI0MDYwNDEzNTkwN1oY
        DzMwMjMxMDA2MTM1OTA3WjCBiTELMAkGA1UEBhMCZXMxDzANBgNVBAgMBm1hZHJp
        ZDEPMA0GA1UEBwwGbWFkcmlkMRAwDgYDVQQKDAdjbGFyaXZlMRAwDgYDVQQLDAdj
        bGFyaXZlMRAwDgYDVQQDDAdjbGFyaXZlMSIwIAYJKoZIhvcNAQkBFhNjbGFyaXZl
        QGNsYXJpdmUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwWtd
        lzrXVx70nLuXffxwKsD3bkf7/4sGdrL4bf/suq1QZZGA8T4ch9HSAlMp6eQkSqm8
        /HbBycqHtDYoxJMT/Jq0Sdjqp4qb/w+Y2WJhkK5bDHOsvqdx89oINjaRL/92Y1jZ
        P0B2T6MoFdji12CUiChXi6r07wYqy3lNQvNCHg786ZwEYOyGpmXMWyGRtciKYEM6
        f/Cv26YCBklcDZt+t6Sp+Fzr97J56shYpVE3G40IYp5MpgXooL4iPqqFqgnTn12G
        8/xKCAcc2HB035+rY/2sFiHspYtCRBfMZyT1hgviDYdtPUMvCKmYyMC97AngkGR3
        WX513xFAqaVrJ/gdpQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQCMOxH70ZEQhQqV
        /D0C5F5x4EVfepiIbV3GU01/qBt84pIE36plaYB8kAowgTc/7tqNoS9/EgmWAFgU
        kn+u32q4uwnkN9pqI6K1LgHrSMRICB8oqHUlbzxUbnzf+35r9FhWbe6f4vE7HI6t
        ItFq5VMvqDZfGl9GhmagX1IjUN2srls3cficWKB9hNwN0BXP88UA7M9wPwUd0F5a
        uZq7nG+yhufKCWVRBBpTIv3G96naHpHfvPLcCZIX5mq3qx3P+9FwvPX+x8gCLHqe
        1UjTvp7z+sEgzs5g11LMhZVapsEKUhbJ3fWZgBL+Epo5aQz7yUvxc0K3wbTaWBv0
        tfbwdDPL
        -----END CERTIFICATE-----

Asegúrese de que la cadena del certificado (idp_cert) o la ruta del certificado esté correctamente proporcionada, y que la URL de entry_point sea precisa para su IdP.

Alternativamente, puede usar una ruta completamente calificada al certificado:

saml2:
    issuer: 'miappclarive'
    entry_point: 'https://mi.servidor.idp/login'
    idp_cert: '/opt/certs/idp_cert.pem'

Reiniciar después de cambiar la configuración

Cualquier cambio en la configuración YAML [config].yml requiere un inicio completo.

Actividad y Eventos SAML2

Clarive emite 2 eventos que registran cualquier intento exitoso y fallido de inicio de sesión con SAML2 activado:

  • event.auth.saml_ok - un usuario ha iniciado sesión en Clarive exitosamente

  • event.auth.saml_failed - se registró un intento fallido de inicio de sesión en modo SAML2.

En caso de un inicio de sesión exitoso, se envían los siguientes atributos como variables de evento (los user_attributes pueden variar según su configuración de SAMLResponse del IdP):

type: saml2
user_attributes:
  email: [email protected]
  firstName: janedoe
  id: 605a07f56226774ca510bdc4af920522c4442661b8857c89e28b7f56cadbb8eb
  lastName: Doe
username: janedoe

Verificar los logs

También verifique los logs del servidor web de Clarive para mensajes de error e inicie Clarive en modo debug cla web-start -d para depurar posibles problemas SAML2.

Personalizar Rutas XML en la Respuesta SAML

Clarive permite al administrador configurar los XPaths usados para analizar el SAMLResponse. Esta es una característica avanzada y típicamente no requerida.

Si está a punto de configurar attribute_statement_path, attribute_path, attribute_value_path y otros parámetros XPath, es esencial entender cómo escribir las rutas XML correctas (XPaths) para coincidir con la estructura del XML SAMLResponse para su instalación.

Los parámetros XPath disponibles son:

nameid_path
attribute_statement_path
attribute_path
attribute_value_path
digest_path
signed_info_path
signature_value_path

Comprender Rutas XML (XPaths)

XPath es un lenguaje de consulta para seleccionar nodos de un documento XML. Se usa para navegar a través de elementos y atributos en un documento XML. Aquí hay algunos conceptos clave para escribir XPaths:

  • Nodo Raíz: El elemento de nivel superior en el documento XML. En respuestas SAML, esto es típicamente el elemento <Response>.
  • Elemento: Un componente del documento XML, como <Assertion> o <AttributeStatement>.
  • Atributo: Un par nombre-valor dentro de un elemento, como <Attribute Name="email">.

Sintaxis XPath Común

  • Barra Simple (/): Selecciona el elemento hijo inmediato. Por ejemplo, /Response selecciona el elemento <Response> en el nivel raíz.
  • Barra Doble (//): Selecciona elementos desde cualquier lugar en el documento. Por ejemplo, //Assertion selecciona todos los elementos <Assertion> en el documento.
  • Nombre de Elemento: Selecciona todos los elementos con el nombre especificado. Por ejemplo, //saml:Attribute selecciona todos los elementos <saml:Attribute>.
  • Selector de Atributo (@): Selecciona elementos con un atributo específico. Por ejemplo, //saml:Attribute[@Name='email'] selecciona todos los elementos <saml:Attribute> con el atributo Name igual a email.

Pantalla de inicio de sesión con SSO SAML2 habilitado

Una vez que SAML2 está habilitado en la configuración, Clarive siempre redirigirá a la URL de inicio de sesión SSO. Para deshabilitar SSO temporalmente e iniciar sesión usando la página de inicio de sesión estándar, use el parámetro de URL de inicio de sesión sso=0.

https://misclariveserver/?sso=0

Esto llevará al usuario al inicio de sesión estándar de Clarive.

Inicio de sesión de Git, Servicio Web y Clave API

La interfaz Git de Clarive usa Autenticación HTTP Básica desde la línea de comandos u otros clientes git y no redirigirá al usuario al inicio de sesión del proveedor SSO SAML2.

Lo mismo sucede cuando se usa el inicio de sesión con clave API del Servicio Web que seguirá funcionando usando claves API definidas en base por usuario y no dependerá de la infraestructura SSO.

Ambos inicios de sesión se pueden lograr creando una clave API y usándola como contraseña (especialmente en el caso de Git).

Ejemplo de Estructura de Respuesta SAML

Aquí hay un ejemplo de una estructura típica de SAMLResponse:

<Response>
    <Assertion>
        <AttributeStatement>
            <Attribute Name="email">
                <AttributeValue>[email protected]</AttributeValue>
            </Attribute>
        </AttributeStatement>
    </Assertion>
</Response>

Estas rutas se usan para navegar la respuesta SAML y extraer los atributos necesarios.

Ejemplo de Configuración para Microsoft Azure Entra ID

Este es un ejemplo completo de cómo configurar el Single sign-on de Azure Entra ID:

saml2:
    issuer: 'miclarive'
    service_url: 'https://miclarive.ejemplo.com/'
    entry_point: 'https://login.microsoftonline.com/9a624754-aa30-4cab-af32-c71b8af0ca50/saml2'
    logout_url: 'https://login.microsoftonline.com/9a624754-aa30-4cab-af32-c71b8af0ca50/saml2'
    idp_cert: |
      -----BEGIN CERTIFICATE-----
      MIIC9DDD....
      TylNaWNyb3....
      STNaFw0yN....
      U1NPIENlc....
      S7o3oJ3li....
      -----END CERTIFICATE-----

En Microsoft Azure > Manage > Single sign-on > Basic SAML Configuration establezca los campos a los valores correspondientes en su archivo CONFIG.yml: