Keycloak como Identity Broker com Entra ID

Federação SAML, o problema do ForceAuthn ignorado e solução para dispositivos partilhados.

Este artigo explica como usar o Keycloak como intermediário de identidade (identity broker) entre aplicações locais e o Microsoft Entra ID, com foco na federação SAML e no problema do ForceAuthn ignorado em cenários de dispositivos partilhados.

Neste artigo

O que é o Keycloak

O Keycloak é uma solução open-source de gestão de identidade e acesso (IAM), desenvolvida pela Red Hat. Permite autenticar utilizadores, gerir sessões, federar identidades com múltiplos providers e aplicar políticas de segurança como MFA, sem ter de implementar estas funcionalidades em cada aplicação.

Principais capacidades do Keycloak:

Funcionalidade Descrição
SSO (Single Sign-On) Uma sessão para múltiplas aplicações
Identity Brokering Federar com Entra ID, Google, AD, etc.
Protocolos OpenID Connect, SAML 2.0, OAuth 2.0
Gestão de utilizadores Realm próprio com utilizadores, grupos, papéis
MFA TOTP, WebAuthn, fluxos de autenticação customizados

Keycloak como Identity Broker

Num cenário típico de PME, as aplicações internas precisam de autenticar utilizadores que já existem no Entra ID (antigo Azure AD). Em vez de cada aplicação falar diretamente com a Microsoft, o Keycloak posiciona-se como broker: as aplicações autenticam-se no Keycloak, e este delega a autenticação no Entra ID.

Vantagens desta arquitetura:

  • Camada de abstração: aplicações só conhecem o Keycloak; mudanças no Entra ID não afectam as aplicações
  • Mapeamento de atributos: transformar claims do Entra ID no formato que as aplicações esperam
  • Políticas locais: aplicar MFA adicional, políticas de sessão ou autorização no Keycloak
  • Multi-provider: pode federar com Entra ID + outros IdPs simultaneamente

Configurar Entra ID como Provider SAML

No portal do Entra ID, é necessário registar o Keycloak como uma aplicação enterprise com SAML. Passos:

1. Criar aplicação enterprise: No portal do Entra ID, ir a Enterprise applications → New application → Create your own application. Escolher “Integrate any other application you don’t find in the gallery”.

2. Configurar SSO por SAML: Em Single sign-on → SAML, definir:

Identifier (Entity ID):      https://keycloak.exemplo.pt/realms/empresa
Reply URL (Assertion Consumer URL): https://keycloak.exemplo.pt/realms/empresa/broker/entra-id/endpoint

Required claim types:
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  - http://schemas.microsoft.com/identity/claims/objectidentifier

3. Descarregar metadados: Na página de configuração SAML, copiar o App Federation Metadata URL — será usada no Keycloak.

4. Configurar atributos opcionais: Em Attributes & Claims, garantir que o userprincipalname e mail são mapeados. O objectidentifier (OID) é essencial para identificar o utilizador de forma estável.

Configurar Keycloak com Entra ID

No Keycloak, a federação faz-se através de Identity Providers no realm desejado:

1. Adicionar Identity Provider SAML: Em Realm Settings → Identity Providers → Add provider → SAML v2.0.

2. Importar metadados do Entra ID: Colar a URL de metadados do passo anterior. O Keycloak preenche automaticamente os campos:

Alias:                  entra-id
Display name:           Entra ID (Microsoft 365)
Single Sign-On Service URL: (auto-preenchido dos metadados)
Single Logout Service URL: (auto-preenchido dos metadados)
Entity ID:              https://keycloak.exemplo.pt/realms/empresa
NameID Policy Format:   Persistent
Force Authentication:   Enabled   <-- importante (ver secção seguinte)

3. Mapear atributos: Em Mappers do IdP, criar mapeamentos para que o email, name e OID do Entra ID sejam atributos do utilizador no Keycloak:

Mapper type:           Attribute Importer
Social Profile UID Field: http://schemas.microsoft.com/identity/claims/objectidentifier
Email Attribute:       http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Name Attribute:        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

4. Prime login: O primeiro login de um utilizador via Entra ID cria automaticamente o utilizador no realm do Keycloak (se Trust Email e Account Linking Only não estiverem activos).

O Problema do ForceAuthn Ignorado

Problema: O Keycloak envia ForceAuthn="true" no pedido SAML para o Entra ID, esperando que o Entra ID force uma nova autenticação (pedir credenciais novamente). No entanto, o Entra ID ignora este parâmetro se a sessão do utilizador no browser ainda for válida — apresenta SSO silencioso e devolve a asserção sem pedir login.

