OIDC / Single Sign-On

O SnapOtter oferece suporte a OpenID Connect (OIDC) para single sign-on. Os usuários podem fazer login com um provedor de identidade externo, como Keycloak, Authentik, Google ou Microsoft Entra ID, em vez de (ou junto com) a autenticação local por usuário/senha.

Veja também

SAML SSO | Provisionamento SCIM | Usuários, Papéis e Permissões

Início rápido

Adicione estas variáveis de ambiente ao seu docker-compose.yml:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

A URI de redirecionamento do seu provedor é sempre:

${EXTERNAL_URL}/api/auth/oidc/callback

Por exemplo, se EXTERNAL_URL for https://photos.example.com, configure a URI de redirecionamento do seu provedor como https://photos.example.com/api/auth/oidc/callback.

Referência de configuração

Variável	Padrão	Descrição
OIDC_ENABLED	false	Habilita o login OIDC. Um botão "Entrar com SSO" aparece na página de login.
OIDC_ISSUER_URL		URL do issuer do provedor. Deve suportar OIDC Discovery (/.well-known/openid-configuration).
OIDC_CLIENT_ID		ID do cliente OAuth registrado com seu provedor.
OIDC_CLIENT_SECRET		Segredo do cliente OAuth.
OIDC_SCOPES	openid profile email	Lista de escopos a solicitar, separados por espaço.
OIDC_AUTO_CREATE_USERS	true	Cria automaticamente uma conta de usuário local no primeiro login OIDC.
OIDC_DEFAULT_ROLE	user	Papel atribuído a usuários OIDC criados automaticamente. Um de admin, editor ou user.
OIDC_AUTO_LINK_USERS	false	Vincula uma identidade OIDC a um usuário local existente se o endereço de e-mail corresponder.
OIDC_PROVIDER_NAME		Nome de exibição mostrado no botão de login (por exemplo, "Keycloak", "Google"). Se vazio, o botão diz "SSO".
OIDC_CLOCK_TOLERANCE	30	Tolerância de desvio de relógio em segundos para validação de token.
OIDC_USERNAME_CLAIM	preferred_username	Claim do token de ID usada como nome de usuário para novas contas.
EXTERNAL_URL		A URL pública onde o SnapOtter está acessível. Obrigatória para que o OIDC construa a URI de redirecionamento correta.
COOKIE_SECRET	gerado automaticamente	Segredo para assinar os cookies de sessão. Defina isto explicitamente ao executar várias réplicas.

Guias de provedores

Keycloak

1. Crie um novo realm (ou use um existente).
2. Vá para Clients e crie um novo cliente:
   • Client ID: snapotter
   • Client authentication: On (confidential)
   • Authentication flow: Standard flow (Authorization Code)
