Pular para o conteúdo principal
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
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

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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.