Este comportamento é documentado e conhecido. O Entra ID trata o ForceAuthn como uma sugestão, não como um requisito obrigatório. A Microsoft usa o parâmetro interno prompt=login (em OIDC) para forçar re-autenticação, mas no protocolo SAML esta garantia não existe de forma fiável.

Impacto: Em cenários onde é obrigatório confirmar a identidade do utilizador (ex: operações sensíveis, dispositivos partilhados, quiosques), o SSO silencioso é um risco de segurança — o utilizador anterior pode ainda ter a sessão activa.

Solução para Dispositivos Partilhados

Para cenários de dispositivos partilhados (quiosques, salas de formação, terminais multi-utilizador), há várias abordagens para contornar o ForceAuthn ignorado:

Abordagem 1 — Logout explícito antes do login:

O Keycloak faz um SAMLLogoutRequest para o Entra ID antes de redireccionar para o login. Isto termina a sessão no Entra ID e força credenciais na próxima autenticação.

// Fluxo de autenticação customizado no Keycloak:
// 1. Verificar se dispositivo é partilhado (header/parâmetro)
// 2. Se sim, enviar SAMLLogoutRequest para Entra ID
// 3. Redireccionar para SSO com ForceAuthn=true

// No Keycloak, configurar Authentication Flow:
// Browser Flow → Identity Provider Redirector
//   → Conditional sub-flow "Shared Device"
//     → Condition: parameter shared_device=true
//     → Execute SAML Logout (custom SPI)
//     → Redirect to IdP login

Abordagem 2 — Usar OIDC em vez de SAML para o broker:

Configurar o Entra ID como IdP OIDC (não SAML) no Keycloak. O OIDC suporta o parâmetro prompt=login que o Entra ID respeita de forma fiável:

// No Keycloak, adicionar IdP tipo OpenID Connect v1.0
// Configurar:
Alias:              entra-id-oidc
Authorization URL:  https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
Token URL:          https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Logout URL:         https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout
Prompt:             login    <-- força re-autenticação sempre

Nota: A opção prompt=login no Keycloak OIDC IdP corresponde ao parâmetro OIDC standard que o Entra ID honra. Esta é a solução mais fiável para dispositivos partilhados.

Abordagem 3 — Shared Device Mode do Entra ID:

O Entra ID suporta Shared Device Mode para dispositivos geridos via Intune/MDM. Neste modo, o logout de um utilizador termina verdadeiramente a sessão a nível do dispositivo, e o próximo utilizador tem de se autenticar desde o início. Requer que as aplicações usem a MSAL Library e que o dispositivo esteja registado como partilhado.

Erros Comuns no SAML

Erro Causa Solução
ACS URL não corresponde Reply URL no Entra ID diferente da URL do Keycloak Confirmar que a Assertion Consumer URL exacta está no Entra ID
“Invalid signature” no Keycloak Certificado do Entra ID expirou ou não foi importado Reimportar metadados do Entra ID; verificar validade do certificado
Utilizador não é criado no Keycloak Account Linking Only activo ou mapeamento de NameID incorrecto Desactivar “Account Linking Only”; usar OID como identificador estável
Sessão não termina no logout Single Logout não configurado ou Entra ID não propaga logout Verificar SLO URLs nos metadados; testar logout com browser traces
ForceAuthn não força re-login Entra ID ignora ForceAuthn em SAML (comportamento conhecido) Mudar para OIDC com prompt=login ou fazer logout explícito antes
“Entity ID mismatch” Entity ID do Keycloak diferente do registado no Entra ID Confirmar que o Entity ID inclui o realm completo
Certificado de assinatura rotacionado Entra ID roda certificados; Keycloak tem versão antiga em cache Reimportar metadados periodicamente ou usar URL de metadados dinâmica

Checklist de Implementação

  1. Instalar Keycloak com HTTPS válido (TLS obrigatório para SAML)
  2. Criar realm dedicado para a organização (não usar o realm master)
  3. Registar aplicação enterprise no portal do Entra ID com SAML SSO
  4. Configurar Entity ID e ACS URL com correspondência exacta entre Entra ID e Keycloak
  5. Importar metadados do Entra ID no Keycloak (Identity Providers → SAML)
  6. Criar mapeamentos de atributos (email, nome, OID)
  7. Testar login com um utilizador de teste do Entra ID
  8. Avaliar necessidade de ForceAuthn — se dispositivos partilhados, migrar para OIDC com prompt=login
  9. Configurar Single Logout e testar fim-a-fim
  10. Configurar alerta de expiração de certificados do Entra ID
  11. Documentar URLs de metadados e procedimento de rotação de certificados

Artigos Relacionados