SSO SAML — Azure AD / Entra
Guia de configuração para Single Sign-On via protocolo SAML 2.0 com Azure Active Directory / Microsoft Entra ID.
Visão geral
O protocolo SAML 2.0 permite que colaboradores façam login na Plataforma Fhinck usando as credenciais corporativas do Azure AD / Microsoft Entra, sem criar senhas adicionais. O fluxo é iniciado pelo Service Provider (Fhinck) ou pelo Identity Provider (Azure AD).
O que o cliente fornece
| Item | Descrição | Onde obter |
|---|---|---|
| Tenant ID | Identificador do diretório Azure AD. | Azure Portal → Azure Active Directory → Visão Geral |
| App Registration | Registro do aplicativo Fhinck no Azure AD. | Criado pelo admin Azure durante o setup |
| Certificate (X.509) | Certificado de assinatura SAML da federação. | Azure Portal → Enterprise Applications → Fhinck → SSO → Certificado |
| Claims mapping | Mapeamento de atributos: email, nome, grupos. | Configurado no App Registration pelo admin |
| NameID format | Formato do identificador do usuário. Recomendado: emailAddress. | Configurado nas Claims da Enterprise Application |
O que a Fhinck fornece
| Item | Valor |
|---|---|
| SP Entity ID | Fornecido pelo time Fhinck após abertura do chamado. |
| ACS URL | Assertion Consumer Service URL — fornecida pelo time Fhinck. |
| Metadata XML | Arquivo XML com todos os metadados do SP — fornecido pelo time Fhinck. |
Fluxo de configuração
Abertura de chamado
Entre em contato com o time Fhinck via contato@fhinck.com solicitando a configuração de SSO SAML. Informe o Tenant ID do Azure AD.
Fhinck envia os metadados do SP
O time Fhinck envia o SP Entity ID, a ACS URL e o arquivo Metadata XML para configuração no Azure AD.
Admin Azure configura a Enterprise Application
No Azure Portal, cria-se uma Enterprise Application do tipo SAML, configurando o SP Entity ID, ACS URL e o mapeamento de claims (email, displayName, groups).
Cliente envia o certificado e metadados do IdP
O admin do Azure exporta o certificado X.509 e o arquivo Federation Metadata XML do Azure AD e envia para o time Fhinck.
Teste e validação
O time Fhinck configura o IdP na plataforma e valida o fluxo de login com um usuário de teste. Em homologação antes de promover para produção.
Claims necessárias
| Claim | Atributo Azure AD | Obrigatório |
|---|---|---|
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | user.mail | Sim |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | user.givenname | Recomendado |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | user.surname | Recomendado |
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups | user.groups | Opcional |
Troubleshooting
InResponseTo invalid
Causa: O campo InResponseTo da resposta SAML não coincide com o ID da requisição AuthnRequest. Geralmente indica replay de sessão ou problema de sincronização de tempo.
Solução: Verifique se os servidores do cliente e da Fhinck estão sincronizados via NTP. Certifique-se de que não há caches de sessão SAML no browser do usuário.
Certificate expired
Causa: O certificado de assinatura SAML expirou.
Solução: Renove o certificado no Azure Portal (Enterprise Applications → Fhinck → Single sign-on → SAML Signing Certificate) e envie o novo certificado para o time Fhinck.
Claim missing
Causa: O atributo de email não está sendo enviado na asserção SAML.
Solução: No Azure AD, verifique se a claim emailaddress está mapeada para user.mail na configuração de attributes & claims da Enterprise Application.
NameID format
Causa: O formato de NameID enviado pelo Azure AD não é aceito pela Fhinck.
Solução: Configure o NameID format como urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress na Enterprise Application.