Solução de Problemas de SSO

Este guia aborda problemas comuns que você pode encontrar ao configurar ou usar Single Sign-On com Zenovay, junto com suas soluções.

Erros SAML 2.0

"SAML signature verification failed"

Causa: O certificado X.509 em Zenovay não corresponde ao certificado que seu provedor de identidade usou para assinar a resposta SAML.

Solução:

1. Baixe uma cópia nova do certificado de assinatura do seu IdP
2. No Zenovay, acesse Settings → Security → SSO
3. Edite o provedor SAML e substitua o certificado
4. Certifique-se de que você copiou o certificado completo, incluindo -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----

"SAML digest mismatch"

Causa: A resposta SAML foi modificada em trânsito ou o certificado errado está configurado.

Solução:

1. Verifique se o certificado em Zenovay corresponde ao certificado de assinatura ativo no seu IdP
2. Se seu IdP rotacionou certificados recentemente, baixe o novo
3. Certifique-se de que não há proxies ou middleware modificando a resposta SAML

"Referenced element not found"

Causa: A resposta SAML não contém o elemento assinado esperado.

Solução:

1. Verifique se seu IdP está enviando uma resposta SAML 2.0 padrão
2. Verifique que a resposta inclui um elemento Assertion com um atributo ID válido
3. Entre em contato com o administrador do seu IdP se o problema persistir

"Entity ID mismatch" ou "Audience mismatch"

Causa: O SP Entity ID configurado no seu IdP não corresponde ao que Zenovay espera.

Solução:

• Configure o SP Entity ID / Audience URI no seu IdP exatamente para: https://auth.zenovay.com
• Não inclua uma barra final ou nenhum caminho

"Invalid ACS URL" ou "Reply URL mismatch"

Causa: A URL de ACS no seu IdP não corresponde ao endpoint de callback do Zenovay.

Solução:

• Configure a URL de ACS exatamente para: https://auth.zenovay.com/api/sso/saml/callback
• Certifique-se de que não há barra final

"NameID not found" ou "Email not provided"

Causa: A resposta SAML não contém o endereço de e-mail do usuário no formato esperado.

Solução:

1. Configure o NameID format para EmailAddress no seu IdP
2. Certifique-se de que o NameID value mapeia para o endereço de e-mail do usuário
3. Verifique se o usuário tem um endereço de e-mail válido no diretório do seu IdP

Erros OAuth 2.0 / OIDC

"Invalid redirect URI" ou "Redirect URI mismatch"

Causa: A URI de redirecionamento configurada no seu IdP não corresponde ao que Zenovay envia.

Solução:

• Configure a URI de redirecionamento exatamente para: https://auth.zenovay.com/api/sso/oauth/callback
• Certifique-se de que não há barra final
• A URI deve ser uma correspondência exata (sensível a maiúsculas e minúsculas)

"Invalid client credentials"

Causa: O ID do Cliente ou o Segredo do Cliente inserido em Zenovay está incorreto.

Solução:

1. Verifique o ID do Cliente e o Segredo do Cliente no painel do seu IdP
2. Se o segredo expirou, gere um novo
3. Atualize os valores em Zenovay

"OIDC discovery failed"

Causa: Zenovay não consegue acessar o endpoint de descoberta do OpenID Connect na sua URL do Emissor.

Solução:

