Integração SAML com Lemonldap em Aplicações Web

O que é LemonLDAP::NG e por que usar SAML?

No cenário atual de infraestrutura de TI, a gestão de identidades e acessos tornou-se um pilar fundamental para a segurança. O LemonLDAP::NG surge como uma solução robusta e open-source para Single Sign-On (SSO) e gerenciamento de autenticação, permitindo que organizações centralizem o controle de acesso sobre diversas aplicações web sem exigir modificações profundas no código-fonte dessas aplicações. A capacidade de auto-hospedar (self-hosted) essa ferramenta em um ambiente VPS ou servidor dedicado oferece às empresas soberania total sobre seus dados sensíveis, atendendo a requisitos rigorosos de conformidade e privacidade.

A integração via protocolo SAML (Security Assertion Markup Language) é uma das formas mais maduras e seguras de conectar o LemonLDAP::NG a aplicações web modernas. O SAML permite que um provedor de identidade (IdP), neste caso, o próprio LemonLDAP, autentique o usuário e emita um asserto que é consumido por um provedor de serviços (SP), como um painel administrativo, CRM ou sistema interno. Isso elimina a necessidade de gerenciar senhas locais em cada aplicação, reduzindo drasticamente o risco de vazamentos de credenciais e facilitando a revogação de acesso instantânea.

Neste tutorial técnico, guiamos você pelo processo completo de configuração do LemonLDAP::NG como IdP SAML 2.0 e sua integração com uma aplicação web fictícia (ou real) que atua como SP. O foco é prático, utilizando Linux e comandos diretos para garantir que sysadmins e desenvolvedores possam replicar o ambiente em poucos passos.

Pré-requisitos de Infraestrutura

Antes de iniciar a configuração do software, é essencial ter um ambiente de rede estável e corretamente configurado. Para este tutorial, assumimos que você já possui uma VPS ou servidor Linux (Ubuntu/Debian ou CentOS/RHEL) com acesso root ou privilégios de sudo. A comunicação entre o IdP e o SP deve ser bidirecional e segura.

