Dia 7: Federação SAML com Entra ID e Keycloak

A federação SAML permite que o Entra ID (antigo Azure AD) funcione como Fornecedor de Identidade central para aplicações externas, eliminando passwords múltiplas e centralizando a gestão de identidade. Neste sétimo dia do curso M365, vamos configurar SSO SAML com enterprise applications, mapear claims personalizadas, integrar Keycloak como identity broker e explorar cenários multi-tenant e B2B.

Neste artigo

1. Introdução à Federação SAML

O protocolo SAML 2.0 (Security Assertion Markup Language) é o padrão de facto para federar identidade entre organizações e aplicações. Ao contrário do OIDC (baseado em OAuth 2.0), o SAML usa tokens XML assinados — as assertions — para transmitir informação de identidade de forma segura entre um Fornecedor de Identidade (IdP) e um Service Provider (SP).

No contexto do Entra ID, a federação SAML permite que aplicações que suportam SAML (como Salesforce, ServiceNow, Amazon AWS e aplicações on-premises) autentiquem os utilizadores através do Entra ID, sem que estes precisem de memorizar credenciais adicionais. O fluxo básico é:

  1. O utilizador acede à aplicação (SP)
  2. A aplicação redireciona para o Entra ID (IdP)
  3. O utilizador autentica-se no Entra ID (com MFA, Conditional Access, etc.)
  4. O Entra ID devolve uma SAML assertion assinada à aplicação
  5. A aplicação valida a assertion e concede acesso

Para uma visão geral completa do SSO no Entra ID, consulte a documentação oficial de Enterprise Applications.

ℹ O SSO SAML elimina passwords múltiplas — os utilizadores autenticam-se uma vez no Entra ID e acedem a todas as aplicações federadas.

Aspecto SAML 2.0 OIDC
Formato do token XML assinado JWT (JSON)
Caso de uso típico Aplicações enterprise legadas Aplicações modernas, SPAs
Complexidade de configuração Média-alta (certificados, metadados) Baixa (client ID + secret)
Suporte no Entra ID Gallery + Non-gallery apps App registrations

2. Enterprise Applications no Entra ID

As Enterprise Applications são o ponto de entrada para configurar SSO no Entra ID. Existem três tipos principais:

  • Gallery Applications — aplicações pré-configuradas (mais de 4000 no catálogo, incluindo Salesforce, ServiceNow, AWS)
  • Non-gallery Applications — aplicações SAML customizadas, sem predefinição do catálogo
  • On-premises Applications — aplicações internas publicadas via Application Proxy

Cada enterprise application cria automaticamente um Service Principal no Entra ID, que representa a instância da aplicação no directório. O Service Principal contém a configuração de SSO, as atribuições de utilizadores e grupos, e as políticas de acesso condicional.

# Listar enterprise applications com SAML SSO configurado
Connect-MgGraph -Scopes "Application.Read.All"
Get-MgServicePrincipal -Filter "samlSingleSignOnSettings ne null" | Select-Object DisplayName, AppId

# Verificar certificados de assinatura SAML (data de expiração)
Get-MgServicePrincipal | ForEach-Object {
    $certs = $_.KeyCredentials | Where-Object {$_.Usage -eq "Verify"}
    if ($certs) {
        [PSCustomObject]@{
            App = $_.DisplayName
            Expiry = $certs.EndDateTime
        }
    }
} | Sort-Object Expiry

A diferença entre App Registrations e Enterprise Applications causa confusão frequente: a App Registration define a aplicação no abstracto (client ID, redirect URIs, permissões), enquanto a Enterprise Application (Service Principal) representa a instância concreta no tenant, com utilizadores atribuídos, claims configuradas e SSO activo.

3. Configurar SSO SAML

A configuração de SSO SAML envolve três passos fundamentais: importar a metadados da aplicação, configurar o Entra ID com os endpoints correctos e trocar certificados de assinatura.

Passo 1 — Configuração básica SAML

No portal do Entra ID, navegar para Enterprise Applications → [Aplicação] → Single início de sessão → SAML. Os parâmetros essenciais são:

Parâmetro Descrição Obrigatório
Identifier (Entity ID) URI único que identifica a aplicação Sim
Reply URL (ACS) Endpoint onde o Entra ID envia a assertion Sim
Sign on URL URL de início de sessão iniciado pelo SP Opcional
Relay State URL de destino após autenticação Opcional

Passo 2 — Troca de metadados e certificados

O Entra ID gera automaticamente um certificado de assinatura SAML com validade de 3 anos. É necessário descarregar a Federation Metadados XML e fornecer à aplicação, ou copiar manualmente os valores de Login URL, Entra ID Identifier e Certificate (Base64).

