Pular para o conteúdo principal

Solução de Problemas e Referência SSO

Este artigo cobre permissões, valores de referência rápida e soluções para problemas comuns de SSO. Para instruções de configuração, consulte o Guia de Configuração de Metadados SSO.

Permissões​

Todas as ações de gerenciamento de metadados SSO são restritas a Super Admins, com uma exceção: um administrador de equipe pode carregar metadados do IdP via arquivo para o domínio da sua própria equipe.

AçãoFunção Necessária
Visualizar a aba de Metadados SSOSuper Admin
Carregar metadados do IdP via arquivo (POST /admin/saml-metadata/upload)Super Admin, ou um administrador de equipe cujo sso_domain corresponda ao email_domain da sua equipe
Carregar metadados do IdP via XML colado (POST /admin/saml-metadata/upload-text)Apenas Super Admin
Baixar metadados armazenados (GET /admin/saml-metadata/download)Super Admin
Excluir metadados armazenados (DELETE /admin/saml-metadata/delete)Super Admin
Nota

O endpoint de metadados SP em /saml/well-known/sp-metadata é público por design. Não contém segredos — apenas o entity ID do SP, URL ACS, formato NameID e certificado público de assinatura.

Referência Rápida​

Host do Backend

<your-backend-host> (por exemplo, ek-api.corp.acme.com)

Processa todo o tráfego SAML — metadados SP, iniciação SSO e o endpoint ACS. Este é o único host que seu IdP precisa conhecer.

Host do Frontend

<your-frontend-host> (por exemplo, ek.corp.acme.com)

A interface web que seus usuários abrem. Configurado no backend via FRONTEND_ROOT_URL. Nunca aparece na configuração do IdP.

URL de Metadados SP
https://<your-backend-host>/saml/well-known/sp-metadata

Compartilhe isso com seu administrador de IdP para registrar o EK como uma aplicação SAML.

URL ACS
https://<your-backend-host>/user/generic/sso/saml/acs/admin

Onde seu IdP faz POST nas respostas SAML. Sempre o host do backend — nunca o frontend.

Ponto de Entrada SSO Iniciado pelo SP
https://<your-backend-host>/sso/login?enterprise_id=<email-domain>

O endpoint do backend para o qual o frontend redireciona quando um usuário inicia o SSO.

Formato NameID Necessário
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Seu IdP deve enviar o endereço de e-mail do usuário neste formato.

Variáveis de Ambiente do Modo de SSO do Frontend​

VariávelDescrição
VITE_ALLOW_ONLY_SSO_LOGINtrue para SSO de clique único, false (padrão) para SSO com modal de e-mail.
VITE_SSO_ENTERPRISE_IDApenas modo de clique único. Deve corresponder a um domínio que tenha metadados do IdP carregados na aba SSO Metadata.
  • Onde carregar metadados do IdP? Painel do Super Admin → aba SSO Metadata → Add Metadata / Update
  • Um documento por domínio. Recarregar substitui os metadados existentes. Excluir desabilita o SSO para aquele domínio.
  • Função necessária? Super Admin para todas as ações, exceto administradores de equipe podem carregar via arquivo para o domínio da sua própria equipe.

Solução de Problemas​

Erro "Please enter a valid domain"

O campo SSO Team Email Domain espera um domínio simples como acme.com ou eu.acme.co.uk. Remova qualquer @, https://, caminhos ou números de porta antes de enviar.

Erro "File must be an XML file"

O carregador de arquivos aceita apenas arquivos com extensão .xml. Se seu IdP forneceu os metadados como um arquivo .txt ou sem extensão, renomeie-o para .xml ou mude para a opção Paste XML Content.

Erro "Content does not appear to be valid XML"

Ao usar Paste XML Content, o conteúdo colado deve começar com <?xml ou < após remover espaços em branco. Certifique-se de que você copiou o documento de metadados completo e que nenhum preâmbulo ou comentário foi incluído.

Login é bem-sucedido com o IdP, mas o EK rejeita a asserção

