> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Login único (OIDC)

> Permita que os usuários entrem no Notifuse com o seu provedor de identidade (Google Workspace, Keycloak, Okta, …) via OpenID Connect, junto com o login por código mágico.

O Notifuse oferece suporte a **Login único (SSO)** via [OpenID Connect](https://openid.net/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.

> [!WARNING]
>
> **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](https://www.notifuse.com/pt/docs/self-hosting/licence.md). No Notifuse Cloud, a chave é gerenciada para você e o SSO está incluído no plano Business: veja [No Notifuse Cloud](https://www.notifuse.com/pt/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> 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**:

1. O usuário clica em **Entrar com SSO**, e o Notifuse o redireciona para o seu IdP.
2. O usuário se autentica no IdP (com o MFA e as políticas definidas lá).
3. 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.

> [!NOTE]
>
> **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](#provisioning) abaixo.

## Configuração

O OIDC pode ser configurado de três formas, nesta ordem de prioridade:

1. **Variáveis de ambiente** (`OIDC_*`): recomendadas para produção, e sempre prevalecem.
2. **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.
3. **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](#provisioning).                                                                                                                                                                                                                                                                    | `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](#invited-users)). | `false`                    |

> [!WARNING]
>
> 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](#invited-users)). 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:

```bash
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](#invited-users) 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                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Google                  | 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.

> [!NOTE]
>
> 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
```

> [!WARNING]
>
> 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

1. No [Google Cloud Console](https://console.cloud.google.com/apis/credentials), acesse **APIs & Services → Credentials → Create credentials → OAuth client ID**.
2. Escolha **Web application**.
3. Em **Authorized redirect URIs**, adicione `https://<your-notifuse-domain>/api/user.oidc.callback`.
4. Copie o **Client ID** e o **Client secret**.
5. Configure o Notifuse:

```bash
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
```

> [!NOTE]
>
> 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](#invited-users)).

### Keycloak

1. No seu realm, crie um client: **Client type** OpenID Connect, **Client authentication** ON (confidencial), **Standard flow** ativado.
2. Defina **Valid redirect URIs** como `https://<your-notifuse-domain>/api/user.oidc.callback`.
3. Copie o segredo na aba **Credentials** do client.
4. Configure o Notifuse:

```bash
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret
```

> [!TIP]
>
> 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_ENABLED` e 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 `HttpOnly` criptografado 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](#invited-users)), 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](#invited-users)); 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**.                                                                                                                                            |

> [!NOTE]
>
> 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.
