OIDC para TYPO3

Como projetos TYPO3 sem stack de identidade próprio se conectam ao Azure AD, Keycloak ou Okta

Em toda empresa que opera Microsoft 365, Google Workspace ou um Keycloak central, a gestão de usuários já foi decidida: todas as contas de colaboradores vivem no IdP, e cada nova aplicação deve se conectar a esse IdP, não gerenciar senhas próprias. A extensão OIDC para TYPO3 atende exatamente a esse padrão ao incorporar o OpenID Connect como protocolo de autenticação no TYPO3, tornando Azure AD, Keycloak, Okta, Google Workspace ou Auth0 utilizáveis como IdP sem operar um Shibboleth SP próprio. O público-alvo são portais corporativos, intranets, áreas de login de clientes e todos os setups TYPO3 que precisam se integrar a ambientes de identidade corporativa existentes.

Cenários típicos de uso

Um grupo industrial brasileiro com 14.000 colaboradores opera sua intranet interna em TYPO3. A equipe de TI já decidiu que cada nova aplicação se autentica contra o Azure AD e aplica Multi-Factor Authentication por lá. A extensão OIDC obtém os ID tokens do Azure AD, lê as atribuições de grupos contidas no claim e gera grupos de fe_user a partir disso. A intranet ganha Single Sign-On, MFA e Conditional Access sem infraestrutura adicional, apenas por meio de configuração limpa.

Um segundo cenário vem de empresas de médio porte: uma software house com um portal de clientes em TYPO3 utiliza o Keycloak como broker central, porque seus próprios clientes chegam com usernames ou com Social Logins como Google ou GitHub. O Keycloak unifica isso e fala OIDC para fora. O TYPO3 usa a extensão OIDC e ganha acesso a todas as variantes de login, sem nem mesmo saber que por trás há Social Login.

O terceiro caso são órgãos públicos e administrações estaduais que migram para contas de cidadão baseadas em Keycloak. Um portal TYPO3 no qual cidadãos enviam formulários de requerimento pode se conectar via extensão OIDC ao Keycloak estadual. O atributo eID do broker vai direto para o fe_user, e o nível de autenticação pode ser avaliado pelo claim acr, em conformidade com a LGPD (PT: RGPD) quanto ao tratamento dos dados.

Arquitetura técnica: Authorization Code Flow no TYPO3

OpenID Connect é uma camada de autenticação sobre OAuth 2.0, e a extensão OIDC implementa exatamente o Authorization Code Flow. O fluxo é mais simples que o SAML: o TYPO3 redireciona o usuário ao IdP com um Authorization Request, recebe um code após o login bem-sucedido, troca esse code no servidor por um ID token e valida a assinatura via JSON Web Key Set (JWKS) do provedor. Os claims do ID token, tipicamente sub, email, name, groups e roles, são mapeados para campos de usuário TYPO3.

A extensão é configurada via Extension Configuration do TYPO3 e um Discovery Endpoint, que qualquer provedor compatível com OIDC oferece em /.well-known/openid-configuration. A extensão lê desse URL os endpoints de token, o URL JWKS e os fluxos suportados de forma automática, reduzindo erros manuais. O mapeamento de claims é feito via uma configuração YAML ou TypoScript, que mapeia nomes de campos locais para caminhos de claim.

Problemas frequentes e soluções

O primeiro problema envolve formatos de claim: o Azure AD entrega grupos como Object IDs (GUIDs), não como nomes legíveis. Quem espera um claim group_ids e recebe group_names vê grupos vazios no TYPO3. A solução limpa está na própria aplicação Azure AD: no Token Configuration Blade é possível definir quais atributos são emitidos como claims, e adicionalmente regras de Claim Transformation podem traduzir GUIDs para nomes legíveis.

O segundo problema é o Redirect URI. Todo cliente OIDC precisa registrar no IdP exatamente a Redirect URI para a qual é enviado após o login. Diferenças em maiúsculas e minúsculas, trailing slashes esquecidos ou uma troca de HTTP para HTTPS causam erros de login imediatos que não são visíveis no log do TYPO3, porque o erro ocorre no IdP. A Gosign configura clientes separados para staging e produção, com Redirect URIs limpos, e documenta cada alteração no processo de deploy.

O terceiro tema é o Token Refresh. Quem quer sessões mais longas precisa de Refresh Tokens, que o IdP só emite se o scope offline_access for solicitado no login. Sem esse scope, a sessão TYPO3 termina assim que o ID token expira, normalmente após uma hora. A configuração no backend da extensão precisa enviar o scope offline_access e ativar a lógica de refresh de token.

Um quarto problema envolve o logout. O OIDC conhece Front-Channel e Back-Channel Logout, e ambos não estão necessariamente ativados na extensão. Quem espera Single Logout real em várias aplicações precisa configurar o End Session Endpoint do provedor e garantir que o TYPO3 chame o URL de logout do IdP ao encerrar a sessão. Sem essa configuração, o usuário continua autenticado no IdP mesmo após ter saído do TYPO3.

Migração e compatibilidade de versões

A extensão OIDC é atualmente o padrão recomendado para TYPO3 v12 e v13, enquanto projetos antigos em v11 frequentemente ainda usam implementações OAuth próprias ou shibboleth_auth. O caminho de migração de Shibboleth para OIDC é bem estabelecido, desde que o IdP fale os dois protocolos: Keycloak, ADFS e Azure AD conseguem servir SAML e OIDC em paralelo, permitindo uma transição sem big-bang.

Quem migra de uma gestão de fe_user puramente baseada em banco de dados precisa mapear as contas existentes aos claims OIDC com uma estratégia de matching. O endereço de email é o ponto de ancoragem mais comum, mas nem sempre basta, porque emails mudam. Um claim sub gravado no fe_user como identificador persistente único é a solução mais robusta. A Gosign assume essas migrações, incluindo o casamento de contas existentes e uma fase de transição em que ambos os caminhos de autenticação funcionam em paralelo.

Para equipes que estão iniciando um novo projeto TYPO3, OIDC é, na grande maioria dos casos, a primeira escolha. A configuração é mais enxuta que a do SAML, o esforço de cliente é menor, e todo IdP moderno suporta o protocolo nativamente. Exceções só se justificam onde exigências regulatórias ou federativas requerem explicitamente SAML, como na federação CAFe mencionada. Em todos os outros cenários, especialmente IdPs baseados em nuvem e integrações corporativas, OIDC entrega o melhor equilíbrio entre simplicidade, segurança e manutenibilidade.