Descripción general

Descripción general

SAML (Security Assertion Markup Language) es un protocolo de autenticación ampliamente utilizado que permite el inicio de sesión único (SSO). Permite a los usuarios autenticarse una vez con un Proveedor de Identidad (IdP) y obtener acceso a múltiples servicios sin necesidad de volver a iniciar sesión.

Activación del método de autenticación basada en variables de entorno

La siguiente tabla indica qué método de autenticación está habilitado dependiendo de la configuración de las variables de entorno:

Formato y configuración del certificado SAML

La variable de entorno SAML_CERT se utiliza para especificar el certificado de firma del Proveedor de Identidad (IdP) para validar las Respuestas SAML. Este certificado debe proporcionarse en formato PEM y puede especificarse de una de las siguientes maneras:

Como una ruta de archivo (relativa o absoluta)

Si SAML_CERT se establece en una ruta de archivo, la aplicación cargará el certificado desde el archivo especificado. Se admiten tanto rutas relativas como rutas absolutas.

# Relative path (resolved based on the application root)
SAML_CERT=idp-cert.pem

# Absolute path
SAML_CERT=/path/to/idp-cert.pem

Contenido del archivo de ejemplo (idp-cert.pem):

-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...
-----END CERTIFICATE-----

Como una cadena PEM de una sola línea

El certificado también puede proporcionarse como una cadena PEM de una sola línea (codificada en Base64, sin saltos de línea).

SAML_CERT="MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W=="

Este formato es útil al almacenar el certificado directamente en variables de entorno.

Como una cadena PEM de varias líneas (con secuencias de escape \n)

El certificado también puede proporcionarse como una cadena PEM multilínea donde los saltos de línea se representan como \n.

SAML_CERT="-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...\n-----END CERTIFICATE-----\n"

Este formato es útil al configurar certificados en archivos .env mientras se preserva la estructura PEM completa.

Requisitos de formato de certificado

• El certificado debe estar siempre en formato PEM (certificado X.509 codificado en Base64).
• Si se proporciona como archivo, debe ser un formato PEM de mensaje textual estricto RFC7468 válido.
• Al usar un certificado de una sola línea, asegúrese de que no haya saltos de línea en el valor.
• Al usar una cadena multilínea, asegúrese de que los saltos de línea estén representados como secuencias de escape \n.

Para más detalles, consulte la documentación de node-saml.

Flujo de determinación del nombre de usuario para mostrar basado en atributos SAML

En la autenticación SAML, el nombre de usuario que se muestra se determina de acuerdo con el siguiente flujo.

flowchart TD
    A[Start] --> B{{Is SAML_NAME_CLAIM available?}}
    B -- Yes --> C[Value of SAML_NAME_CLAIM]
    B -- No --> D{{Are both SAML_GIVEN_NAME_CLAIM & SAML_FAMILY_NAME_CLAIM available?}}
    D -- Yes --> E[Value of SAML_GIVEN_NAME_CLAIM / SAML_FAMILY_NAME_CLAIM]
    D -- No --> F{{Is only SAML_GIVEN_NAME_CLAIM available?}}
    F -- Yes --> G[Value of SAML_GIVEN_NAME_CLAIM]
    F -- No --> H{{Is only SAML_FAMILY_NAME_CLAIM available?}}
    H -- Yes --> I[Value of SAML_FAMILY_NAME_CLAIM]
    H -- No --> J{{Is SAML_USERNAME_CLAIM available?}}
    J -- Yes --> K[Value of SAML_USERNAME_CLAIM]
    J -- No --> L[Value of SAML_EMAIL_CLAIM]
    style C fill:#FFDEA5,stroke:#FFA500
    style E fill:#FFDEA5,stroke:#FFA500
    style G fill:#FFDEA5,stroke:#FFA500
    style I fill:#FFDEA5,stroke:#FFA500
    style K fill:#FFDEA5,stroke:#FFA500
    style L fill:#FFDEA5,stroke:#FFA500

Reglas de determinación

1. Si se proporciona SAML_NAME_CLAIM, su valor se utiliza como el nombre de usuario para mostrar.
2. Si se proporcionan tanto SAML_GIVEN_NAME_CLAIM como SAML_FAMILY_NAME_CLAIM, sus valores correspondientes se concatenan para formar el nombre de usuario.
3. Si solo se proporciona SAML_GIVEN_NAME_CLAIM, se utiliza su valor.
4. Si solo se proporciona SAML_FAMILY_NAME_CLAIM, se utiliza su valor.
5. Si se proporciona SAML_USERNAME_CLAIM, se utiliza su valor.
6. Si no se proporciona ninguno de los atributos anteriores, se utiliza SAML_EMAIL_CLAIM como el nombre de usuario para mostrar.

Al seguir este flujo, se determina un nombre de usuario apropiado durante la autenticación SAML.

Ejemplos de configuración

• Auth0