Autenticación SAML 2.0 saml-2-0-authentication

Aprenda a configurar y autenticar usuarios finales (no autores de AEM) en un IDP compatible con SAML 2.0 de su elección.

¿Qué es SAML para AEM as a Cloud Service?

La integración de SAML 2.0 con AEM Publish (o Preview) permite a los usuarios finales de una experiencia web basada en AEM autenticarse en un IDP (proveedor de identidad) que no es de Adobe y acceder a AEM como un usuario autorizado con nombre.

Introducción a la configuración

Este vídeo explica cómo configurar la integración de SAML 2.0 con el servicio de publicación de AEM as a Cloud Service y cómo utilizar Okta como IDP.

Requisitos previos

Se requiere lo siguiente al configurar la autenticación SAML 2.0:

SAML 2.0 solo se admite para autenticar usuarios en AEM Publish o Preview. Para administrar la autenticación del autor de AEM que usa y IDP, integre el IDP con Adobe IMS.

Instalación del certificado público IDP en AEM

El certificado público del IDP se añade al repositorio de confianza global de AEM y se utiliza para validar que la afirmación de SAML enviada por el IDP es válida.

El repositorio de confianza global está configurado con el certificado público del IDP en AEM Author, pero como SAML solo se utiliza en AEM Publish, el repositorio de confianza global debe replicarse en AEM Publish para que el certificado público IDP sea accesible allí.

Crear almacén de claves del servicio de autenticación authentication-service-keystore

Es necesario crear un almacén de claves para el servicio de autenticación cuando la propiedad de configuración OSGi del controlador de autenticación SAML 2.0 handleLogout está establecida en true o cuando se requiere cifrado de firma AuthnRequest/aserción SAML

Instalación del par de claves pública y privada de AEM install-aem-public-private-key-pair

La instalación del par de claves pública y privada de AEM es opcional

AEM Publish se puede configurar para firmar solicitudes de autenticación (a IDP) y cifrar aserciones de SAML (a AEM). Esto se logra proporcionando una clave privada a AEM Publish y haciendo coincidir la clave pública con el IDP.

Tanto la firma de AuthnRequest como el cifrado de aserción de SAML son opcionales; sin embargo, ambos están habilitados mediante la propiedad de configuración OSGi del controlador de autenticación SAML 2.0, lo que significa que se pueden usar ambos o ninguno.useEncryption

Configurar el controlador de autenticación SAML 2.0 configure-saml-2-0-authentication-handler

La configuración de SAML de AEM se realiza a través de la configuración OSGi Controlador de autenticación Adobe Granite SAML 2.0.
La configuración es una configuración de fábrica de OSGi, lo que significa que un solo servicio de publicación de AEM as a Cloud Service puede tener varias configuraciones de SAML que cubran árboles de recursos discretos del repositorio; esto resulta útil para implementaciones de AEM de varios sitios.

Las configuraciones de OSGi por entorno (config.publish.dev, config.publish.stage y config.publish.prod) se pueden definir con atributos específicos si la configuración de SAML varía entre entornos.

Usar cifrado

Al cifrar AuthnRequest y la aserción SAML, se requieren las siguientes propiedades: useEncryption, spPrivateKeyAlias y keyStorePassword. El keyStorePassword contiene una contraseña; por lo tanto, el valor no debe almacenarse en el archivo de configuración OSGi, sino insertarse usando valores de configuración secretos

Configurar el filtro de referente

Durante el proceso de autenticación SAML, el IDP inicia un POST HTTP del lado del cliente en el punto final .../saml_login de AEM Publish. Si el IDP y AEM Publish existen en un origen diferente, el Filtro de referente de AEM Publish se configura mediante la configuración OSGi para permitir HTTP POST desde el origen del IDP.

AEM Publish admite una sola configuración de filtro de referente, por lo que debe combinar los requisitos de configuración de SAML con cualquier configuración existente.

