SAML SSO

O SnapOtter oferece suporte a SAML 2.0 para single sign-on. Os usuários podem fazer login por meio de um provedor de identidade externo (Okta, Azure AD / Entra ID, Google Workspace ou qualquer IdP SAML 2.0 padrão) em vez da autenticação local por usuário/senha.

Recurso enterprise

O SAML SSO requer uma licença team ou enterprise com o recurso saml_sso. Se SAML_ENABLED=true estiver definido sem uma licença válida, as rotas SAML são ignoradas silenciosamente e um aviso é registrado.

Pré-requisitos

• Uma instância do SnapOtter em execução, acessível em uma URL pública
• EXTERNAL_URL definido para essa URL pública (por exemplo, https://photos.example.com)
• Uma chave de licença team ou enterprise com o recurso saml_sso
• Acesso de administrador ao seu provedor de identidade SAML

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"
      SNAPOTTER_LICENSE_KEY: "your-license-key"
      SAML_ENABLED: "true"
      SAML_IDP_SSO_URL: "https://idp.example.com/sso/saml"
      SAML_IDP_CERTIFICATE: |
        MIICpDCCAYwCCQDU+pQ4pHgSpDANBgkqhkiG9w0BAQsFADAUMRIw
        ...your IdP's signing certificate in PEM format...
        EAYHKoZIzj0CAQYFK4EEACIDYgAE

Reinicie o contêiner. Um botão "Entrar com SAML" (ou o rótulo definido por SAML_PROVIDER_NAME) aparece na página de login.

Referência de configuração

Variável	Padrão	Descrição
SAML_ENABLED	false	Habilita o login SAML.
SAML_IDP_SSO_URL		URL do endpoint SSO do IdP. Obrigatória quando o SAML está habilitado.
SAML_IDP_CERTIFICATE		Certificado de assinatura X.509 do IdP em formato PEM (o texto do certificado em si, não um caminho de arquivo). Obrigatório quando o SAML está habilitado.
EXTERNAL_URL		A URL pública onde o SnapOtter está acessível. Obrigatória quando o SAML está habilitado.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI enviado ao IdP.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	URL do Assertion Consumer Service (ACS).
SAML_AUTO_CREATE_USERS	true	Cria automaticamente uma conta de usuário local no primeiro login SAML.
SAML_AUTO_LINK_USERS	false	Vincula uma identidade SAML a um usuário local existente se o endereço de e-mail corresponder.
SAML_DEFAULT_ROLE	user	Papel atribuído a usuários SAML criados automaticamente. Um de admin, editor ou user.
SAML_PROVIDER_NAME		Rótulo de exibição para o botão de login SAML no frontend (por exemplo, "Okta", "Azure AD"). Se vazio, o botão diz "SAML".
SAML_USERNAME_ATTRIBUTE		Atributo da asserção SAML usado como nome de usuário. Se vazio, recorre à parte local do e-mail e, então, ao NameID.
SAML_EMAIL_ATTRIBUTE	email	Atributo da asserção SAML usado como endereço de e-mail do usuário.

O servidor se recusa a iniciar se SAML_ENABLED=true e qualquer uma das três variáveis obrigatórias (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) estiver ausente.

Notas de segurança

Tanto wantAuthnResponseSigned quanto wantAssertionsSigned estão fixados em true. O SnapOtter rejeita respostas SAML não assinadas ou assinadas incorretamente. Asserções de um IdP confiável são tratadas como e-mail verificado.

Apenas login iniciado pelo SP é suportado. O SnapOtter não suporta login iniciado pelo IdP (não solicitado) nem Single Logout (SLO). Sair do SnapOtter não desconecta o usuário do IdP.

Metadados do SP e URLs

Seu IdP precisa de três valores do SnapOtter:

Campo	Valor
ACS URL (Assertion Consumer Service)	${EXTERNAL_URL}/api/auth/saml/callback
Entity ID / Audience URI	${EXTERNAL_URL}/api/auth/saml/metadata
SP Metadata (XML)	GET ${EXTERNAL_URL}/api/auth/saml/metadata

Por exemplo, se EXTERNAL_URL for https://photos.example.com:

• ACS URL: https://photos.example.com/api/auth/saml/callback
• Entity ID: https://photos.example.com/api/auth/saml/metadata
• Endpoint de metadados: https://photos.example.com/api/auth/saml/metadata (retorna XML)

Alguns IdPs conseguem importar a URL de metadados do SP diretamente, o que preenche automaticamente a ACS URL e o Entity ID.

Configuração do provedor

Okta

1. No console de administração do Okta, vá para Applications > Create App Integration.
2. Selecione SAML 2.0 e clique em Next.
3. Defina um nome (por exemplo, "SnapOtter") e clique em Next.
4. Configure as definições SAML:
   • Single sign-on URL: Sua ACS URL (por exemplo, https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Seu Entity ID (por exemplo, https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. Em Attribute Statements, adicione email mapeado para user.email.
6. Clique em Next, depois em Finish.
7. Vá para a aba Sign On, clique em View SAML setup instructions e copie:
   • Identity Provider Single Sign-On URL para SAML_IDP_SSO_URL
   • X.509 Certificate para SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. No portal do Azure, vá para Microsoft Entra ID > Enterprise applications > New application.
2. Clique em Create your own application, nomeie-a como "SnapOtter" e selecione Integrate any other application you don't find in the gallery.
3. Vá para Single sign-on > SAML e clique em Edit na seção Basic SAML Configuration:
   • Identifier (Entity ID): Seu Entity ID (por exemplo, https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): Sua ACS URL (por exemplo, https://photos.example.com/api/auth/saml/callback)
4. Em SAML Certificates, baixe o Certificate (Base64).
5. Em Set up SnapOtter, copie a Login URL.
6. Defina SAML_IDP_SSO_URL como a Login URL e SAML_IDP_CERTIFICATE como o conteúdo do certificado baixado.
7. Atribua usuários ou grupos ao aplicativo em Users and groups.

Google Workspace

1. No console de administração do Google, vá para Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Nomeie o app como "SnapOtter" e clique em Continue.
3. Na página Google Identity Provider details, copie a SSO URL e baixe o Certificate. Clique em Continue.
4. Configure os detalhes do Service Provider:
   • ACS URL: Sua ACS URL (por exemplo, https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Seu Entity ID (por exemplo, https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Clique em Continue, depois em Finish.
6. Ative o app (ON) para suas unidades organizacionais.
7. Defina SAML_IDP_SSO_URL como a SSO URL da etapa 3 e SAML_IDP_CERTIFICATE como o conteúdo do certificado baixado.

IdP SAML 2.0 genérico

Para qualquer provedor de identidade compatível com SAML 2.0:

1. Crie um novo aplicativo/service provider SAML no seu IdP.
2. Defina a ACS URL como ${EXTERNAL_URL}/api/auth/saml/callback.
3. Defina o Entity ID / Audience como ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Configure o IdP para enviar o e-mail do usuário em um atributo chamado email (ou defina SAML_EMAIL_ATTRIBUTE para corresponder ao nome do atributo do seu IdP).
5. Copie a IdP SSO URL e o certificado de assinatura para SAML_IDP_SSO_URL e SAML_IDP_CERTIFICATE.

Provisionamento de usuários

Criação automática

Quando SAML_AUTO_CREATE_USERS é true (o padrão), uma conta de usuário local é criada na primeira vez que alguém faz login via SAML. O papel é definido como SAML_DEFAULT_ROLE.

O nome de usuário é derivado nesta ordem:

1. O valor do atributo da asserção especificado por SAML_USERNAME_ATTRIBUTE (se definido e presente)
2. A parte local do endereço de e-mail (tudo antes de @)
3. O NameID do SAML

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 SAML_AUTO_LINK_USERS é true, o SnapOtter vincula uma identidade SAML 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 IdP SAML verifica os endereços de e-mail. Um e-mail não verificado de um IdP mal configurado poderia permitir que alguém assumisse a conta de outro usuário.

Mapeamento de atributos

Campo do SnapOtter	Origem	Configuração
E-mail	Atributo da asserção	SAML_EMAIL_ATTRIBUTE (padrão: email)
Nome de usuário	Atributo da asserção, e-mail ou NameID	SAML_USERNAME_ATTRIBUTE (veja a ordem de derivação acima)
ID externo	NameID	Sempre o NameID do SAML, não configurável

Aplicação obrigatória de SSO

Se você quiser exigir que todos os usuários façam login via SAML (ou OIDC) e bloquear o login local por senha, habilite a aplicação obrigatória de SSO:

1. Garanta que o recurso enterprise sso_enforcement esteja licenciado (disponível nos planos team e enterprise).
2. Em Admin Settings > Security, ative a opção SSO Enforcement.
3. Defina um break-glass username: esta é a única conta local que ainda pode fazer login com senha, para acesso de emergência caso o IdP esteja inacessível.

Quando a aplicação obrigatória de SSO está ativa, qualquer tentativa de login local (exceto para o usuário break-glass) retorna um erro 403 com a mensagem "Local password login is disabled. Please use SSO."

TIP

Sempre configure um break-glass username antes de habilitar a aplicação obrigatória de SSO. Sem ele, você poderá ficar bloqueado fora do SnapOtter se o seu IdP cair.

Usando SAML junto com OIDC

SAML e OIDC podem ser habilitados simultaneamente. Quando ambos estão ativos, a página de login mostra botões separados para cada provedor (rotulados por SAML_PROVIDER_NAME e OIDC_PROVIDER_NAME). Os usuários podem fazer login com qualquer um dos métodos.

Ambos os provedores compartilham as mesmas configurações de criação automática, vinculação automática e aplicação obrigatória de SSO de forma independente: cada um tem suas próprias variáveis *_AUTO_CREATE_USERS, *_AUTO_LINK_USERS e *_DEFAULT_ROLE.

Solução de problemas

Falha na validação da asserção

A assinatura da resposta SAML ou a assinatura da asserção não pôde ser verificada. Verifique:

• O certificado em SAML_IDP_CERTIFICATE corresponde ao certificado de assinatura atual no seu IdP (certificados são renovados, então verifique a expiração)
• O certificado está em formato PEM (começa com -----BEGIN CERTIFICATE-----)
• O certificado é o texto completo, não um caminho de arquivo
• A ACS URL e o Entity ID configurados no seu IdP correspondem exatamente aos valores do SnapOtter (esquema, host, porta, caminho)

Atributos ausentes

Se os nomes de usuário ou e-mails estiverem vazios após o login, seu IdP pode não estar enviando os atributos esperados. Verifique:

• Seu IdP está configurado para liberar um atributo email (ou o que quer que SAML_EMAIL_ATTRIBUTE esteja definido)
• Se estiver usando SAML_USERNAME_ATTRIBUTE, verifique se esse atributo está incluído na asserção
• Alguns IdPs exigem configuração explícita de mapeamento de atributos antes de liberarem as claims

Desvio de relógio

As asserções SAML incluem condições de timestamp (NotBefore, NotOnOrAfter). Se o relógio do seu servidor e o relógio do IdP estiverem fora de sincronia, a validação da asserção falha. Rode NTP em ambas as máquinas para manter os relógios alinhados.

"SAML is enabled via env but saml_sso enterprise feature is not licensed"

Este aviso aparece nos logs do servidor quando SAML_ENABLED=true mas a licença não inclui o recurso saml_sso. Verifique sua chave de licença e seu plano. O recurso saml_sso está disponível nos planos team e enterprise.

O login redireciona de volta com erro

Se clicar no botão de login SAML redireciona de volta para a página de login com um erro, verifique os logs do servidor para detalhes. Causas comuns:

• A IdP SSO URL está inacessível a partir do servidor
• O IdP rejeitou a requisição de autenticação (verifique os logs de auditoria do IdP)
• O IdP retornou uma resposta não assinada (o SnapOtter exige que tanto a resposta quanto a asserção sejam assinadas)