O Notifuse oferece suporte a Login único (SSO) via OpenID Connect (OIDC), para que a sua equipe entre usando um provedor de identidade (IdP) externo como Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik ou Dex.
O SSO funciona junto com o login nativo por código mágico e não o substitui. Quando o SSO está ativado, a página de login mostra um botão adicional “Entrar com SSO” ao lado do formulário de email; os dois métodos dão acesso à mesma conta.
Atenção
O SSO exige uma licença que inclua esse recurso (o plano Enterprise). Em uma instalação sem essa licença, o botão Entrar com SSO não aparece, independentemente de como o SSO esteja configurado, e todo mundo entra com um código de login. Ninguém perde acesso: toda conta SSO tem um endereço de email verificado, o login com código continua funcionando sempre e as sessões já abertas não são afetadas. O log de inicialização registra sso_gated=true quando isso ocorre, e Configurações → Sistema exibe o aviso ao lado da opção. Instalar uma licença que inclua SSO traz o botão de volta imediatamente, sem reiniciar. Veja Chaves de licença. No Notifuse Cloud, a chave é gerenciada para você e o SSO está incluído no plano Business: veja No Notifuse Cloud.
Nota
O SSO vem desativado por padrão. Instalações existentes que não o configuram não sofrem nenhuma mudança: a página de login continua igual, apenas com o formulário de código mágico.
Como funciona
O Notifuse atua como um Relying Party OIDC usando o fluxo Authorization Code com PKCE:
- O usuário clica em Entrar com SSO, e o Notifuse o redireciona para o seu IdP.
- O usuário se autentica no IdP (com o MFA e as políticas definidas lá).
- O IdP redireciona de volta para
…/api/user.oidc.callback; o Notifuse valida o ID token no servidor (assinatura, issuer, audience, nonce e validade) e autentica o usuário.
A troca e a validação dos tokens do IdP acontecem inteiramente no servidor: apenas o token de sessão do próprio Notifuse chega ao navegador. O PKCE fica sempre ativado, e o client secret nunca é exposto ao frontend.
Nota
Fazer login não é o mesmo que ter acesso a um workspace. Um login SSO bem-sucedido autentica o usuário, mas não concede acesso a nenhum workspace. Usuários de SSO ainda precisam de um convite para um workspace (ou ser um ROOT_EMAIL) antes de poder fazer qualquer coisa. Veja Provisionamento abaixo.
Configuração
O OIDC pode ser configurado de três formas, nesta ordem de prioridade:
- Variáveis de ambiente (
OIDC_*): recomendadas para produção, e sempre prevalecem. - Assistente de configuração: uma seção opcional Login único na primeira inicialização, com o URI de redirecionamento para registrar no seu IdP e os escopos.
- Configurações do Sistema → SSO (OpenID Connect): o painel administrativo no seletor de workspace do console após a instalação.
Quando um valor é definido por variável de ambiente, o campo correspondente aparece como somente leitura no assistente e nas configurações. No assistente, definir OIDC_ENABLED, OIDC_ISSUER_URL ou OIDC_CLIENT_ID bloqueia a seção inteira, que passa a listar as variáveis definidas. Salvar configurações de OIDC pela interface dispara um reinício controlado do servidor para recarregar a configuração (o mesmo comportamento das configurações de SMTP). O client secret fica criptografado em repouso no banco de dados.
Variáveis de ambiente
| Variável | Descrição | Padrão |
|---|---|---|
OIDC_ENABLED | Chave geral. Quando está como false ou não definida, o SSO fica desativado e o botão fica oculto. | false |
OIDC_ISSUER_URL | URL do issuer do seu IdP (precisa ser https). O Notifuse descobre o restante a partir de <issuer>/.well-known/openid-configuration. Obrigatória quando ativado. | - |
OIDC_CLIENT_ID | Client ID OAuth2 do seu IdP. Obrigatória quando ativado. | - |
OIDC_CLIENT_SECRET | Client secret OAuth2 (cliente confidencial). Criptografado em repouso e nunca enviado ao navegador. Obrigatória quando ativado. | - |
OIDC_REDIRECT_URI | URL de callback registrada no seu IdP. Se ficar vazia, é derivada como <API_ENDPOINT>/api/user.oidc.callback. | derivada de API_ENDPOINT |
OIDC_SCOPES | Escopos separados por espaço. openid é sempre incluído; email é obrigatório e profile fornece o nome de exibição opcional. | openid email profile |
OIDC_BUTTON_LABEL | Texto exibido no botão de login. | Sign in with SSO |
OIDC_AUTO_CREATE_USERS | Provisionamento automático no primeiro acesso. Quando true, exige OIDC_ALLOWED_DOMAINS. Veja Provisionamento. | false |
OIDC_ALLOWED_DOMAINS | Lista de domínios de email permitidos, separados por vírgula, ponto e vírgula ou espaço, que controla a criação automática. Obrigatória quando OIDC_AUTO_CREATE_USERS=true (caso contrário, o servidor se recusa a iniciar). | - |
OIDC_ALLOW_UNVERIFIED_EMAIL | Aceita um ID token sem a claim email_verified, para provedores que nunca a enviam (Microsoft Entra ID, Cloudflare Access). No primeiro login, um token com email_verified: false é recusado; uma identidade já vinculada a uma conta entra pelo subject e não é verificada de novo. Um endereço não verificado nunca conta para um convite pendente (veja Usuários convidados). | false |
Atenção
Quando OIDC_ENABLED=true, o servidor valida a configuração na inicialização e falha imediatamente se encontrar algo inválido (issuer, client ou secret ausente, issuer sem https ou criação automática sem lista de domínios permitidos). A mesma validação roda antes de o painel de Configurações salvar, então uma configuração inválida é recusada com erro em vez de gravada.
Provisionamento
Por padrão, o SSO aceita apenas usuários convidados: alguém só consegue entrar com SSO se já tiver uma conta no Notifuse ou se tiver recebido convite para um workspace (veja Usuários convidados). Uma tentativa de login por SSO de um endereço não convidado é recusada com uma mensagem informando que não há conta. Isso preserva o modelo sem autocadastro do Notifuse.
Para criar novos usuários automaticamente no primeiro login por SSO, defina:
OIDC_AUTO_CREATE_USERS=true
OIDC_ALLOWED_DOMAINS=yourcompany.com
Com a criação automática ativada, uma conta é criada no primeiro login quando o IdP informa um email verificado e o domínio está em OIDC_ALLOWED_DOMAINS. Mesmo assim, o novo usuário não tem acesso a nenhum workspace até ser convidado. Um endereço com convite pendente segue as regras de Usuários convidados nos dois sentidos: o convite pode criar a conta fora da lista de domínios permitidos, e um provedor que não tem autoridade sobre o endereço não cria nenhuma conta.
Usuários convidados
Quem foi convidado não precisa abrir o link do email antes de entrar com SSO. No primeiro login por SSO, um convite pendente para o endereço cria a conta. Isso vale no modo somente para convidados e mesmo quando o domínio não está em OIDC_ALLOWED_DOMAINS, já que o convite representa a escolha explícita de um proprietário por aquele endereço. O convite não é aceito automaticamente: o usuário cai na lista de workspaces, em Convites pendentes, e clica em Entrar.
Isso só acontece quando o seu provedor de identidade tem autoridade sobre o endereço, porque entrar pelo console confia no endereço informado pelo provedor:
| Provedor | Tem autoridade quando |
|---|---|
O endereço termina em @gmail.com ou pertence a uma conta Google Workspace (a claim hd). O Google não garante a posse de uma conta Google pessoal cadastrada com o endereço de outro domínio. | |
| Microsoft Entra ID | O usuário é membro do seu tenant e o ID token traz a claim opcional xms_edov definida como true. Adicione-a no registro do aplicativo em Token configuration → Add optional claim → ID. Convidados que entram com uma conta pessoal da Microsoft ou do Google, ou com um código descartável, não contam (o Entra também define xms_edov para eles). |
| Qualquer outro provedor | O ID token traz email_verified: true. Um provedor que atua como intermediário de outros (Keycloak, Dex, conexões sociais do Auth0) atesta os endereços deles com o próprio email_verified, então repasse essa claim apenas para endereços confiáveis. |
Quando o provedor não tem autoridade sobre o endereço, o SSO não cria conta para um endereço convidado (nem mesmo com OIDC_AUTO_CREATE_USERS), e o convidado precisa abrir o link no email de convite. Depois de aceitar o convite, o SSO passa a funcionar normalmente para ele.
Nota
Os usuários são identificados pelo par persistente (issuer, subject) do IdP, não pelo email, então a conta continua sendo a mesma mesmo que o email mude no IdP. O email é usado apenas no primeiro login, para vincular a identidade SSO a uma conta existente ou localizar convites pendentes para aquele endereço. Uma conta ROOT_EMAIL nunca pode ser vinculada automaticamente a uma identidade externa (uma proteção contra tomada de controle do administrador da plataforma).
Configuração do provedor de identidade
A URL de callback/redirecionamento que você deve registrar em todos os provedores é:
https://<your-notifuse-domain>/api/user.oidc.callback
Atenção
O URI de redirecionamento precisa coincidir byte a byte entre o seu IdP e o Notifuse. Se você roda atrás de um proxy reverso que reescreve o esquema ou o host, defina OIDC_REDIRECT_URI explicitamente com a URL visível externamente; caso contrário, o IdP retorna um erro redirect_uri_mismatch.
Google Workspace
- No Google Cloud Console, acesse APIs & Services → Credentials → Create credentials → OAuth client ID.
- Escolha Web application.
- Em Authorized redirect URIs, adicione
https://<your-notifuse-domain>/api/user.oidc.callback. - Copie o Client ID e o Client secret.
- Configure o Notifuse:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
OIDC_CLIENT_SECRET=your-client-secret
# Restrict to your organization's domain:
OIDC_ALLOWED_DOMAINS=yourcompany.com
Nota
Contas pessoais @gmail.com e as contas do seu Workspace compartilham o issuer accounts.google.com. Use OIDC_ALLOWED_DOMAINS (ou mantenha o modo padrão somente para convidados) para restringir o login à sua organização. Um endereço @gmail.com que você convidou continua podendo entrar (veja Usuários convidados).
Keycloak
- No seu realm, crie um client: Client type OpenID Connect, Client authentication ON (confidencial), Standard flow ativado.
- Defina Valid redirect URIs como
https://<your-notifuse-domain>/api/user.oidc.callback. - Copie o segredo na aba Credentials do client.
- Configure o Notifuse:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret
Dica
Os escopos padrão de client do Keycloak já enviam email, email_verified, name e sub. Se alguém removeu o mapper de email do seu client, os logins por SSO são recusados por falta da claim de email: adicione de volta o escopo nativo email.
Outros provedores
Qualquer provedor certificado em OpenID Connect funciona da mesma forma: defina OIDC_ISSUER_URL com o issuer do provedor, registre o URI de redirecionamento e informe o client ID e o client secret. Isso inclui Okta, Microsoft Entra ID (Azure AD), Authentik e Dex.
Notas de segurança
- Apenas dois valores não secretos chegam ao navegador:
window.OIDC_ENABLEDe o texto do botão. O client ID, o client secret e a URL do issuer nunca são expostos na página. - Os ID tokens são validados com as chaves publicadas pelo issuer (rotacionadas automaticamente via JWKS); assinatura, issuer, audience, nonce e validade são verificados, e apenas algoritmos assimétricos (RS256/ES256) são aceitos.
- O estado CSRF/nonce/PKCE do fluxo fica armazenado em um cookie
HttpOnlycriptografado e de curta duração. - As chamadas HTTP de OIDC (descoberta, busca de chaves e troca de tokens) têm limite de tempo, então um issuer lento ou inacessível não trava a página de login; o login por código mágico não é afetado.
Solução de problemas
| Sintoma | Causa e solução |
|---|---|
| “O single sign-on está temporariamente indisponível” ao clicar em SSO | O Notifuse não consegue alcançar ou descobrir o issuer. Verifique se OIDC_ISSUER_URL está correta, acessível a partir do servidor e servindo o documento de descoberta. O Notifuse tenta novamente de forma automática assim que o issuer voltar. |
| “Nenhuma conta Notifuse está vinculada… Se você foi convidado, abra o link do seu e-mail de convite” | O endereço não tem conta e o SSO não tem de onde criar uma. Ou ninguém o convidou (convide o usuário, ou ative OIDC_AUTO_CREATE_USERS com uma lista de domínios permitidos), ou há um convite pendente mas o seu provedor não tem autoridade sobre o endereço (veja Usuários convidados), e o usuário precisa aceitar o convite pelo link. |
| “O single sign-on não pode criar uma conta para o seu domínio de e-mail” | A criação automática está ativada e o endereço está fora de OIDC_ALLOWED_DOMAINS. Adicione o domínio ou convide o usuário: um convite prevalece sobre a lista de domínios para aquele endereço quando o provedor tem autoridade sobre ele (veja Usuários convidados); caso contrário, o usuário aceita o convite pelo link. |
redirect_uri_mismatch / invalid_redirect_uri no IdP | O URI de redirecionamento registrado no IdP não coincide exatamente com o que o Notifuse envia. Registre …/api/user.oidc.callback e defina OIDC_REDIRECT_URI se você estiver atrás de um proxy que reescreve esquema ou host. |
| O servidor não inicia após ativar o OIDC | A validação da configuração falhou. Verifique se OIDC_ISSUER_URL usa https, se OIDC_CLIENT_ID e OIDC_CLIENT_SECRET estão definidas, e se OIDC_ALLOWED_DOMAINS não está vazia quando OIDC_AUTO_CREATE_USERS=true. |
| Um usuário consegue entrar, mas não acessa nenhum workspace | Comportamento esperado: fazer login não concede autorização. Convide o usuário para o workspace desejado (ou adicione-o a ROOT_EMAIL); um convite pendente aparece na lista de workspaces com o botão Entrar. |
Nota
Roda várias réplicas do Notifuse atrás de um balanceador de carga? O código de uso único que conclui a troca do SSO fica guardado por instância, então ative sticky sessions para o SSO funcionar de forma confiável entre réplicas. Instalações com uma única instância não precisam de nenhuma configuração extra.