Las configuraciones de OSGi por entorno (config.publish.dev, config.publish.stage y config.publish.prod) se pueden definir con atributos específicos si allow.hosts (o allow.hosts.regex) varían entre entornos.

Configuración del intercambio de recursos de origen cruzado (CORS)

Durante el proceso de autenticación SAML, el IDP inicia un POST HTTP del lado del cliente en el punto final .../saml_login de AEM Publish. Si el IDP y la publicación de AEM existen en hosts/dominios diferentes, el intercambio de recursos de origen de CRoss (CORS) de AEM Publish debe configurarse para permitir HTTP POST desde el host/dominio del IDP.

El encabezado Origin de esta solicitud HTTP POST suele tener un valor diferente al host de publicación de AEM, por lo que requiere la configuración CORS.

Al probar la autenticación SAML en AEM SDK local (localhost:4503), el IDP puede establecer el encabezado Origin en null. Si es así, agregue "null" a la lista alloworigin.

{
    "alloworigin": [
        "$[env:SAML_IDP_ORIGIN;default=https://dev-1234567890.okta.com]",
        "null"
    ],
    "allowedpaths": [
        ".*/saml_login"
    ],
    "supportedmethods": [
        "POST"
    ]
}

Las configuraciones de OSGi por entorno (config.publish.dev, config.publish.stage y config.publish.prod) se pueden definir con atributos específicos si alloworigin y allowedpaths varían entre entornos.

Configuración de AEM Dispatcher para permitir HTTP POST de SAML

Después de autenticarse correctamente en el IDP, el IDP orquestará un POST HTTP de vuelta al punto final /saml_login registrado de AEM (configurado en el IDP). Este POST HTTP para /saml_login está bloqueado de forma predeterminada en Dispatcher, por lo que debe permitirse explícitamente usando la siguiente regla de Dispatcher:

...

# Allow SAML HTTP POST to ../saml_login end points
/0190 { /type "allow" /method "POST" /url "*/saml_login" }

Si está configurada la reescritura de URL en el servidor web Apache (dispatcher/src/conf.d/rewrites/rewrite.rules), asegúrese de que las solicitudes a los puntos finales .../saml_login no se manipulen accidentalmente.

Pertenencia a grupo dinámico

La pertenencia a grupos dinámicos es una característica de Apache Jackrabbit Oak que aumenta el rendimiento de la evaluación y el aprovisionamiento de grupos. En esta sección se describe cómo se almacenan los usuarios y grupos cuando se habilita esta función y cómo modificar la configuración del Controlador de autenticación SAML para habilitarlo para entornos nuevos o existentes.

Cómo habilitar la pertenencia a grupos dinámicos para usuarios de SAML en nuevos entornos

Para mejorar significativamente el rendimiento de la evaluación de grupos en nuevos entornos de AEM as a Cloud Service, se recomienda activar la función de pertenencia a grupos dinámicos en nuevos entornos.
También es un paso necesario cuando se activa la sincronización de datos. Más detalles aquí .
Para ello, agregue la siguiente propiedad al archivo de configuración OSGI:

/apps/example/osgiconfig/config.publish/com.adobe.granite.auth.saml.SamlAuthenticationHandler~example.cfg.json

Con esta configuración, los usuarios y grupos se crean como usuarios externos de Oak. En AEM, los usuarios y grupos externos tienen un(a) rep:principalName predeterminado compuesto(a) por [user name];[idp] o [group name];[idp].
Observe que las Listas de control de acceso (ACL) están asociadas al nombre principal de los usuarios o grupos.
Al implementar esta configuración en una implementación existente en la que anteriormente identitySyncType no se especificaba ni se establecía en default, se crearán nuevos usuarios y grupos y se deberá aplicar ACL a estos nuevos usuarios y grupos. Tenga en cuenta que los grupos externos no pueden contener usuarios locales. Repoinit se puede usar para crear ACL para grupos externos SAML, incluso si solo se crearán cuando el usuario inicie sesión.
Para evitar esta refactorización en ACL, se ha implementado una característica de migración estándar.