# Criar uma enterprise application SAML (non-gallery)
New-MgServicePrincipal -AppId "app-id-here" -DisplayName "Aplicação Externa"

# Verificar modo de SSO configurado
Get-MgServicePrincipal -ServicePrincipalId "sp-id" | Select-Object PreferredSingleSignOnMode

# Descarregar federation metadados XML
# Entra ID → Enterprise Applications → App → Single início de sessão → Download Federation Metadados XML

Passo 3 — Atribuir utilizadores e grupos

Por defeito, ninguém tem acesso a uma enterprise application nova. É necessário atribuir explicitamente utilizadores ou grupos. Para empresas com muitos utilizadores, recomenda-se atribuir grupos em vez de utilizadores individuais — isto simplifica a gestão e permite escalar.

⚠ O certificado de assinatura SAML expira — sem renovação, todas as aplicações federadas deixam de funcionar. Monitorizar a data de expiração.

4. Claims e Token Configuration

As claims são atributos do utilizador incluídos na SAML assertion. Por defeito, o Entra ID envia user.userprincipalname (Name ID), user.givenname e user.surname. A maioria das aplicações requer claims adicionais como email, departamento ou role.

Claims essenciais

Claim Origem (Entra ID) Uso típico
emailaddress user.mail Identificação do utilizador na app
department user.department Autorização baseada em departamento
role directoryRole / appRole RBAC na aplicação
employeeid user.employeeid Mapeamento com HR 
# Configurar claims via portal:
# Entra ID → Enterprise Applications → App → Single início de sessão
# → Attributes & Claims → Add new claim
#
# Adicionar claims: email, department, role
# Transform claims: extra → tolower(user.mail) para normalizar email
#
# Via Microsoft Graph PowerShell:
$params = @{
    ClaimsMapping = @{
        AdditionalProperties = @(
            @{ Name = "email"; Source = "user"; SourceId = "mail" }
            @{ Name = "department"; Source = "user"; SourceId = "department" }
            @{ Name = "role"; Source = "user"; SourceId = "assignedroles" }
        )
    }
}
Update-MgServicePrincipalClaimMapping -ServicePrincipalId "sp-id" -BodyParameter $params

As claims transformations permitem modificar valores antes de os enviar. Por exemplo, converter o email para minúsculas (ToLower(user.mail)), extrair o domínio (ExtractMailDomain(user.mail)) ou juntar atributos (Join(user.givenname, " ", user.surname)).

5. Keycloak como Identity Broker

O Keycloak é um Fornecedor de Identidade código aberto que pode funcionar como identity broker — uma camada intermédia entre o Entra ID e aplicações que não suportam SAML nativamente ou que precisam de um IdP próprio. Neste padrão, o Keycloak federar com o Entra ID (recebendo identidades) e oferece OIDC ou SAML às aplicações a jusante.

Para detalhes sobre a configuração específica de Keycloak com Entra ID e forçar reautenticação, consulte o artigo Keycloak como Identity Broker com Entra ID: Federação SAML e Forçar Reautenticação no kbase.pt.

Configuração do Keycloak como IdP Broker

# Keycloak como IdP broker
# Keycloak → Fornecedor de Identidades → Add → OpenID Connect ou SAML 2.0
#
# Para federar com Entra ID via OIDC:
# Configurar:
#   Client ID:     [do App Registration no Entra ID]
#   Client Secret: [gerado no Entra ID]
#   Authorization URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
#   Token URL:        https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
#   Issuer:           https://login.microsoftonline.com/{tenant-id}/v2.0
#   Scope:            openid email profile
#
# Para federar via SAML 2.0:
#   Importar metadados XML do Entra ID
#   Single Sign-On Service URL: do metadados
#   Single Logout Service URL: do metadados
#   Signing Certificate: do metadados

A documentação completa do Keycloak está disponível em keycloak.org/documentation.

Fluxo de autenticação intermediada

  1. Utilizador acede à aplicação configurada com Keycloak
  2. Keycloak mostra página de login com opção “Início de sessão with Entra ID”
  3. Keycloak redireciona para o Entra ID (IdP a montante)
  4. Entra ID autentica (MFA, Conditional Access) e devolve token ao Keycloak
  5. Keycloak mapeia identidade e emite token próprio (OIDC ou SAML) à aplicação
Cenário Recomendação Justificação
App suporta SAML nativo Directo Entra ID → App Menos saltos, menor latência
App suporta apenas OIDC Directo Entra ID → App (OIDC) Entra ID suporta OIDC nativamente
Múltiplas apps on-premises Keycloak como broker Centraliza SSO, simplifica certificados
App só suporta SAML legado Keycloak traduz OIDC→SAML Evita SAML directo no Entra ID

