Configuração SSO OAuth/OIDC

Scale Plano

Configure o OAuth 2.0 ou OpenID Connect (OIDC) para logon único. Uma alternativa moderna ao SAML para provedores de identidade nativos em nuvem.

SAML vs OAuth/OIDC

Recurso	SAML	OAuth/OIDC
Protocolo	Baseado em XML	JSON/REST
Formato de token	Asserção XML	JWT
Melhor para	IdPs corporativos	Aplicativos em nuvem
Complexidade de configuração	Maior	Menor

Provedores suportados

Provedor	Protocolo
Microsoft Entra ID (Azure AD)	OIDC
Okta	OIDC
Auth0	OIDC
Keycloak	OIDC
Personalizado	OAuth 2.0 / OIDC

Configuração Zenovay OAuth/OIDC

Redirect URI

Seu provedor de identidade precisará deste redirect URI:

Configuração	Valor
Redirect URI / Callback URL	https://auth.zenovay.com/api/sso/oauth/callback

Você pode copiar este valor (e os equivalentes SAML) diretamente em Configurações → Segurança → SSO, sob Detalhes do Fornecedor de Serviços.

Escopos necessários

Zenovay requer estes escopos:

openid
email
profile

Escolhendo entre OAuth 2.0 e OpenID Connect

Recurso	OAuth 2.0	OpenID Connect
Verificação do token de identidade	Não aplicável	Automática via JWKS
Campos necessários	Client ID, Client Secret, Issuer, Authorization URL, Token URL, Userinfo URL	Client ID, Client Secret, Issuer, Metadata URL
Melhor para	IdPs sem suporte OIDC	IdPs modernos (Okta, Entra ID, Auth0, Keycloak)

Com OIDC você fornece a URL de Metadados (o documento .well-known/openid-configuration do seu IdP) e o Zenovay lê os pontos finais de autorização, token, userinfo e JWKS a partir dele. Com OAuth 2.0 puro você insere cada URL de ponto final você mesmo.

Configuração Microsoft Entra ID OIDC

Etapa 1: Registrar aplicativo

1. Faça login no centro de administração Microsoft Entra
2. Vá para Identidade → Aplicativos → Registros de aplicativo
3. Clique em Novo registro
4. Configure:

Campo Entra ID	Valor
Nome	Zenovay
Tipos de conta suportados	Contas apenas neste diretório organizacional
Redirect URI	Web — https://auth.zenovay.com/api/sso/oauth/callback

5. Clique em Registrar

Etapa 2: Criar segredo do cliente

1. Vá para Certificados e segredos
2. Clique em Novo segredo do cliente
3. Defina descrição e expiração
4. Copie o valor secreto imediatamente (não será mostrado novamente)

Etapa 3: Anotar detalhes do aplicativo

Registre estes valores:

• ID de aplicativo (ID do cliente) — da página Visão geral
• Client Secret — da Etapa 2
• Tenant ID — da página Visão geral

Etapa 4: Permissões de API

1. Vá para Permissões de API
2. Verifique se Microsoft Graph → User.Read (delegado) está listado
3. Caso contrário, clique em Adicionar uma permissão → Microsoft Graph → Permissões delegadas → User.Read

Etapa 5: Configurar no Zenovay

1. No Zenovay, vá para Configurações → Segurança → SSO
2. Clique em Adicionar provedor e selecione OpenID Connect
3. Digite:
   • Nome do provedor: por exemplo, "Microsoft Entra ID"
   • Client ID: o ID de aplicativo (ID do cliente) da Etapa 3
   • Client Secret: o valor secreto da Etapa 2
   • Issuer: https://login.microsoftonline.com/{seu-id-tenant}/v2.0
   • Metadata URL: https://login.microsoftonline.com/{seu-id-tenant}/v2.0/.well-known/openid-configuration
4. Clique em Criar
5. Adicione e verifique seu domínio de email
6. Teste a conexão

Configuração Okta OIDC

Etapa 1: Criar aplicativo

1. Vá para o Console de administração Okta → Aplicativos
2. Clique em Criar integração de aplicativo
3. Selecione OIDC - OpenID Connect
4. Selecione Aplicativo Web
5. Clique em Próximo

Etapa 2: Configurar aplicativo

