Autenticação SAML 2.0 saml-2-0-authentication

Saiba como configurar e autenticar usuários finais (não autores do AEM) em um IDP compatível com SAML 2.0 de sua escolha.

Qual SAML para AEM as a Cloud Service?

A integração do SAML 2.0 com o AEM Publish (ou Preview) permite que os usuários finais de uma experiência da Web com base no AEM se autentiquem em um IDP (Identity Provider) que não seja da Adobe e acessem o AEM como um usuário nomeado e autorizado.

Passo a passo da configuração

Este vídeo aborda a configuração da integração do SAML 2.0 com o serviço de publicação do AEM as a Cloud Service e o uso do Okta como o IDP.

Pré-requisitos

Os seguintes itens são necessários ao configurar a autenticação SAML 2.0:

O SAML 2.0 é compatível apenas com usos de autenticação para Publicação ou Pré-visualização do AEM. Para gerenciar a autenticação do AEM Author usando e o IDP, integre o IDP ao Adobe IMS.

Instalar certificado público do IDP no AEM

O certificado público do IDP é adicionado ao armazenamento global de confiança da AEM e usado para validar se a asserção SAML enviada pelo IDP é válida.

O armazenamento global de confiança está configurado com o certificado público do IDP no AEM Author, mas como o SAML é usado somente no AEM Publish, o armazenamento global de confiança deve ser replicado para o AEM Publish para que o certificado público do IDP fique acessível lá.

Criar armazenamento de chaves do serviço de autenticação authentication-service-keystore

A criação de um keystore para o serviço de autenticação é necessária quando a propriedade de configuração OSGi do manipulador de autenticação SAML 2.0 handleLogout está definida como true ou quando a criptografia de assinatura AuthnRequest/asserção SAML é necessária

Instalar par de chave pública/privada do AEM install-aem-public-private-key-pair

A instalação do par de chaves públicas/privadas do AEM é opcional

O AEM Publish pode ser configurado para assinar AuthnRequests (para IDP) e criptografar asserções SAML (para AEM). Isso é feito fornecendo uma chave privada para o AEM Publish e uma chave pública correspondente ao IDP.

A assinatura AuthnRequest e a criptografia de asserção SAML são opcionais, no entanto, ambas estão habilitadas, usando a propriedade de configuração OSGi do manipulador de autenticação SAML 2.0 useEncryption, o que significa que ambas ou nenhuma das duas podem ser usadas.

Configurar o manipulador de autenticação SAML 2.0 configure-saml-2-0-authentication-handler

A configuração SAML do AEM é executada por meio do Manipulador de autenticação SAML 2.0 do Adobe Granite, configuração OSGi.
A configuração é uma configuração de fábrica do OSGi, o que significa que um único serviço de publicação do AEM as a Cloud Service pode ter várias configurações SAML cobrindo árvores de recursos discretas do repositório; isso é útil para implantações de AEM em vários sites.

As configurações de OSGi por ambiente (config.publish.dev, config.publish.stage e config.publish.prod) poderão ser definidas com atributos específicos se a configuração de SAML variar entre ambientes.

Usar criptografia

Ao criptografar a solicitação AuthnRequest e a instrução SAML, as seguintes propriedades são necessárias: useEncryption, spPrivateKeyAlias e keyStorePassword. O keyStorePassword contém uma senha, portanto, o valor não deve ser armazenado no arquivo de configuração OSGi, mas inserido usando valores de configuração secreta

Configurar filtro Referenciador

Durante o processo de autenticação SAML, o IDP inicia um POST HTTP do lado do cliente para o ponto de extremidade .../saml_login do AEM Publish. Se o IDP e o AEM Publish existirem em origens diferentes, o Filtro de referenciador do AEM Publish será configurado através da configuração OSGi para permitir POSTs HTTP a partir da origem do IDP.

O AEM Publish oferece suporte a uma única configuração de filtro Referenciador, portanto, mescle os requisitos de configuração do SAML com qualquer configuração existente.

As configurações de OSGi por ambiente (config.publish.dev, config.publish.stage e config.publish.prod) poderão ser definidas com atributos específicos se o allow.hosts (ou allow.hosts.regex) variar entre ambientes.