6. Multi-Tenant e B2B

O Entra ID suporta dois padrões de multi-tenancy para federação SAML: multi-tenant applications (uma aplicação serve múltiplos tenants) e Entra B2B (utilizadores externos convidados para o tenant).

Multi-tenant Applications

Para SaaS providers que servem múltiplas organizações, a App Registration é configurada como multi-tenant. Cada tenant cria o seu próprio Service Principal com claims e SSO específicos. O fluxo SAML multi-tenant funciona com IdP-initiated ou SP-initiated, mas requer que o Issuer (Entity ID) seja único por tenant.

# App Registration multi-tenant
# No portal: New registration → Supported account types
#   ◦ Accounts in any organizational directory (Any Entra ID tenant - Multitenant)
#
# Para SAML SSO multi-tenant, cada tenant configura:
#   - Entity ID único (ex: https://app.exemplo.com/tenant-contoso)
#   - Reply URL específica por tenant
#   - Claims mapping por tenant (atributos podem diferir)
#
# Verificar configuração multi-tenant via Graph:
Get-MgApplication -ApplicationId "app-obj-id" | Select-Object DisplayName, SignInAudience
# SignInAudience deve ser "AzureADMultipleOrgs"

Entra B2B Collaboration

O Entra B2B permite convidar utilizadores externos (de outros tenants Entra ID ou de IdPs federados) como utilizadores convidados. Estes utilizadores autenticam-se no seu IdP de origem, mas recebem acesso a aplicações no tenant anfitrião. O fluxo B2B com federação SAML é especialmente útil para parceiros que já têm um IdP próprio (Keycloak, Okta, AD FS).

Funcionalidade Multi-tenant App B2B Collaboration
Quem cria a identidade Tenant de origem do utilizador Tenant de origem (guest)
Onde reside a conta Tenant de origem Tenant anfitrião (como guest)
Acesso a apps Apps no próprio tenant Apps no tenant anfitrião
Conditional Access Tenant de origem Tenant anfitrião

A escolha entre multi-tenant e B2B depende do controlo necessário: multi-tenant dá autonomia a cada organização; B2B dá controlo centralizado ao tenant anfitrião sobre políticas de acesso e Conditional Access.

7. Erros Comuns e Lista de Verificação

A configuração SAML tem vários pontos de falha. Seguem-se os erros mais frequentes e uma lista de verificação para resolver problemas.

Erros mais comuns

Problema Causa Solução
AADSTS50158 Utilizador não atribuído à app Atribuir utilizador/grupo na app
AADSTS75005 SAML request malformado Verificar Reply URL e Entity ID
Certificado expirado Cert SAML não renovado Renovar e actualizar na app
Claims em falta Mapeamento não configurado Adicionar claims em Attributes & Claims
NameID mismatch Formato NameID errado Verificar formato esperado pela app 
# Diagnosticar erros SAML com Registos de início de sessão
# Entra ID → Monitoring & health → Registos de início de sessão
# Filtrar por: Application = [nome da app]
# Verificar coluna "Status" → detalhes do erro
#
# Via Graph PowerShell:
Get-MgAuditLogSignIn -Filter "appId eq 'app-id-here'" -Top 10 | 
    Select-Object CreatedDateTime, Status, ErrorDescription

Lista de verificação final

  • ✓ Entity ID (Identifier) corresponde exactamente ao configurado na aplicação
  • ✓ Reply URL (ACS) é HTTPS e corresponde ao endpoint da aplicação
  • ✓ Certificado de assinatura SAML não expira nos próximos 30 dias
  • ✓ Utilizadores ou grupos atribuídos à enterprise application
  • ✓ Claims necessárias configuradas (email, role, department conforme app)
  • ✓ Formato Name ID correcto (email, UPN ou unspecified)
  • ✓ Conditional Access aplicado à app (MFA, localização, dispositivo)
  • ✓ Federation Metadados XML actualizada na aplicação
  • ✓ Registos de início de sessão sem erros para pelo menos um utilizador de teste
  • ✓ Keycloak broker (se aplicável): mapeamento de claims IdP → realm configurado

A federação SAML entre Entra ID e aplicações externas é uma peça fundamental da estratégia de identidade moderna. Com SSO bem configurado, os utilizadores ganham produtividade, a equipa de TI centraliza o controlo, e a segurança aumenta com MFA e Conditional Access aplicados uniformemente. No próximo dia exploraremos a governação de identidade e Privileged Identity Management (PIM).

Artigos Relacionados

Artigo publicado no âmbito do Curso M365 para SysAdmins — kbase.pt