SSO SAML
Configure o login corporativo com validação cuidadosa de metadados, atributos e usuários de teste.
Visão geral
Organizações podem usar SSO SAML via provedor de identidade corporativo quando esse recurso estiver contratado e configurado.
O fluxo pode incluir descoberta por domínio, redirecionamento para o provedor corporativo e provisionamento automático de usuários.
Fluxo esperado:
- o usuário informa o e-mail corporativo no XGuardian;
- o XGuardian identifica o domínio do e-mail;
- o login é redirecionado para o provedor de identidade configurado;
- o usuário autentica no provedor corporativo;
- o XGuardian recebe a resposta SAML;
- quando habilitado, o usuário é provisionado automaticamente com o perfil inicial definido pela organização.
Como configurar uma conexão SSO
O procedimento pode variar conforme o provedor de identidade, como Authentik, Microsoft Entra ID, Okta, Google Workspace, Keycloak ou outro IdP compatível com SAML 2.0. A lógica geral é a mesma: criar uma aplicação SAML no IdP, obter os metadados e cadastrar a conexão no XGuardian.
1. Preparar o provedor de identidade
No provedor corporativo, crie uma aplicação ou provider SAML para o XGuardian.
Configure os dados do Service Provider conforme os valores fornecidos pelo XGuardian para o ambiente da organização:
| Campo no IdP | Orientação |
|---|---|
| ACS URL / Reply URL | URL de resposta SAML do XGuardian para o ambiente. |
| Entity ID / Issuer / Audience | Identificador do XGuardian como Service Provider. |
| Binding | Use HTTP POST quando solicitado pelo provedor. |
| NameID | Preferencialmente e-mail corporativo do usuário. |
| Certificado de assinatura | Use certificado válido do provedor de identidade. |
Depois da criação, exporte o SAML Metadata XML ou copie a URL de metadata do IdP. Esse dado será usado na configuração do XGuardian.
2. Validar usuários e atributos no IdP
Antes de testar o login, confirme que o usuário existe no provedor de identidade e possui e-mail corporativo preenchido corretamente.
Valide também se o IdP envia os atributos esperados na resposta SAML:
| Atributo | Uso no XGuardian |
|---|---|
| Identificação do usuário e domínio usado no discovery. | |
| Primeiro nome | Apoia criação e exibição do usuário provisionado. |
| Sobrenome | Apoia criação e exibição do usuário provisionado. |
| Grupos ou papéis | Podem depender da configuração e do suporte disponível no ambiente. |
3. Criar a conexão no XGuardian
No XGuardian, um Admin autorizado deve:
- acessar Settings ou Configurações;
- abrir a área SSO;
- selecionar Nova Conexão;
- informar o nome do provedor;
- informar o domínio corporativo real da organização;
- inserir o SAML Metadata XML ou a URL de metadata do IdP;
- revisar os mapeamentos de atributos do usuário;
- criar a conexão.
Campos importantes:
| Campo | Como preencher |
|---|---|
| Provider Name | Nome identificável do provedor, sem depender de placeholders. Exemplo: Empresa-EntraID, Empresa-Okta ou Empresa-Authentik. |
| Domínio | Domínio real do e-mail corporativo, como empresa.com.br. É usado para direcionar o login ao IdP correto. |
| SAML Metadata XML / URL | Metadata exportado pelo provedor de identidade. |
| Field mappings | Atributos que o IdP envia para e-mail, primeiro nome e sobrenome. |
Campos como Entity ID, ACS URL e validações de assinatura devem seguir os valores apresentados ou fornecidos pelo XGuardian para o ambiente. Não altere esses dados sem validação técnica.
Guia visual: criar conexão SSO SAML
Use este fluxo quando a organização já tiver os dados do provedor de identidade e precisar cadastrar a conexão no XGuardian.
4. Testar o login
Teste o SSO antes de liberar para todos os usuários:
- abra uma janela anônima do navegador;
- acesse o XGuardian;
- selecione login com SSO;
- informe um e-mail do domínio configurado;
- confirme o redirecionamento para o IdP;
- autentique com um usuário de teste;
- valide o retorno ao XGuardian e o perfil provisionado.
Use janela anônima para evitar que sessões já abertas no provedor de identidade mascarem falhas de configuração.
Boas práticas:
- valide o domínio corporativo usado para discovery;
- revise o perfil padrão de usuários provisionados automaticamente;
- mantenha menor privilégio como padrão;
- teste login tradicional, login SSO e recuperação de acesso em ambiente controlado;
- alinhe desativação de usuários com o processo interno de identidade da organização.
Pré-requisitos comuns para configuração de SSO:
| Item | Observação |
|---|---|
| Domínio corporativo | Usado para discovery e roteamento do login. |
| Metadados SAML | Informações do provedor de identidade necessárias para configurar a federação. |
| Atributos do usuário | E-mail, nome e identificadores usados no provisionamento. |
| Perfil padrão | Papel inicial de usuários provisionados automaticamente. |
| Usuários de teste | Contas para validar login, logout e falhas antes de ampliar o uso. |
| Plano de contingência | Caminho de suporte caso o provedor de identidade fique indisponível. |
Erros comuns em SSO
| Sintoma | Causa provável | Ação recomendada |
|---|---|---|
| Usuário não é redirecionado ao IdP | Domínio do e-mail não corresponde ao domínio cadastrado no XGuardian. | Revisar o campo Domínio na conexão SSO. |
| Login falha após autenticação | Metadata, ACS, Entity ID ou assinatura não estão alinhados. | Conferir configuração do IdP e os dados fornecidos pelo XGuardian. |
| Usuário provisionado sem dados corretos | Mapeamento de atributos aponta para claims incorretas. | Validar os atributos enviados na asserção SAML e ajustar os mappings. |
| IdP informa credencial inválida | Usuário, senha, política ou atribuição à aplicação no IdP estão incorretos. | Revisar usuário, credenciais, grupos e permissões no provedor corporativo. |
| Usuário autentica no IdP, mas não acessa o XGuardian | Usuário não está autorizado à aplicação SAML no IdP ou perfil inicial não foi provisionado como esperado. | Validar atribuição do usuário/grupo à aplicação XGuardian e revisar provisionamento. |