Configurar o CORS (Cross-Origin Resource Sharing, Compartilhamento de recursos entre origens)

Durante o processo de autenticação SAML, o IDP inicia um POST HTTP do lado do cliente para o ponto de extremidade .../saml_login do AEM Publish. Se o IDP e o AEM Publish existirem em hosts/domínios diferentes, o CORS (CRoss-Origin Resource Sharing) do AEM Publish deve ser configurado para permitir POSTs HTTP do host/domínio do IDP.

O cabeçalho Origin dessa solicitação HTTP POST geralmente tem um valor diferente do host de publicação do AEM, exigindo a configuração do CORS.

Ao testar a autenticação SAML no AEM SDK local (localhost:4503), o IDP pode definir o cabeçalho Origin como null. Em caso afirmativo, adicione "null" à lista alloworigin.

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

As configurações de OSGi por ambiente (config.publish.dev, config.publish.stage e config.publish.prod) poderão ser definidas com atributos específicos se o alloworigin e o allowedpaths variarem entre ambientes.

Configurar o AEM Dispatcher para permitir POSTs HTTP SAML

Após a autenticação bem-sucedida no IDP, o IDP orquestrará um POST HTTP de volta para o ponto de extremidade registrado /saml_login da AEM (configurado no IDP). Este POST HTTP para /saml_login está bloqueado por padrão no Dispatcher, portanto, deve ser permitido explicitamente usando a seguinte regra do Dispatcher:

...

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

Se a regravação de URL no servidor Web Apache estiver configurada (dispatcher/src/conf.d/rewrites/rewrite.rules), verifique se as solicitações para os pontos de extremidade .../saml_login não foram acidentalmente danificadas.

Associação de grupo dinâmico

A Associação de Grupo Dinâmica é um recurso no Apache Jackrabbit Oak que aumenta o desempenho da avaliação e do provisionamento de grupos. Esta seção descreve como usuários e grupos são armazenados quando este recurso é ativado e como modificar a configuração do Manipulador de autenticação SAML para ativá-lo em ambientes novos ou existentes.

Como habilitar a Associação de Grupo Dinâmico para Usuários SAML em novos ambientes

Para melhorar significativamente o desempenho da avaliação de grupo em novos ambientes do AEM as a Cloud Service, a ativação do recurso Associação de grupo dinâmico é recomendada em novos ambientes.
Essa também é uma etapa necessária quando a sincronização de dados é ativada. Mais detalhes aqui .
Para fazer isso, adicione a seguinte propriedade ao arquivo de configuração OSGI:

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

Com essa configuração, usuários e grupos são criados como Usuários Externos do Oak. No AEM, os usuários e grupos externos têm um rep:principalName padrão composto por [user name];[idp] ou [group name];[idp].
Observe que as Listas de controle de acesso (ACL) estão associadas ao PrincipalName de usuários ou grupos.
Ao implantar esta configuração em uma implantação existente na qual anteriormente identitySyncType não foi especificado ou definido como default, novos usuários e grupos serão criados e a ACL deve ser aplicada a esses novos usuários e grupos. Observe que os grupos externos não podem conter usuários locais. Repoinit pode ser usado para criar uma ACL para grupos externos SAML, mesmo que eles só sejam criados quando o usuário realizar um logon.
Para evitar essa refatoração na ACL, um recurso de migração padrão foi implementado.

Como as associações são armazenadas em grupos locais e externos com associação de grupo dinâmica

Em grupos locais, os membros do grupo são armazenados no atributo oak: rep:members. O atributo contém a lista de uid de cada membro do grupo. Detalhes adicionais podem ser encontrados aqui.
Exemplo:

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

Grupos externos com associação de grupo dinâmico não armazenam nenhum membro na entrada de grupo.
A associação de grupo é armazenada nas entradas de usuários. A documentação adicional pode ser encontrada aqui. Por exemplo, este é o nó OAK do 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 é o nó de um membro usuário desse 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"
  ],
  ...
}

Como habilitar a Associação de Grupo Dinâmico para Usuários SAML em ambientes existentes

Como explicado na seção anterior, o formato dos usuários e grupos externos é um pouco diferente daquele usado para usuários e grupos locais. É possível definir uma nova ACL para grupos externos e provisionar novos usuários externos, ou usar a ferramenta de migração conforme descrito abaixo.