Campo Okta	Valor
Nome de integração do aplicativo	Zenovay
Tipo de concessão	Código de autorização
URIs de redirecionamento de logon	https://auth.zenovay.com/api/sso/oauth/callback

Etapa 3: Atribuir usuários

1. Vá para a guia Atribuições
2. Atribua usuários ou grupos
3. Salvar

Etapa 4: Obter credenciais

Na guia Geral, anote:

• Client ID
• Client Secret

Etapa 5: Obter Issuer e URLs de metadados

1. Vá para Segurança → API no Console de administração Okta
2. Encontre seu servidor de autorização (geralmente "default")
3. O Issuer URI terá este aspecto: https://sua-org.okta.com/oauth2/default
4. A URL de metadados correspondente é o Issuer URI mais /.well-known/openid-configuration, por exemplo: https://sua-org.okta.com/oauth2/default/.well-known/openid-configuration

Etapa 6: Configurar no Zenovay

1. Vá para Configurações → Segurança → SSO
2. Clique em Adicionar provedor e selecione OpenID Connect
3. Digite:
   • Nome do provedor: por exemplo, "Okta"
   • Client ID: da Etapa 4
   • Client Secret: da Etapa 4
   • Issuer: o Issuer URI da Etapa 5
   • Metadata URL: a URL de descoberta da Etapa 5
4. Clique em Criar
5. Adicione e verifique seu domínio de email
6. Teste a conexão

Configuração Auth0

Etapa 1: Criar aplicativo

1. Vá para Painel Auth0
2. Vá para Aplicativos → Criar aplicativo
3. Escolha Aplicativos Web Convencionais
4. Clique em Criar

Etapa 2: Configurar configurações

Na guia Configurações:

Campo Auth0	Valor
URLs de retorno de chamada permitidas	https://auth.zenovay.com/api/sso/oauth/callback

Clique em Salvar mudanças.

Etapa 3: Obter credenciais

Na guia Configurações, anote:

• Domínio (por exemplo, seu-tenant.us.auth0.com)
• Client ID
• Client Secret

Etapa 4: Configurar no Zenovay

1. Vá para Configurações → Segurança → SSO
2. Clique em Adicionar provedor e selecione OpenID Connect
3. Digite:
   • Nome do provedor: por exemplo, "Auth0"
   • Client ID: da Etapa 3
   • Client Secret: da Etapa 3
   • Issuer: https://seu-tenant.us.auth0.com/ (incluir barra final)
   • Metadata URL: https://seu-tenant.us.auth0.com/.well-known/openid-configuration
4. Clique em Criar
5. Adicione e verifique seu domínio de email
6. Teste a conexão

Google Workspace

Se você especificamente precisa de OIDC com Google, você pode criar credenciais OAuth no Console da Google Cloud:

1. Vá para Google Cloud Console → APIs e Serviços → Credenciais
2. Clique em Criar credenciais → ID de cliente OAuth
3. Selecione Aplicativo web e digite https://auth.zenovay.com/api/sso/oauth/callback como o redirect URI
4. Anote o Client ID e o Client Secret
5. No Zenovay, adicione um provedor OpenID Connect com Issuer https://accounts.google.com e Metadata URL https://accounts.google.com/.well-known/openid-configuration

Provedor OIDC personalizado

Se seu provedor de identidade suporta a descoberta do OpenID Connect:

