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 ou Google, 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).

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.

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