Isso é quase sempre causado por um dos seguintes:

  • Incompatibilidade de certificado — o certificado de assinatura do IdP nos metadados carregados não corresponde mais ao certificado que o IdP está realmente usando. Isso tipicamente acontece após uma rotação de certificado do IdP. Obtenha metadados novos do seu administrador de IdP e use Update.
  • Formato NameID incorreto — o IdP não está enviando o endereço de e-mail como o NameID. Confirme que o formato está definido como urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress no lado do IdP.
  • Incompatibilidade de Entity ID — a audiência ou Entity ID configurada no seu IdP não corresponde ao Entity ID da sua instância EK. Recompartilhe o XML de metadados SP do EK e peça ao seu administrador de IdP para reimportá-lo.
Usuário faz login com sucesso, mas tem o acesso negado

Isso é controlado por Super Admin → Access Controls, não pela aba SSO Metadata. Consulte o guia Controles de Acesso SAML para detalhes sobre Allow Any New Users vs Restrict to SAML Metadata e regras de atribuição automática de equipe/projeto.

SSO iniciado pelo IdP não está funcionando

Por padrão, o EK apenas aceita respostas SAML iniciadas a partir de seu próprio endpoint /sso/login — significando SSO iniciado pelo SP apenas. Para habilitar SSO iniciado pelo IdP (não solicitado), o operador on-premise deve definir ALLOW_IDP_INITIATED_SSO=true no backend EK e reiniciar o serviço. Esta é uma configuração de nível de implantação, não algo configurável na aba SSO Metadata.

IdP configurado com o host do frontend em vez do host do backend

Se a aplicação do IdP foi configurada com o hostname do frontend do EK para a URL ACS ou Entity ID, as respostas SAML serão enviadas para o serviço errado e a autenticação falhará silenciosamente — geralmente exibindo um 404 ou uma página de erro genérica após a tela de login do IdP.

Peça ao seu administrador de IdP para confirmar que:

  • A URL ACS é https://<your-backend-host>/user/generic/sso/saml/acs/admin.
  • O Entity ID / Audience corresponde ao entityID em https://<your-backend-host>/saml/well-known/sp-metadata.

O host do frontend nunca deve aparecer na configuração da aplicação SAML do IdP.

Botão de SSO de clique único não faz nada (ou mostra "Could not determine domain for SSO login")

VITE_SSO_ENTERPRISE_ID não está definido no frontend. Defina-o para o domínio de e-mail para o qual você carregou metadados do IdP, depois reimplante ou reinicie o frontend para que o valor tenha efeito.

Botão de SSO de clique único redireciona, mas o SSO falha no backend

VITE_SSO_ENTERPRISE_ID está definido, mas não corresponde a nenhum domínio com metadados carregados na aba SSO Metadata. Corrija isso:

  • Carregando metadados do IdP para o domínio atualmente em VITE_SSO_ENTERPRISE_ID — recomendado, pois mantém sua configuração do frontend inalterada.
  • Atualizando VITE_SSO_ENTERPRISE_ID para corresponder a um domínio que já tenha metadados carregados, depois reimplantando ou reiniciando o frontend.

Os dois valores devem corresponder exatamente (insensível a maiúsculas/minúsculas).

SSO com modal de e-mail mostra "Your organization is not configured for SSO login"

O domínio de e-mail do usuário não tem metadados do IdP carregados na aba SSO Metadata. Carregue metadados para aquele domínio, ou peça ao usuário para fazer login usando e-mail/senha ou OAuth.

Usuários completam o SSO, mas caem na página errada ou recebem erro de redirecionamento

Após uma resposta SAML bem-sucedida, o EK redireciona o usuário para a URL do frontend definida por FRONTEND_ROOT_URL no backend. Se esta variável não estiver definida, apontar para o host errado, ou usar o esquema ou porta errados, o usuário parecerá finalizar a autenticação, mas cairá em uma página quebrada.

Peça ao seu operador on-premise para confirmar que FRONTEND_ROOT_URL corresponde exatamente a https://<your-frontend-host> — esquema correto, porta correta, sem problemas de barra final.