shibboleth_auth para TYPO3: Shibboleth Single Sign-On

Como universidades brasileiras conectam seus portais TYPO3 à gestão central de identidade

Quem opera um portal TYPO3 em uma universidade que participa da federação CAFe (Comunidade Acadêmica Federada, operada pela RNP) não consegue ignorar o Shibboleth. A federação CAFe é a maior federação de identidade acadêmica do Brasil, e cada universidade, como USP, UFRJ, UNICAMP ou UFRGS, que queira oferecer dados de pesquisa, materiais didáticos ou serviços administrativos precisa autenticar seus usuários contra um Shibboleth Identity Provider. O shibboleth_auth é a extensão que insere o TYPO3 nesse cenário: ela lê as SAML assertions de um Shibboleth Service Provider configurado à frente e cria fe_users e be_users a partir disso.

Cenários típicos de uso

Uma faculdade de medicina com 8.000 estudantes opera um portal TYPO3 para currículos clínicos. Os alunos devem ver seus materiais didáticos após o login, e os professores devem ter ainda uma interface editorial. O IdP central da universidade fornece os atributos eduPersonAffiliation, schacHomeOrganization e um identificador único. O shibboleth_auth assume o mapeamento desses atributos para grupos TYPO3 e garante que um aluno nunca acesse o backend, enquanto um professor é automaticamente incluído no grupo de redatores.

Um segundo caso típico são institutos de pesquisa associados, como os institutos vinculados ao CNPq ou à FAPESP. Seus colaboradores vêm de dezenas de universidades parceiras, e cada um deve poder se autenticar em portais centrais de projeto com sua credencial institucional. O shibboleth_auth em combinação com um SP conectado à eduGAIN permite exatamente isso: um pesquisador visitante da Universidade de Lisboa se autentica em um portal brasileiro com sua conta da federação portuguesa, sem que exista uma conta local.

O terceiro contexto é a administração pública, onde estados brasileiros operam cada vez mais IdPs estaduais para unificar contas de cidadãos e acessos de servidores. Um órgão estadual com vários portais TYPO3 para diferentes áreas pode, via shibboleth_auth, conectar todos os portais ao IdP central do estado e dispensar a manutenção de bases de usuários separadas por portal.

Arquitetura técnica entre SP, SAML e fe_user

O shibboleth_auth é construído de forma diferente dos serviços de autenticação clássicos do TYPO3: a extensão não fala SAML diretamente, mas delega todo o protocolo a um Shibboleth Service Provider instalado localmente. O SP, tipicamente o daemon shibd com mod_shib no Apache ou o módulo correspondente no Nginx, processa a SAML assertion, valida assinaturas e certificados e disponibiliza os atributos extraídos como variáveis de ambiente HTTP. O shibboleth_auth lê essas variáveis, cria ou atualiza o fe_user e faz o login na sessão TYPO3.

A extensão é configurada via Extension Configuration do TYPO3 e pelo padrão Extbase Service para provedores de autenticação. O mapeamento de atributos fica em um arquivo TypoScript ou diretamente no backend da extensão: variável HTTP à esquerda, nome do campo TYPO3 à direita, opcionalmente com transformações para IDs de grupo. A ordem na configuração $TYPO3_CONF_VARS[‘SVCONF’][‘auth’][‘setup’] é importante, para que o shibboleth_auth atue antes do serviço de login padrão.

Problemas frequentes e soluções

O erro mais comum é um loop de redirecionamento: o usuário é enviado ao IdP, volta, é enviado ao IdP novamente, e assim por diante. A causa quase sempre é uma divergência entre o domínio de sessão do SP e o do TYPO3, ou um cookie faltando porque o SP grava sua sessão em um caminho diferente do esperado pelo TYPO3. A solução é uma separação limpa: sessão do SP no caminho /Shibboleth.sso, sessão TYPO3 em / e ambos sob o mesmo domínio de topo.

O segundo problema envolve atributos: o IdP entrega um nome de atributo diferente do que a extensão espera. Especialmente na federação CAFe, os namespaces de atributos mudam entre notações OID e URN. Sem uma normalização limpa, o usuário não entra em nenhum grupo ou recebe um nome vazio no perfil. Um arquivo de mapeamento de atributos no SP, que unifica nomes antigos e novos em um nome local único, resolve o problema em definitivo.

O terceiro tema é rotação de certificados. Todo IdP troca seus certificados de assinatura e criptografia regularmente, normalmente a cada dois anos. O SP precisa puxar os novos certificados pelo feed de metadados, caso contrário a validação de assertions para de funcionar do nada. A configuração de metadata provider no shibboleth2.xml deve rodar com intervalo de refresh automático de poucas horas e verificação de assinatura contra o signer da federação.

Um quarto ponto são os tempos de vida das sessões. As sessões Shibboleth e TYPO3 têm timeouts independentes: se a sessão do SP expira enquanto a sessão TYPO3 ainda está ativa, o usuário vê seus conteúdos protegidos, mas um re-login falha porque o SP não tem mais uma assertion válida. A solução limpa é ajustar ambas as durações para o mesmo valor e configurar um comportamento de logout paralelo, de modo que Single Logout realmente encerre as duas sessões.

Migração e compatibilidade de versões

O shibboleth_auth acompanhou por muito tempo as versões TYPO3 v9, v10 e v11 via forks da comunidade, mas a situação em v12 e v13 varia conforme o ramo de fork. Alguns forks adotaram serviços de autenticação baseados em Symfony, outros ficaram na v11. Quem migra hoje para v12 deve verificar antes do upgrade se o próprio ramo da extensão ainda é mantido ou se uma mudança para a OIDC Extension é a escolha melhor.

O caminho de migração de Shibboleth para OIDC ficou relevante para muitas universidades desde que Keycloak e brokers de identidade similares passaram a conectar clientes SAML e OIDC em paralelo. A Gosign acompanhou várias dessas transições e, durante a fase de mudança, tipicamente opera ambos os caminhos de autenticação em paralelo, de modo que sistemas legados continuam autenticando via Shibboleth enquanto portais novos já falam OIDC diretamente.

Quem permanece no shibboleth_auth deve avaliar a carga de manutenção de forma realista. A extensão em si muda pouco, mas a infraestrutura ao redor muda regularmente: o Shibboleth SP publica atualizações de segurança, a federação atualiza metadados e certificados, versões Apache ou Nginx são trocadas, e cada uma dessas alterações pode quebrar o fluxo de login. Um monitoramento adequado da pipeline de autenticação com logins sintéticos e alertas para assertions falhadas não é um nice-to-have, mas parte do conceito operacional para uma integração SSO estável.