Almacenamiento de las suscripciones en grupos locales y externos con pertenencia a grupos dinámicos

En los grupos locales, los miembros del grupo se almacenan en el atributo oak: rep:members. El atributo contiene la lista de uid de cada miembro del grupo. Se pueden encontrar detalles adicionales aquí.
Ejemplo:

{
  "jcr:primaryType": "rep:Group",
  "rep:principalName": "operators",
  "rep:managedByIdp": "SAML",
  "rep:members": [
    "635afa1c-beeb-3262-83c4-38ea31e5549e",
    "5e496093-feb6-37e9-a2a1-7c87b1cec4b0",
    ...
  ],
   ...
}

Los grupos externos con pertenencia a grupo dinámico no almacenan ningún miembro en la entrada de grupo.
La pertenencia al grupo se almacena en las entradas de los usuarios. Encontrará documentación adicional aquí. Por ejemplo, este es el nodo de OAK para el grupo:

{
  "jcr:primaryType": "rep:Group",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "jcr:createdBy": "",
  "jcr:created": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "rep:principalName": "GROUP_1;aem-saml-idp-1",
  "rep:lastSynced": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "jcr:uuid": "d9c6af8a-35c0-3064-899a-59af55455cd0",
  "rep:externalId": "GROUP_1;aem-saml-idp-1",
  "rep:authorizableId": "GROUP_1;aem-saml-idp-1"
}

Este es el nodo de un usuario miembro de ese grupo:

{
  "jcr:primaryType": "rep:User",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "surname": "Test",
  "rep:principalName": "testUser",
  "rep:externalId": "test;aem-saml-idp-1",
  "rep:authorizableId": "test",
  "rep:externalPrincipalNames": [
    "projects-users;aem-saml-idp-1",
    "GROUP_2;aem-saml-idp-1",
    "GROUP_1;aem-saml-idp-1",
    "operators;aem-saml-idp-1"
  ],
  ...
}

Habilitación de la pertenencia a grupos dinámicos para usuarios de SAML en entornos existentes

Como se explica en la sección anterior, el formato de los usuarios y grupos externos es ligeramente diferente del utilizado para los usuarios y grupos locales. Es posible definir una nueva ACL para grupos externos y aprovisionar nuevos usuarios externos, o utilizar la herramienta de migración como se describe a continuación.

Habilitar la pertenencia a grupos dinámicos para entornos existentes con usuarios externos

El controlador de autenticación SAML crea usuarios externos cuando se especifica la siguiente propiedad: "identitySyncType": "idp". En este caso, se puede habilitar la pertenencia al grupo dinámico modificando esta propiedad a: "identitySyncType": "idp_dynamic". No se requiere ninguna migración.

Migración automática a la pertenencia a grupos dinámicos para entornos existentes con usuarios locales

El controlador de autenticación SAML crea usuarios locales cuando se especifica la siguiente propiedad: "identitySyncType": "default". También es el valor predeterminado cuando no se especifica la propiedad. En esta sección describimos los pasos que debe seguir el procedimiento de migración automática.

Cuando esta migración está habilitada, se realiza durante la autenticación del usuario y consiste en los siguientes pasos:

Por ejemplo, si antes de la migración user1 es un usuario local y un miembro del grupo local group1, después de la migración se producirán los siguientes cambios:
user1 se convierte en un usuario externo. El atributo rep:externalId se agrega a este perfil.
user1 se convierte en miembro del grupo externo: group1;idp
user1 ya no es un miembro directo del grupo local: group1
group1;idp es miembro del grupo local: group1.
user1 es entonces miembro del grupo local: group1 a través de la herencia

La pertenencia a grupos para grupos externos se almacena en el perfil de usuario de la propiedad rep:externalPrincipalNames

