Como Configurar o Login SAML em uma Instância Mastodon Auto-hospedada

Administradores de instâncias Mastodon auto-hospedadas frequentemente precisam integrar um provedor de identidade existente para permitir que usuários façam login com suas credenciais corporativas ou organizacionais. O login único baseado em SAML elimina a necessidade de senhas separadas do Mastodon e centraliza o gerenciamento de usuários por meio de um provedor como Azure Active Directory, Okta ou OneLogin. Este artigo explica como configurar a autenticação SAML em uma instância Mastodon auto-hospedada rodando em um servidor Linux. Você aprenderá as variáveis de ambiente necessárias, as etapas para modificar o arquivo de configuração do Mastodon e como testar o fluxo de login de ponta a ponta.

Entendendo a Autenticação SAML no Mastodon

O Mastodon usa o framework OmniAuth para suportar provedores de autenticação externos. Por padrão, o Mastodon vem com suporte embutido para provedores OAuth como Twitter e Facebook. Para SAML, você deve adicionar a gem Ruby omniauth-saml e configurar variáveis de ambiente que informam ao Mastodon onde encontrar seu provedor de identidade e como lidar com a resposta SAML.

A autenticação SAML funciona através de um fluxo de redirecionamento do navegador. Quando um usuário clica no botão de login SAML na página de login do seu Mastodon, o Mastodon envia uma solicitação de autenticação SAML para o provedor de identidade. Após o usuário se autenticar no IdP, o IdP envia uma asserção SAML de volta ao Mastodon. O Mastodon valida a asserção usando a impressão digital do certificado ou a URL de metadados que você configurou e, em seguida, cria ou faz login na conta do usuário.

Pré-requisitos

Antes de começar, confirme que os seguintes itens estão em vigor:

• Uma instância Mastodon auto-hospedada rodando Mastodon 3.5 ou posterior em um servidor Linux com acesso root ou sudo.
• Acesso ao painel de administração do seu provedor de identidade. Você precisa da URL de metadados SAML ou da impressão digital do certificado do IdP.
• A URL de callback SAML para o Mastodon: https://SEU_DOMINIO/auth/auth/saml/callback
• Uma conta de usuário registrada no servidor Mastodon com privilégios de administrador para testar a configuração.

Passos para Habilitar o Login SAML no Mastodon

1. Adicione a gem omniauth-saml ao seu Gemfile
   Conecte-se via SSH ao seu servidor Mastodon. Navegue até o diretório de instalação do Mastodon, geralmente /home/mastodon/live. Abra o Gemfile com um editor de texto como nano ou vim. Adicione esta linha ao final do arquivo: gem 'omniauth-saml', '~> 2.1'. Salve e feche o arquivo.
2. Instale a gem com bundle
   Execute bundle install como o usuário mastodon. Este comando lê o Gemfile atualizado e instala a gem omniauth-saml junto com suas dependências. Aguarde a conclusão da instalação. Se encontrar um erro de permissão, execute o comando com o prefixo sudo -u mastodon.
3. Configure as variáveis de ambiente para SAML
   Edite o arquivo .env.production localizado no diretório de instalação do Mastodon. Adicione ou modifique as seguintes variáveis. Substitua SEU_DOMINIO, SEU_ISSUER e SUA_URL_IDP_SSO pelos valores do seu provedor de identidade.
   SAML_ISSUER=https://SEU_DOMINIO
SAML_IDP_SSO_TARGET_URL=https://SUA_URL_IDP_SSO
SAML_IDP_CERT_FINGERPRINT=SUA_IMPRESSÃO_DIGITAL
SAML_CALLBACK_URL=https://SEU_DOMINIO/auth/auth/saml/callback
OMNIAUTH_ONLY=false
   Se seu IdP fornecer uma URL de metadados em vez de uma impressão digital do certificado, defina SAML_IDP_METADATA_URL em vez da variável de impressão digital. Salve e feche o arquivo.
4. Atualize a configuração do Mastodon para OmniAuth
   Abra o arquivo config/initializers/omniauth.rb no diretório do Mastodon. Adicione o bloco de configuração do provedor SAML dentro da configuração OmniAuth existente. O bloco deve ficar assim:
   provider :saml,