O primeiro passo crítico é garantir a resolução de nomes correta. Tanto o LemonLDAP::NG quanto a aplicação web que será protegida devem conseguir resolver os nomes de domínio um do outro, ou acessar diretamente via endereços IP se estiverem na mesma rede privada. Recomenda-se fortemente o uso de certificados TLS/SSL válidos (emitidos por uma CA pública como Let's Encrypt ou privados) para ambos os serviços, pois o protocolo SAML exige assinaturas digitais e, em muitos casos, criptografia dos assertos.

Você precisará ter instalado e funcionando um servidor web (Apache ou Nginx) e o backend Perl necessário para o LemonLDAP::NG. O processo de instalação do pacote base do LemonLDAP::NG varia conforme a distribuição, mas geralmente envolve adicionar os repositórios oficiais e instalar o meta-pacote. Certifique-se de que as dependências básicas de SSL e XML sejam satisfeitas antes de prosseguir.

Configuração do Provedor de Identidade (IdP) no LemonLDAP::NG

O coração da configuração reside nos arquivos de configuração principal do LemonLDAP::NG, localizados tipicamente em /etc/lemonldap-ng/lemonldap-ng.conf. Este arquivo controla o comportamento global do sistema, incluindo os módulos de autenticação e as configurações específicas para cada protocolo suportado.

Inicialmente, você deve garantir que o módulo SAML esteja habilitado. No arquivo de configuração global, procure pela seção [SAML]. Se ela não existir, crie-a. As seguintes diretrizes são fundamentais:

[SAML]
# Habilita o suporte a SAML 2.0
enabled = 1

# Define o tipo de servidor: 'idp' para provedor de identidade
serverType = idp

# URL base do seu IdP (sem barra final)
url = https://saml.seudominio.com.br

Além disso, é crucial definir os caminhos para os certificados digitais que serão utilizados para assinar as requisições e respostas SAML. O LemonLDAP::NG utiliza a biblioteca Crypt::OpenSSL ou similares. Você deve gerar um par de chaves RSA (privada e pública) especificamente para o SAML. Isso pode ser feito via linha de comando:

openssl req -x509 -newkey rsa:2048 -keyout /etc/lemonldap-ng/saml.key -out /etc/lemonldap-ng/saml.crt -days 365 -nodes

Em seguida, aponte para esses arquivos na configuração:

[SAML]
# Caminho para a chave privada
signingKey = /etc/lemonldap-ng/saml.key

# Caminho para o certificado público
signingCert = /etc/lemonldap-ng/saml.crt

Outro ponto vital é a configuração do EntityID. Este é um identificador único global para o seu provedor de identidade. Geralmente, segue o padrão da URL base:

[SAML]
entityId = https://saml.seudominio.com.br/saml/metadata

Após modificar o arquivo lemonldap-ng.conf, é necessário reiniciar os serviços relacionados para aplicar as mudanças. Dependendo da sua instalação, isso pode envolver reiniciar o daemon do LemonLDAP ou recarregar a configuração do servidor web.

systemctl restart lemonldap-ng
systemctl reload apache2 # ou nginx

Gerando e Exportando o Metadata SAML

O protocolo SAML funciona através da troca de metadados. O arquivo de metadados XML contém informações técnicas sobre o IdP, incluindo suas URLs de endpoint (onde o SP envia a requisição de autenticação), os certificados digitais usados para assinatura e o EntityID. Esse arquivo deve ser exportado do LemonLDAP::NG e fornecido ao administrador da aplicação web (SP).

No ambiente LemonLDAP::NG, o metadata é gerado dinamicamente pela URL de metadados configurada anteriormente. Para acessar ou baixar esse arquivo, basta navegar até a URL definida no campo url + /saml/metadata. Por exemplo:

curl https://saml.seudominio.com.br/saml/metadata -o idp_metadata.xml

Este arquivo XML resultante é a "carteira de identidade" do seu LemonLDAP::NG. Ele deve ser mantido seguro e distribuído apenas para os SPs confiáveis. Note que o arquivo contém referências à chave pública (saml.crt) que geramos anteriormente.

Configuração da Aplicação Web (Service Provider)

Agora, focamos no lado do cliente, ou seja, na aplicação web que deseja ser protegida. Seja ela desenvolvida em PHP, Python, Node.js ou Java, o princípio é o mesmo: configurar um middleware ou biblioteca SAML que atuará como Service Provider (SP). Vamos assumir uma configuração genérica baseada em bibliotecas comuns como saml2php para PHP ou passport-saml para Node.js.

O primeiro passo é instalar a dependência SAML na aplicação. No caso de um projeto PHP padrão:

composer require onelogin/php-saml

Em seguida, você deve criar o arquivo de configuração do SP. Este arquivo precisa conter as informações inversas às do IdP: onde o SP reside e onde ele espera receber os assertos.

Crie um arquivo saml_config.php (ou equivalente) com a estrutura abaixo:

$settings = array(
    'sp' => array(
        # EntityID único do seu serviço
        'entityId' => 'https://app.seudominio.com.br/saml/sp',
        
        # Configurações de certificado do SP (gerar outro par de chaves)
        'x509cert' => file_get_contents('/etc/lemonldap-ng/sp.crt'),
        'privateKey' => file_get_contents('/etc/lemonldap-ng/sp.key'),

        # URLs de endpoint do SP
        'assertionConsumerService' => array(
            'url' => 'https://app.seudominio.com.br/saml/acs',
        ),
        'singleLogoutService' => array(
            'url' => 'https://app.seudominio.com.br/saml/sls',
        ),
        
        # Indica que o SP não exigirá assinatura nas respostas, 
        # mas verificará as assinaturas do IdP
        'allowNameIdPolicy' => true,
    ),
    'idp' => array(
        # EntityID do IdP (copiado da configuração do LemonLDAP)
        'entityId' => 'https://saml.seudominio.com.br/saml/metadata',
        
        # URLs de endpoint do IdP onde o SP enviará a requisição AuthnRequest
        'singleSignOnService' => array(
            'url' => 'https://saml.seudominio.com.br/saml/redirect',
            'responseUrl' => 'https://saml.seudominio.com.br/saml/post',
        ),
        
        # URLs de Single Logout
        'singleLogoutService' => array(
            'url' => 'https://saml.seudominio.com.br/saml/logout',
        ),

        # Certificado público do IdP (extraído do idp_metadata.xml ou direto do arquivo .crt)
        'x509cert' => file_get_contents('/etc/lemonldap-ng/saml.crt'),
    ),
);

É imperativo que as URLs de singleSignOnService no SP correspondam exatamente às URLs de endpoint expostas pelo LemonLDAP::NG. Você pode verificar essas URLs exatas consultando o arquivo idp_metadata.xml gerado anteriormente ou a interface administrativa do LemonLDAP.

Implementação do Middleware de Autenticação

Com a configuração carregada, o próximo passo é implementar a lógica de redirecionamento. Em qualquer rota protegida da sua aplicação web, você deve verificar se o usuário possui uma sessão válida. Se não houver, redirecione para o IdP.

No PHP, utilizando a biblioteca saml2php, o código seria semelhante a:

require_once '/vendor/autoload.php';
use OneLogin\Saml2\Auth;

// Inicializa o objeto Auth com as configurações carregadas
$auth = new Auth($settings);

// Verifica se há sessão SAML
if (!$auth->isAuthenticated()) {
    // Redireciona para a página de login do LemonLDAP::NG
    $auth->login();
} else {
    // Usuário autenticado. Pode obter atributos como nome, email, etc.
    $attributes = $auth->getAttributes();
    echo "Bem-vindo, " . $attributes['cn'][0];
}

Além disso, você deve criar as rotas que receberão as respostas do SAML. O assertionConsumerService (ACS) é o endpoint onde o IdP envia o POST com o asserto assinado. A biblioteca geralmente fornece um controlador ou handler pronto para processar essa resposta, validar a assinatura contra o certificado do IdP e criar uma sessão local na aplicação.

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $auth->processResponse();
    
    $errors = $auth->getErrors();
    if (!empty($errors)) {
        // Trate erros de validação SAML
        error_log('SAML Error: ' . implode(', ', $errors));
    }
    
    if ($auth->isAuthenticated()) {
        // Login bem-sucedido, redirecionar para dashboard
        header('Location: /dashboard');
        exit();
    }
}