Configuración de la migración automática a la pertenencia a grupos dinámicos

{
  "idpIdentifier": "<value of IDP Identifier (idpIdentifier)" property from the "com.adobe.granite.auth.saml.SamlAuthenticationHandler" configuration to be migrated>"
}

Para migrar varias configuraciones de SAML, se deben crear varias configuraciones de fábrica de OSGi para com.adobe.granite.auth.saml.migration.SamlDynamicGroupMembershipMigration, cada una de las cuales especifique un idpIdentifier para migrar.

Implementación de la configuración SAML

Las configuraciones de OSGi deben enviarse a Git e implementarse en AEM as a Cloud Service mediante Cloud Manager.

$ git remote -v
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (fetch)
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (push)
$ git add .
$ git commit -m "SAML 2.0 configurations"
$ git push adobe saml-auth:develop

Implemente la rama de Git de Cloud Manager de destino (en este ejemplo, develop) mediante una canalización de implementación de pila completa.

Invocación de la autenticación SAML

El flujo de autenticación SAML se puede invocar desde una página web del sitio de AEM, creando vínculos especialmente diseñados o botones. Los parámetros que se describen a continuación se pueden configurar mediante programación según sea necesario, por ejemplo, un botón de inicio de sesión puede establecer saml_request_path, que es donde se lleva al usuario tras la autenticación SAML correcta, en diferentes páginas de AEM, según el contexto del botón.

Almacenamiento en caché seguro mientras se usa SAML

En la instancia de publicación de AEM, la mayoría de las páginas se almacenan generalmente en caché. Sin embargo, para las rutas protegidas con SAML, el almacenamiento en caché debe deshabilitarse o el almacenamiento en caché seguro debe habilitarse mediante la configuración auth_checker. Para obtener más información, consulte los detalles proporcionados aquí

Tenga en cuenta que si almacena en caché rutas protegidas sin habilitar el auth_checker, puede experimentar un comportamiento impredecible.

petición GET

La autenticación SAML se puede invocar creando una petición HTTP GET con el formato:

HTTP GET /system/sling/login

y proporcionando parámetros de consulta:

Por ejemplo, este vínculo de HTML almacenará en déclencheur el flujo de inicio de sesión de SAML y, una vez realizado correctamente, llevará al usuario a /content/wknd/us/en/protected/page.html. Estos parámetros de consulta se pueden configurar mediante programación según sea necesario.

<a href="/system/sling/login?resource=/content/wknd&saml_request_path=/content/wknd/us/en/protected/page.html">
    Log in using SAML
</a>

petición POST

La autenticación SAML se puede invocar creando una solicitud HTTP POST con el formato:

HTTP POST /system/sling/login

y proporcionar los datos del formulario:

Por ejemplo, este botón de HTML utilizará un POST HTTP para almacenar en déclencheur el flujo de inicio de sesión de SAML y, una vez realizado correctamente, llevar al usuario a /content/wknd/us/en/protected/page.html. Estos parámetros de datos de formulario se pueden definir mediante programación según sea necesario.

<form action="/system/sling/login" method="POST">
    <input type="hidden" name="resource" value="/content/wknd">
    <input type="hidden" name="saml_request_path" value="/content/wknd/us/en/protected/page.html">
    <input type="submit" value="Log in using SAML">
</form>

Configuración de Dispatcher

Tanto el método HTTP GET como el método POST requieren acceso de cliente a los extremos /system/sling/login de AEM y, por lo tanto, se deben permitir a través de AEM Dispatcher.

Permitir los patrones de URL necesarios en función de si se utiliza GET o POST

# Allow GET-based SAML authentication invocation
/0191 { /type "allow" /method "GET" /url "/system/sling/login" /query "*" }

# Allow POST-based SAML authentication invocation
/0192 { /type "allow" /method "POST" /url "/system/sling/login" }