Single Sign-On (SSO)

Single Sign-On permite que seu time entre no Zoen pelo provedor de identidade da empresa em vez de gerenciar senhas separadas. O Zoen suporta OIDC e SAML 2.0.

Setup

1. Abra as settings de SSO

Vá em Settings → Enterprise → Single Sign-On no seu workspace.

2. Escolha um protocolo

ProtocoloUse quando
OIDCSeu IdP suporta OpenID Connect — Okta, Microsoft Entra ID, Auth0, Google Workspace
SAML 2.0Seu IdP é só SAML — ADFS, Shibboleth ou IdPs enterprise mais antigos

3. Preencha o formulário

Campos obrigatórios para ambos os protocolos:

CampoO que informar
Provider IDUm slug curto identificando esta conexão, ex.: okta ou azure-ad. Só letras, números e hífens.
Issuer URLA URL do issuer do provedor de identidade. Precisa ser HTTPS.
DomainO domínio de e-mail da sua organização, ex.: company.com. Usuários com este domínio serão roteados pelo SSO no sign-in.

Campos adicionais OIDC:

CampoO que informar
Client IDO client ID da aplicação no seu IdP.
Client SecretO client secret do seu IdP.
ScopesScopes OIDC separados por vírgula. Padrão: openid,profile,email.

Para OIDC, o Zoen busca automaticamente os endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri) no documento de discovery /.well-known/openid-configuration do seu issuer. Você só precisa fornecer a issuer URL.

Campos adicionais SAML:

CampoO que informar
Entry Point URLA URL do serviço SSO do IdP para onde o Zoen envia requests de autenticação.
Identity Provider CertificateO certificado X.509 codificado em Base-64 do seu IdP para verificar assertions.

4. Copie a Callback URL

A Callback URL mostrada no formulário é o endpoint para o qual seu provedor de identidade deve redirecionar os usuários depois da autenticação. Copie-a e registre-a no seu IdP antes de salvar.

Provedores OIDC (Okta, Microsoft Entra ID, Google Workspace, Auth0):

https://app.zoen.space/api/auth/sso/callback/{provider-id}

Provedores SAML (ADFS, Shibboleth):

https://app.zoen.space/api/auth/sso/saml2/callback/{provider-id}

5. Salve e teste

Clique em Save. Para testar, saia e use o botão Sign in with SSO na página de login. Informe um endereço de e-mail no domínio configurado — o Zoen redirecionará você ao provedor de identidade.

Guias de provedor

Okta (OIDC)

No Okta (docs oficiais):

  1. Vá em Applications → Create App Integration
  2. Selecione OIDC - OpenID Connect e depois Web Application
  3. Defina o Sign-in redirect URI como sua Callback URL do Zoen: 
    https://app.zoen.space/api/auth/sso/callback/okta
  4. Em Assignments, conceda acesso aos usuários ou grupos relevantes
  5. Copie o Client ID e o Client Secret na aba General do app
  6. Seu domínio Okta é o hostname do console admin, ex.: dev-1234567.okta.com

No Zoen:

CampoValor
Provider TypeOIDC
Provider IDokta
Issuer URLhttps://dev-1234567.okta.com/oauth2/default
Domaincompany.com
Client IDDo app Okta
Client SecretDo app Okta

A issuer URL usa o authorization server padrão do Okta, pré-configurado em toda org Okta. Se você criou um authorization server customizado, substitua default pelo nome do seu server.

Microsoft Entra ID (OIDC)

No Azure (docs oficiais):

  1. Vá em Microsoft Entra ID → App registrations → New registration
  2. Em Redirect URI, selecione Web e informe sua Callback URL do Zoen: 
    https://app.zoen.space/api/auth/sso/callback/azure-ad
  3. Depois do registro, vá em Certificates & secrets → New client secret e copie o valor imediatamente — ele não será mostrado de novo
  4. Vá em Overview e copie o Application (client) ID e o Directory (tenant) ID

No Zoen:

CampoValor
Provider TypeOIDC
Provider IDazure-ad
Issuer URLhttps://login.microsoftonline.com/{tenant-id}/v2.0
Domaincompany.com
Client IDApplication (client) ID
Client SecretValor do secret