1. Vá para Configurações → Segurança → SSO
2. Clique em Adicionar provedor e selecione OpenID Connect
3. Digite:
   • Nome do provedor: o nome do seu provedor
   • Client ID: do seu IdP
   • Client Secret: do seu IdP
   • Issuer: a URL do issuer do seu IdP (por exemplo, https://seu-idp.com)
   • Metadata URL: seu documento de descoberta de IdP, geralmente a URL do issuer mais /.well-known/openid-configuration
4. Clique em Criar

O Zenovay lê automaticamente os pontos finais de autorização, token, userinfo e JWKS do seu IdP a partir do documento de metadados, então você não precisa inseri-los individualmente.

Provedor OAuth 2.0 personalizado

Se seu provedor de identidade não suporta descoberta automática OIDC, use OAuth 2.0 com configuração manual de ponto final:

1. Vá para Configurações → Segurança → SSO
2. Clique em Adicionar provedor e selecione OAuth 2.0
3. Digite:
   • Nome do provedor: o nome do seu provedor
   • Client ID: do seu IdP
   • Client Secret: do seu IdP
   • Authorization URL: o ponto final de autorização do seu IdP
   • Token URL: o ponto final de token do seu IdP
   • Userinfo URL: o ponto final de informações do usuário do seu IdP
4. Clique em Criar

Completando a configuração

Verificar domínio

Após salvar seu provedor SSO, vincula os domínios de email com os quais sua equipe faz login para que o Zenovay saiba direcioná-los através de SSO:

1. Na seção Verificação de domínio, insira seu domínio de email (por exemplo, empresa.com) e clique em Verificar domínio
2. Zenovay retorna um registro TXT de DNS (host e valor) — adicione-o em seu provedor de DNS
3. Clique em Verificar DNS uma vez que o registro tenha se propagado
4. Uma vez verificado, os usuários com esse domínio de email serão direcionados para SSO

Testar conexão

Você pode executar uma verificação rápida antes de habilitar o provedor:

1. Abra o menu de ações do provedor (o botão ⋯ na linha do provedor)
2. Clique em Testar conexão
3. Um toast de sucesso confirma que Zenovay pode alcançar seu IdP com as credenciais configuradas

Você também pode confirmar o fluxo de ponta a ponta manualmente:

1. Abra uma janela do navegador incógnito/privada
2. Vá para auth.zenovay.com
3. Escolha Faça login com SSO e digite um email do seu domínio verificado
4. Autentique-se com seu IdP
5. Verifique se você retorna ao painel Zenovay

Habilitar e aplicar SSO

1. Na linha do provedor, mude a alternância para ativado para habilitar o provedor
2. Para exigir SSO para todos no espaço de trabalho, abra o menu de ações do provedor (⋯) e escolha Aplicar SSO, então confirme

Mapeamento de atributos do usuário

Claims padrão

Reclamação OIDC	Campo Zenovay
email	Endereço de email
given_name	Primeiro nome
family_name	Sobrenome
sub	Identificador único

Provisionamento Just-In-Time

Novos usuários são criados automaticamente no seu primeiro logon SSO bem-sucedido:

• Criação automática de conta do domínio de email verificado
• Nenhum convite necessário

Recursos de segurança

Zenovay aplica automaticamente essas medidas de segurança para OAuth/OIDC:

• PKCE (Proof Key for Code Exchange) — protege a troca do código de autorização
• Parâmetro de estado — previne ataques CSRF
• Validação de Nonce (OIDC) — previne ataques de replay de token
• Verificação do token de identidade (OIDC) — valida tokens usando o ponto final JWKS do IdP

Solução de problemas

Erros comuns

Erro	Causa	Solução
Invalid redirect_uri	Desajuste de URL	Certifique-se de que o redirect URI é exatamente https://auth.zenovay.com/api/sso/oauth/callback
Invalid client_id	Credencial errada	Verifique o ID de cliente no seu painel do IdP
Invalid grant	Código expirado	Tente novamente — códigos de autorização têm vida curta
Token verification failed	Falha de assinatura	Verifique se o ponto final JWKS está acessível
State parameter mismatch	Problema de sessão	Limpe cookies e tente em uma janela incógnita
OIDC discovery failed	Problema de URL de metadados	Abra {metadata-url} no seu navegador e confirme que retorna o documento .well-known/openid-configuration

Problemas de certificado

Se JWKS falhar:

• Verifique se a URL JWKS está acessível
• Verifique se o certificado SSL é válido
• Verifique bloqueios de firewall

Considerações de segurança

Gerenciamento de segredos

• Armazene o segredo do cliente com segurança
• Rotacione os segredos antes de expirarem
• Nunca exponha segredos em código do lado do cliente

Limitações de escopo

Solicite escopos mínimos:

• Apenas openid, email, profile
• Não solicite acesso desnecessário

Validação de Redirect URI

• Use validação de correspondência exata em seu IdP
• Não use caracteres curinga
• HTTPS necessário

Próximas etapas

• Aplicar MFA para todos os usuários
• Configurar log de auditoria
• Políticas de senha personalizadas