3. Na aba Settings do cliente, defina Valid redirect URIs como sua URL de callback (por exemplo, https://photos.example.com/api/auth/oidc/callback).
4. Copie o Client secret da aba Credentials.
5. Defina OIDC_ISSUER_URL como https://keycloak.example.com/realms/your-realm.

Authentik

1. Na interface de administração, vá para Applications > Providers e crie um novo OAuth2/OpenID Provider.
   • Client type: Confidential
   • Redirect URIs: Sua URL de callback
   • Signing key: Selecione uma chave existente ou crie uma
2. Crie uma Application e vincule-a ao provedor.
3. Copie o Client ID e o Client Secret das configurações do provedor.
4. Defina OIDC_ISSUER_URL como https://authentik.example.com/application/o/snapotter/ (a barra final importa).

Google

1. Acesse o Google Cloud Console.
2. Crie um projeto (ou selecione um existente).
3. Navegue até APIs & Services > OAuth consent screen e configure-o.
4. Vá para APIs & Services > Credentials e crie um OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: Sua URL de callback
5. Copie o Client ID e o Client secret.
6. Defina OIDC_ISSUER_URL como https://accounts.google.com.
7. Defina OIDC_USERNAME_CLAIM como email (o Google não fornece preferred_username).

Azure AD / Entra ID

1. No portal do Azure, vá para Microsoft Entra ID > App registrations > New registration.
2. Nomeie o aplicativo como "SnapOtter". Em Redirect URI, selecione a plataforma Web e informe sua URL de callback (por exemplo, https://photos.example.com/api/auth/oidc/callback). Não escolha Single-page application: o SnapOtter se autentica com um segredo de cliente, que o Entra ID rejeita em registros SPA.
3. Copie o Application (client) ID e o Directory (tenant) ID da página Overview.
4. Vá para Certificates & secrets > New client secret e copie imediatamente o Value do segredo. Ele é exibido apenas uma vez, e o Secret ID ao lado não é o segredo.
5. Defina OIDC_ISSUER_URL como https://login.microsoftonline.com/<tenant-id>/v2.0, usando o Directory (tenant) ID da etapa 3.
6. Deixe OIDC_USERNAME_CLAIM no valor padrão. O Entra ID fornece preferred_username, então a substituição por email do guia do Google não é necessária aqui.

Sempre use o ID do seu tenant na URL do issuer, não common nem organizations. Esses endpoints multi-tenant anunciam o template literal {tenantid} como issuer, o que falha na validação do OIDC Discovery.

WARNING

O preferred_username do Entra ID acompanha o user principal name, que muda quando um usuário é renomeado ou movido para outro tenant. O SnapOtter lê a claim uma única vez, no primeiro login, então a conta mantém seu nome de usuário original depois disso. Os logins continuam funcionando de qualquer maneira: usuários recorrentes são identificados pelo subject estável do token, não pelo nome de usuário.

Mudar para o Entra ID não desativa o login por senha. Veja Desabilitando o login local.

Okta e outros provedores

Qualquer provedor que ofereça suporte a OIDC Discovery funciona da mesma maneira: crie um cliente web confidencial com sua URL de callback e aponte OIDC_ISSUER_URL para o issuer. No Okta, crie um aplicativo com o método de login OIDC - OpenID Connect e o tipo Web Application e, em seguida, use seu domínio Okta como issuer (por exemplo, https://your-company.okta.com).

O SnapOtter não mapeia grupos do provedor de identidade para papéis. Novos usuários SSO recebem OIDC_DEFAULT_ROLE, os administradores alteram os papéis em Settings > Users, e solicitar claims de grupo via OIDC_SCOPES não tem efeito.

Provisionamento de usuários

Criação automática

Quando OIDC_AUTO_CREATE_USERS é true (o padrão), uma conta de usuário local é criada na primeira vez que alguém faz login via OIDC. O nome de usuário é obtido da claim especificada por OIDC_USERNAME_CLAIM, e o papel é definido como OIDC_DEFAULT_ROLE.

Se ocorrer uma colisão de nome de usuário, um sufixo numérico é anexado (por exemplo, jane vira jane_2).

Vinculação automática

Quando OIDC_AUTO_LINK_USERS é true, o SnapOtter vincula uma identidade OIDC a uma conta local existente se os endereços de e-mail corresponderem. Isso é útil quando você tem contas de usuário pré-criadas e quer que elas comecem a usar SSO sem perder seus dados.

WARNING

Habilite a vinculação automática apenas se você confiar que seu provedor OIDC verifica os endereços de e-mail. Um e-mail não verificado poderia permitir que alguém assumisse a conta de outro usuário.

Desabilitando o login local

O OIDC não desabilita o login local por usuário/senha. Ambos os métodos permanecem disponíveis. Os administradores ainda podem fazer login com credenciais locais caso o provedor OIDC esteja inacessível.

Certificados autoassinados

Se o seu provedor OIDC usa um certificado autoassinado ou de uma CA privada, monte o pacote da CA no contêiner e aponte NODE_EXTRA_CA_CERTS para ele:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

Não defina NODE_TLS_REJECT_UNAUTHORIZED=0. Isso desabilita toda a verificação TLS e é um risco de segurança.

Emissores com http sem criptografia

O SnapOtter só aceita uma URL de emissor http:// quando o EXTERNAL_URL também é http sem criptografia, o que serve para uma configuração de teste local ou em LAN. Nesse caso, a descoberta, a troca do código de login e os tokens trafegam pela rede sem criptografia, então o SnapOtter registra um aviso na inicialização com o host do emissor. Com um EXTERNAL_URL https://, um emissor http é recusado no login e o aviso de inicialização informa isso. Em ambos os casos, a solução é servir seu provedor de identidade por https.

Solução de problemas

Incompatibilidade de URI de redirecionamento

O erro mais comum. Verifique estas diferenças entre o que seu provedor espera e o que o SnapOtter envia:

• http vs https - o esquema deve corresponder exatamente
• Barra final - alguns provedores são rigorosos quanto a isso
• Número da porta - inclua a porta se ela não for padrão
• Caminho - deve ser /api/auth/oidc/callback

Confira novamente EXTERNAL_URL. Ele deve corresponder à URL que os usuários digitam no navegador.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

O provedor OIDC está usando um certificado no qual o Node.js não confia. Veja Certificados autoassinados acima.

Erros de desvio de relógio

Se o relógio do seu servidor e o relógio do provedor OIDC estiverem fora de sincronia, a validação do token pode falhar. Aumente OIDC_CLOCK_TOLERANCE (o padrão é 30 segundos). Uma solução melhor é rodar NTP em ambas as máquinas.

"OIDC provider unreachable"

O SnapOtter busca o documento de discovery do provedor na inicialização e durante o login. Verifique:

• Resolução de DNS de dentro do contêiner Docker (docker exec snapotter nslookup auth.example.com)
• Regras de firewall entre o contêiner e o provedor
• O valor de OIDC_ISSUER_URL - ele deve ser acessível a partir do servidor, não apenas do seu navegador

Claims ausentes

Se os nomes de usuário ou e-mails estiverem vazios após o login, seu provedor pode não estar retornando as claims esperadas. Verifique:

• Os escopos configurados em OIDC_SCOPES incluem profile e email
• O provedor está configurado para incluir a claim especificada em OIDC_USERNAME_CLAIM no token de ID
• Alguns provedores exigem configuração explícita de mapper/escopo para liberar as claims