Ativação da associação dinâmica a grupos para ambientes existentes com usuários externos

O manipulador SAML Authentication cria usuários externos quando a seguinte propriedade é especificada: "identitySyncType": "idp". Nesse caso, a associação de grupo dinâmico pode ser habilitada modificando essa propriedade para: "identitySyncType": "idp_dynamic". Nenhuma migração é necessária.

Migração automática para associação de grupo dinâmica para ambientes existentes com usuários locais

O manipulador SAML Authentication cria usuários locais quando a seguinte propriedade é especificada: "identitySyncType": "default". Esse também é o valor padrão quando a propriedade não é especificada. Nesta seção, descrevemos as etapas executadas pelo procedimento de migração automática.

Quando habilitada, essa migração é realizada durante a autenticação do usuário e consiste nas seguintes etapas:

Por exemplo, se antes da migração user1 for um usuário local e um membro do grupo local group1, as seguintes alterações ocorrerão após a migração:
user1 torna-se um usuário externo. O atributo rep:externalId foi adicionado a seu perfil.
user1 torna-se membro do grupo externo: group1;idp
user1 não é mais um membro direto do grupo local: group1
group1;idp é um membro do grupo local: group1.
user1 é então um membro do grupo local: group1 por herança

A associação de grupo para grupos externos está armazenada no perfil de usuário na propriedade rep:externalPrincipalNames

Como configurar a migração automática para a associação de grupo dinâmica

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

Para migrar várias configurações SAML, várias configurações de fábrica OSGi para com.adobe.granite.auth.saml.migration.SamlDynamicGroupMembershipMigration devem ser criadas, cada uma especificando um idpIdentifier para migrar.

Implantando configuração SAML

As configurações do OSGi devem ser confirmadas no Git e implantadas no AEM as a Cloud Service usando o 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

Implante a ramificação Git do Cloud Manager de destino (neste exemplo, develop), usando um pipeline de implantação de Empilhamento completo.

Chamar a autenticação SAML

O fluxo de autenticação SAML pode ser chamado de uma página da Web do site do AEM, criando links especialmente criados ou um botão. Os parâmetros descritos abaixo podem ser definidos de forma programática conforme necessário, portanto, por exemplo, um botão de logon pode definir o saml_request_path, que é o local em que o usuário é levado após a autenticação SAML bem-sucedida, para páginas AEM diferentes, com base no contexto do botão.

Armazenamento em cache seguro ao usar SAML

Na instância de publicação do AEM, a maioria das páginas normalmente é armazenada em cache. No entanto, para caminhos protegidos por SAML, o armazenamento em cache deve ser desativado ou o armazenamento em cache seguro ativado usando a configuração auth_checker. Para obter mais informações, consulte os detalhes fornecidos aqui

Observe que, se você armazenar em cache caminhos protegidos sem ativar o auth_checker, poderá enfrentar um comportamento imprevisível.

solicitação GET

A autenticação SAML pode ser invocada ao criar uma solicitação HTTP GET no formato:

HTTP GET /system/sling/login

e fornecem parâmetros de consulta:

Por exemplo, este link do HTML acionará o fluxo de logon do SAML e, se bem-sucedido, levará o usuário para /content/wknd/us/en/protected/page.html. Esses parâmetros de consulta podem ser definidos de forma programática, conforme necessário.

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

solicitação POST

A autenticação SAML pode ser invocada criando uma solicitação HTTP POST no formato:

HTTP POST /system/sling/login

e fornecendo os dados do formulário:

Por exemplo, esse botão do HTML usará um POST HTTP para acionar o fluxo de logon SAML e, caso seja bem-sucedido, levará o usuário para /content/wknd/us/en/protected/page.html. Esses parâmetros de dados de formulário podem ser definidos de forma programática, conforme necessário.

<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>

Configuração do Dispatcher

Os métodos HTTP GET e POST exigem acesso do cliente aos pontos de extremidade /system/sling/login da AEM e, portanto, devem ser permitidos por meio do AEM Dispatcher.

Permitir os padrões de URL necessários com base em se o GET ou POST foi usado

# 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" }