SAML2 para TYPO3

O SAML 2.0 permite Single Sign-On no TYPO3 sem instalar o Shibboleth no servidor

Universidades, órgãos públicos e grandes grupos empresariais operam Identity Providers (IdP) baseados em SAML 2.0: Microsoft ADFS, Okta, Keycloak, PingFederate. Quem queria usar essas identidades no TYPO3 precisava, até agora, de um Shibboleth Service Provider no servidor web: uma camada adicional de software, com configuração, certificados e manutenção próprios. A extensão saml2 para TYPO3 torna o Shibboleth SP dispensável. Ela usa o SimpleSAMLphp, um SP de SAML 2.0 escrito em PHP que roda ao lado do TYPO3. Isso simplifica bastante a arquitetura do servidor, sobretudo em hospedagem compartilhada ou em deploys com containers, onde é difícil instalar um Shibboleth SP.

Para organizações cujo IdP não suporta OIDC (OpenID Connect), o SAML 2.0 é o único caminho padronizado para o Single Sign-On. A extensão fecha exatamente essa lacuna no ecossistema TYPO3.

Os cenários típicos são intranets universitárias, portais de governo e extranets corporativas

O cenário mais comum é a intranet universitária. Uma universidade opera um IdP Shibboleth numa federação acadêmica, como a DFN-AAI da rede alemã de pesquisa (Deutsches Forschungsnetz) ou, no Brasil, a CAFe, operada pela RNP. Estudantes, professores e servidores fazem login com a credencial institucional e acessam páginas protegidas do TYPO3: apostilas, notícias internas, notas de provas. A extensão saml2 deixa a verificação da SAML assertion a cargo do SimpleSAMLphp e faz o login do usuário de frontend correspondente no TYPO3; pelos grupos desse usuário (por exemplo, estudantes = grupo “student”, professores = grupo “staff”), o TYPO3 controla o acesso.

Um segundo cenário são portais de governo com login centralizado do cidadão. Na Alemanha, o BundID é, desde 2023, o serviço central de identidade do governo federal, e o SAML 2.0 é um dos protocolos suportados. Um município alemão pode conectar seu site TYPO3 ao BundID via saml2, para que os cidadãos façam login com a carteira de identidade eletrônica (eID) ou com o certificado do Elster, o portal fiscal alemão, e acessem serviços personalizados. No Brasil, o equivalente é o login gov.br, que se integra via OpenID Connect; nesse caso, o caminho é a extensão oidc.

Terceiro cenário: extranets corporativas. Uma montadora opera um portal de concessionárias em TYPO3. As concessionárias fazem login pelo IdP corporativo (Microsoft ADFS) e veem tabelas de preços, material de treinamento e formulários de pedido atribuídos ao seu grupo de concessionárias. A extensão saml2 faz o login delas como usuários de frontend do TYPO3, e os grupos desses usuários controlam o acesso às áreas de conteúdo protegidas.

A arquitetura técnica conecta o SimpleSAMLphp ao TYPO3 como SP de SAML 2.0

A extensão saml2 se baseia no SimpleSAMLphp, uma implementação independente de SAML 2.0 em PHP que cuida do AuthnRequest, da validação da resposta, do parsing da assertion e da verificação de assinatura. O SimpleSAMLphp é instalado ao lado do TYPO3; a extensão o carrega por um caminho configurado e se registra como serviço de autenticação do TYPO3 para o frontend.

A configuração se divide em dois lugares. IdP e SP (metadados, Entity IDs, certificados) são configurados no SimpleSAMLphp. No TYPO3, a configuração da extensão guarda o caminho do SimpleSAMLphp, o perfil do SP e o endereço do IdP; por TypoScript se definem o atributo pelo qual o usuário TYPO3 é encontrado e o mapeamento dos atributos do IdP para os campos do usuário de frontend. O login começa pelo plugin “SAML-Login” na página TYPO3 (SSO iniciado pelo SP).

A extensão não cria usuários de frontend: ela faz o login de um usuário existente, encontrado pelo atributo configurado (padrão: uid), e, se desejado, atualiza os campos dele a cada acesso. Contas novas surgem pelo cadastro com o femanager, ao qual a extensão se conecta.

A extensão não oferece login no backend (usuários BE) por SAML: ela registra o serviço de autenticação só para o frontend. Quem introduz SAML também no backend assume um risco maior: se o IdP cair, ninguém mais acessa o backend. Nesse caso, recomendamos manter pelo menos uma conta de administrador local como fallback.

Os problemas frequentes envolvem certificados, diferença de horário e mapeamento de atributos

O problema mais comum em integrações SAML são certificados vencidos ou mal configurados. O IdP assina a resposta SAML com o seu certificado. Se o certificado não é atualizado no SP depois que o IdP faz a rotação, a verificação da assinatura falha e o login é interrompido com uma mensagem de erro enigmática. A solução: incluir a rotação de certificados no calendário de manutenção. A maioria dos IdPs avisa com 30 dias de antecedência.

Segundo problema: diferença de horário entre IdP e SP. As SAML assertions têm uma janela de validade (NotBefore / NotOnOrAfter). Se os relógios do servidor do IdP e do servidor TYPO3 divergem mais do que a biblioteca SAML tolera (180 segundos por padrão no onelogin/php-saml e no SimpleSAMLphp), a assertion é rejeitada como inválida. A solução: configurar NTP nos dois servidores.

Terceiro tema: mapeamento de atributos incorreto. Cada IdP nomeia os atributos de um jeito. O Microsoft ADFS entrega “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”, o Keycloak entrega “email”, o Shibboleth entrega “urn:oid:0.9.2342.19200300.100.1.3”. A extensão precisa saber sob qual nome o atributo de e-mail vem no token SAML. Um mapeamento errado gera campos vazios no perfil do usuário no TYPO3. Ativar o log de debug dos atributos recebidos ajuda a identificar as chaves de mapeamento corretas.

A extensão saml2 é uma versão beta de 2014 para o TYPO3 6.2

A extensão saml2 no TER é uma versão beta: a 1.0.0 da Youwe, de agosto de 2014, que suporta apenas o TYPO3 6.2. Não há versão mais nova nem no TER nem no Packagist; para as versões atuais do TYPO3, ela precisa ser portada ou substituída. Em projetos de SSO, a Gosign verifica se a biblioteca SAML está atualizada (patches de segurança) e qual extensão combina com a versão do TYPO3 em uso. Como a extensão saml2 não é mais mantida, recomendamos como alternativa a extensão oidc, desde que o IdP suporte OpenID Connect.