1. Verifique se a URL do Emissor está correta
2. Teste a URL de descoberta no seu navegador: {issuer-url}/.well-known/openid-configuration
3. Alguns IdPs requerem uma barra final na URL do Emissor (por exemplo, Auth0: https://tenant.us.auth0.com/)
4. Certifique-se de que seu IdP está acessível publicamente

"Token verification failed"

Causa: O token de ID do seu IdP não pôde ser verificado.

Solução:

1. Certifique-se de que o endpoint JWKS do seu IdP está acessível
2. Verifique se o algoritmo de assinatura do token corresponde ao que seu IdP anuncia
3. Verifique se a reivindicação aud (audience) no token corresponde ao ID do Cliente

"State parameter mismatch"

Causa: O estado de autenticação foi perdido ou adulterado, normalmente devido a problemas de sessão.

Solução:

1. Limpe os cookies do navegador e tente novamente
2. Certifique-se de que você não está usando uma extensão de navegador que bloqueia cookies
3. Tente em uma janela anônima/privada

Problemas de Verificação de Domínio

"Domain not verified"

Causa: Seu domínio de e-mail não foi verificado para SSO.

Solução:

1. Acesse Settings → Security → SSO
2. Clique no seu provedor de SSO
3. Clique em Add Domain e insira seu domínio de e-mail
4. Siga as etapas de verificação de DNS
5. Aguarde o tempo de propagação do DNS (até 48 horas)

"Domain already in use"

Causa: O domínio de e-mail já está vinculado a outro provedor de SSO ou organização.

Solução:

1. Verifique se outro provedor de SSO em sua organização já usa este domínio
2. Remova o domínio do outro provedor primeiro
3. Se o domínio estiver vinculado a uma organização diferente, entre em contato com [email protected]

Problemas de Certificado

Expiração do Certificado

Certificados de assinatura SAML têm uma data de expiração. Quando expiram, a autenticação via SSO falhará.

Como verificar:

1. Verifique a data de expiração do certificado no painel do seu IdP
2. Configure um lembrete de calendário 30 dias antes da expiração

Como atualizar:

1. Baixe o novo certificado do seu IdP
2. No Zenovay, edite o provedor de SSO
3. Substitua o certificado e salve
4. Teste a conexão

Formato do Certificado

Zenovay espera o certificado X.509 em formato PEM:

-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
(base64 encoded certificate data)
...
-----END CERTIFICATE-----

• Inclua as linhas BEGIN e END
• Não inclua espaço em branco extra ou cabeçalhos
• Se seu IdP fornecer um arquivo .cer ou .der, converta-o para o formato PEM primeiro

Problemas Gerais

"SSO provider not found"

Causa: O domínio de e-mail inserido no login não corresponde a nenhum provedor de SSO configurado.

Solução:

1. Verifique se o domínio foi adicionado e verificado no provedor de SSO em Zenovay
2. Certifique-se de que o usuário está inserindo um e-mail com o domínio correto

Usuários Não Conseguem Fazer Login Após a Imposição de SSO

Causa: SSO está imposto, mas os usuários não conseguem se autenticar com o IdP.

Solução:

1. Desabilite temporariamente a imposição de SSO em Settings → Security → SSO
2. Faça login com e-mail/senha para acessar as configurações
3. Corrija a configuração de SSO
4. Reabilite a imposição

Novos Usuários Não Sendo Criados

Causa: O usuário existe no seu IdP, mas não tem uma conta Zenovay.

Solução: Zenovay provisiona automaticamente novas contas de usuário no primeiro login via SSO. Se isso não estiver acontecendo:

1. Verifique se a resposta SAML ou token OIDC inclui o endereço de e-mail do usuário
2. Verifique se o domínio de e-mail corresponde ao domínio verificado
3. Certifique-se de que o usuário está atribuído à aplicação Zenovay no seu IdP

Checklist de Testes

Antes de impor SSO, verifique:

• Provedor de SSO está configurado em Zenovay com os valores corretos do IdP
• Domínio de e-mail está verificado
• Usuários estão atribuídos à aplicação no seu IdP
• Login de teste funciona em uma janela anônima
• Provisionamento de novo usuário funciona (teste com um usuário que ainda não tem uma conta Zenovay)
• Pelo menos um Proprietário ainda pode fazer login por e-mail/senha como backup

Obtenha Ajuda

Se você ainda está enfrentando problemas:

• E-mail: [email protected]
• Enterprise Support: [email protected]

Ao contactar o suporte, inclua:

1. Nome do seu provedor de identidade e protocolo (SAML/OAuth/OIDC)
2. A mensagem de erro exata que você vê
3. Se esta é uma nova configuração ou uma existente que parou de funcionar
4. Quaisquer alterações recentes na configuração do seu IdP