Google Workspace (OIDC)

No Google Cloud Console (docs oficiais):

  1. Vá em APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
  2. Defina o tipo de aplicação como Web application
  3. Adicione sua Callback URL do Zoen em Authorized redirect URIs: 
    https://app.zoen.space/api/auth/sso/callback/google-workspace
  4. Copie o Client ID e o Client Secret

No Zoen:

CampoValor
Provider TypeOIDC
Provider IDgoogle-workspace
Issuer URLhttps://accounts.google.com
Domaincompany.com
Client IDDo Google Cloud Console
Client SecretDo Google Cloud Console

Para restringir o sign-in ao domínio do Google Workspace, configure a OAuth consent screen e garanta que o app está definido como Internal (só usuários do Workspace) em User type. Definir o app como Internal limita o acesso a usuários dentro da organização Google Workspace.

ADFS (SAML 2.0)

No ADFS (docs oficiais):

  1. Abra AD FS Management → Relying Party Trusts → Add Relying Party Trust
  2. Escolha Claims aware e depois Enter data about the relying party manually
  3. Defina o Relying party identifier (Entity ID) como a base URL do Zoen: 
    https://app.zoen.space
  4. Adicione um endpoint: SAML Assertion Consumer Service (HTTP POST) com a URL: 
    https://app.zoen.space/api/auth/sso/saml2/callback/adfs
  5. Exporte o Token-signing certificate de Certificates: clique com o botão direito → View Certificate → Details → Copy to File, escolha Base-64 encoded X.509 (.CER). O arquivo .cer é PEM-encoded — renomeie para .pem antes de colar o conteúdo no Zoen.
  6. Anote a ADFS Federation Service endpoint URL (ex.: https://adfs.company.com/adfs/ls)

No Zoen:

CampoValor
Provider TypeSAML
Provider IDadfs
Issuer URLhttps://app.zoen.space
Domaincompany.com
Entry Point URLhttps://adfs.company.com/adfs/ls
CertificateConteúdo do arquivo .pem

Para ADFS, o campo Issuer URL é o SP entity ID — o identificador que o ADFS usa para identificar o Zoen como relying party. Precisa bater com o Relying party identifier que você registrou no ADFS.

Como o sign-in funciona depois do setup

Uma vez que o SSO está configurado, usuários com o seu domínio (company.com) podem entrar pelo provedor de identidade:

  1. O usuário vai a app.zoen.space e clica em Sign in with SSO
  2. Informa o e-mail de trabalho (ex.: alice@company.com)
  3. O Zoen redireciona ao provedor de identidade
  4. Depois de autenticar, volta ao Zoen e é adicionado à organização automaticamente
  5. Cai no workspace

Usuários que entram via SSO pela primeira vez são provisionados automaticamente e adicionados à organização — sem convite manual.

O provisioning de SSO cria membros internos da organização. Membros externos de workspace são diferentes: são convidados a um workspace específico sem entrar na organização nem consumir um seat.

Login por senha continua disponível. Forçar todos os membros da organização a usar só SSO ainda não é suportado.

Common Questions

Qualquer provedor de identidade que suporte OIDC ou SAML 2.0. Isso inclui Okta, Microsoft Entra ID (Azure AD), Google Workspace, Auth0, OneLogin, JumpCloud, Ping Identity, ADFS, Shibboleth e mais.
O domínio (ex.: company.com) é como o Zoen roteia usuários ao provedor de identidade certo. Quando um usuário informa o e-mail na página de sign-in SSO, o Zoen combina o domínio do e-mail com um provedor SSO registrado e redireciona para lá.
Não. Para provedores OIDC, o Zoen busca automaticamente os endpoints de authorization, token e JWKS no documento de discovery em {issuer}/.well-known/openid-configuration. Você só precisa fornecer a issuer URL.
O Zoen cria uma conta automaticamente e o adiciona à organização. Nenhum convite manual é necessário. Ele recebe o role member por padrão. Membros externos de workspace não são provisionados via SSO na organização; são convidados diretamente a um workspace e permanecem fora do roster da org.
Sim. Habilitar SSO não desabilita o login por senha. Usuários ainda podem entrar com e-mail e senha se tiverem. Forced SSO (exigir que todos os usuários do domínio usem SSO) ainda não é suportado.
O Zoen liga a identidade SSO à conta existente automaticamente, desde que seu provedor de identidade reporte o e-mail como verificado (email_verified) ou o provedor seja trusted. A maioria dos provedores OIDC (Okta, Google Workspace, Auth0) afirma email_verified, então o linking funciona. Se o sign-in falhar com 'account not linked' — comum com provedores SAML que omitem o claim — adicione o ID do provedor a SSO_TRUSTED_PROVIDER_IDS no self-hosted e reinicie.
Owners e admins da organização podem configurar SSO. Você precisa estar no plano Enterprise.
A Callback URL (também chamada Redirect URI ou ACS URL) é o endpoint no Zoen que recebe a resposta de autenticação do provedor de identidade. Para provedores OIDC segue o formato: https://app.zoen.space/api/auth/sso/callback/{provider-id}. Para provedores SAML: https://app.zoen.space/api/auth/sso/saml2/callback/{provider-id}. Você precisa registrar esta URL no provedor de identidade antes do SSO funcionar.
Abra Settings → Enterprise → Single Sign-On e clique em Edit. Atualize os campos e salve. A configuração existente do provedor é substituída.

Setup self-hosted

Deployments self-hosted usam variáveis de ambiente em vez da checagem de billing/plano.

Variáveis de ambiente

# Required
SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

# Required if you want users auto-added to your organization on first SSO sign-in
ORGANIZATIONS_ENABLED=true
NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true

# Optional: comma-separated SSO provider IDs to trust for automatic account linking
# (links an SSO sign-in to an existing account with the same email). Needed when your
# IdP does not assert email_verified — typically SAML providers, or OIDC providers that
# omit the claim. Set it to the Provider ID you registered, then restart.
# (If you also keep SSO_PROVIDER_ID in the app's environment, that provider is trusted
# without listing it here.)
SSO_TRUSTED_PROVIDER_IDS=custom-oidc,partner-saml

Quando alguém entra com SSO e já existe uma conta com o mesmo e-mail (por exemplo, se cadastrou antes com e-mail/senha), o Zoen liga a identidade SSO àquela conta automaticamente desde que seu IdP reporte o e-mail como verificado, ou o provedor seja trusted. Se você encontrar um erro account not linked, confirme que o IdP envia email_verified, ou adicione o ID do provedor a SSO_TRUSTED_PROVIDER_IDS e reinicie.

Você pode registrar provedores pela Settings UI (como no cloud) ou rodando o script de registro diretamente contra o banco.

Registro via script

Use isso quando precisar registrar um provedor SSO sem passar pela UI — por exemplo, durante o deployment inicial ou automação CI/CD.

# OIDC example (Okta)
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=oidc \
SSO_PROVIDER_ID=okta \
SSO_ISSUER=https://dev-1234567.okta.com/oauth2/default \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
SSO_OIDC_CLIENT_ID=your-client-id \
SSO_OIDC_CLIENT_SECRET=your-client-secret \
bun run packages/db/scripts/register-sso-provider.ts
# SAML example (ADFS)
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=saml \
SSO_PROVIDER_ID=adfs \
SSO_ISSUER=https://your-instance.com \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
SSO_SAML_ENTRY_POINT=https://adfs.company.com/adfs/ls \
SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
bun run packages/db/scripts/register-sso-provider.ts

O script imprime a callback URL para configurar no IdP quando conclui.

Para remover um provedor:

SSO_USER_EMAIL=admin@company.com \
bun run packages/db/scripts/deregister-sso-provider.ts
PreviousEnterpriseNextAccess Control

On this page

Setup
1. Abra as settings de SSO
2. Escolha um protocolo
3. Preencha o formulário
4. Copie a Callback URL
5. Salve e teste
Guias de provedor
Okta (OIDC)
Microsoft Entra ID (OIDC)
Google Workspace (OIDC)
ADFS (SAML 2.0)
Como o sign-in funciona depois do setup
Setup self-hosted
Variáveis de ambiente
Registro via script