issuer: ENV['SAML_ISSUER'],
idp_sso_target_url: ENV['SAML_IDP_SSO_TARGET_URL'],
idp_cert_fingerprint: ENV['SAML_IDP_CERT_FINGERPRINT'],
callback_url: ENV['SAML_CALLBACK_URL']
   Se você usar uma URL de metadados, substitua a linha de impressão digital por idp_metadata_url: ENV['SAML_IDP_METADATA_URL']. Salve e feche o arquivo.
5. Pré-compile assets e reinicie os serviços do Mastodon
   Execute RAILS_ENV=production bundle exec rails assets:precompile para compilar a configuração OmniAuth atualizada. Em seguida, reinicie os serviços do Mastodon com systemctl restart mastodon-web e systemctl restart mastodon-sidekiq. Se você usar um gerenciador de processos diferente, reinicie os serviços apropriados.
6. Teste o fluxo de login SAML
   Abra uma janela de navegador privada e navegue até a página de login da sua instância Mastodon. Você deve ver um botão de login SAML. Clique nele. Você será redirecionado para a página de login do seu provedor de identidade. Insira credenciais válidas. Após a autenticação bem-sucedida, você será redirecionado de volta ao Mastodon e estará logado. Se o login falhar, verifique o log de produção do Mastodon em log/production.log para mensagens de erro.

Erros Comuns na Configuração SAML e Como Evitá-los

Incompatibilidade na URL de callback SAML causa erros de redirecionamento

A URL de callback no Mastodon deve corresponder exatamente à URL ACS registrada em seu provedor de identidade. Muitos IdPs exigem o caminho completo, incluindo a barra no final. Verifique se o valor em .env.production corresponde à URL ACS na configuração do seu IdP. Uma incompatibilidade comum é usar http em vez de https ou omitir o caminho /auth/auth/saml/callback.

A validação da impressão digital do certificado falha

O Mastodon espera a impressão digital SHA1 do certificado do IdP. Se você fornecer uma impressão digital SHA256 ou o certificado completo no formato PEM, a validação falhará. Obtenha a impressão digital correta baixando o XML de metadados do IdP e extraindo o valor SHA1 do elemento . Alternativamente, use a opção de URL de metadados para permitir que o Mastodon busque o certificado automaticamente.

Usuários não conseguem se cadastrar via SAML

Por padrão, o Mastodon cria uma nova conta de usuário local na primeira vez que um usuário autenticado por SAML faz login. Se o registro de usuários estiver desabilitado em sua instância, defina OMNIAUTH_ONLY=true no .env.production. Essa configuração permite que usuários SAML façam login mesmo quando o registro aberto está desativado. Lembre-se de que os usuários ainda precisam ter uma conta existente no banco de dados do Mastodon se você não habilitar a criação automática de contas.

Login SAML vs Registro Integrado: Principais Diferenças

Item	Login SAML	Registro Integrado
Método de autenticação	Provedor de identidade externo	Banco de dados local do Mastodon
Gerenciamento de senhas	Gerenciado pelo IdP	Gerenciado pelo Mastodon
Criação de conta	Automática no primeiro login SAML	Manual através do formulário de registro
Autenticação multifator	Fornecido pelo IdP	TOTP ou WebAuthn do Mastodon
Mapeamento de atributos do usuário	Email, nome de usuário da asserção SAML	Definido pelo usuário durante o registro

Após a configuração bem-sucedida do SAML, sua instância Mastodon pode aplicar políticas de autenticação centralizadas da sua organização. Os usuários não precisam mais lembrar de uma senha separada do Mastodon. Para aumentar ainda mais a segurança, configure seu provedor de identidade para exigir autenticação multifator antes de liberar a asserção SAML. Se depois você decidir trocar de provedor de identidade, atualize apenas as variáveis de ambiente no .env.production e reinicie o serviço web do Mastodon. A URL de callback SAML permanece a mesma, desde que o domínio do seu Mastodon não mude.