Testando a Integração e Solução de Problemas

Agora que ambos os lados estão configurados, é hora de testar o fluxo completo. Abra um navegador privado (para evitar conflitos de cookies de sessões anteriores) e tente acessar a URL protegida da sua aplicação web (https://app.seudominio.com.br/protegido). O navegador deve ser redirecionado para https://saml.seudominio.com.br/saml/redirect, onde o LemonLDAP::NG solicitará as credenciais.

Após inserir um usuário válido (criado anteriormente no painel do LemonLDAP::NG), o sistema deve validar as credenciais e redirecionar o navegador de volta para https://app.seudominio.com.br/saml/acs, com um POST contendo o asserto XML. Se tudo estiver correto, você verá a mensagem de boas-vindas ou o conteúdo do dashboard.

Caso ocorra erro, verifique os logs do servidor web e do LemonLDAP::NG (/var/log/apache2/error.log ou /var/log/lemonldap-ng/error.log). Os erros mais comuns incluem:

Falha de validação de assinatura: Verifique se o certificado público configurado no SP corresponde exatamente à chave privada usada pelo IdP. Uma atualização de certificado no LemonLDAP que não foi refletida no SP causará este erro.
Erros de tempo (Clock Skew): O protocolo SAML é sensível a diferenças de horário. Certifique-se de que o NTP esteja sincronizado em ambos os servidores (IdP e SP). Uma diferença superior a alguns minutos invalidará os timestamps do asserto.
Erros de domínio (Domain Mismatch): Se o LemonLDAP::NG estiver configurado para aceitar apenas requisições de um domínio específico, e o SP enviar uma requisição de um IP ou domínio diferente (ex: localhost durante testes), a autenticação falhará.

Considerações Finais sobre Segurança e Manutenção

A integração SAML com LemonLDAP::NG oferece uma camada de segurança forte, mas não está isenta de responsabilidades. Mantenha os certificados digitais atualizados antes que expirem. Configure alertas para renovação automática ou manual dos certificados do IdP e SP.

Além disso, considere implementar a Single Logout (SLO). Embora o tutorial tenha mencionado as URLs de logout, garantir que o fechamento de sessão no SP invalide a sessão no IdP (e vice-versa) requer configuração adicional nos metadados e na lógica de redirecionamento. Sem o SLO configurado, um usuário pode fechar a aba da aplicação web, mas ainda permanecer logado no IdP, podendo acessar outras aplicações protegidas sem reautenticação.

Por fim, utilize sempre HTTPS. O protocolo SAML não impõe criptografia de transporte por padrão; ele depende da camada de transporte (TLS) para garantir a confidencialidade dos dados transmitidos, especialmente os assertos que podem conter informações pessoais identificáveis (PII). Jamais exponha seus endpoints SAML em portas não seguras em produção.

Com esta configuração, você estabeleceu um ambiente robusto de gestão de identidade auto-hospedado, aproveitando o poder do LemonLDAP::NG para centralizar acessos em sua infraestrutura Linux/VPS, garantindo maior controle e segurança para seus sistemas internos.

Tags: #lemonldap auth #saml #integracao web #auto-hosted #identidade #vps #linux #seguranca