How to Set Up SAML Login on a Self-Hosted Mastodon Instance

Self-hosted Mastodon instance administrators often need to integrate with an existing identity provider to allow users to sign in with their corporate or organizational credentials. SAML-based single sign-on eliminates the need for separate Mastodon passwords and centralizes user management through a provider such as Azure Active Directory, Okta, or OneLogin. This article explains how to configure SAML authentication on a self-hosted Mastodon instance running on a Linux server. You will learn the required environment variables, the steps to modify the Mastodon configuration file, and how to test the login flow end to end.

Understanding SAML Authentication in Mastodon

Mastodon uses the OmniAuth framework to support external authentication providers. By default, Mastodon ships with built-in support for OAuth providers such as Twitter and Facebook. For SAML, you must add the omniauth-saml Ruby gem and configure environment variables that tell Mastodon where to find your identity provider and how to handle the SAML response.

SAML authentication works through a browser redirect flow. When a user clicks the SAML login button on your Mastodon sign-in page, Mastodon sends a SAML authentication request to the identity provider. After the user authenticates at the IdP, the IdP sends a SAML assertion back to Mastodon. Mastodon validates the assertion using the certificate fingerprint or metadata URL you configured, then creates or logs in the user account.

Prerequisites

Before you begin, confirm the following items are in place:

• A self-hosted Mastodon instance running Mastodon 3.5 or later on a Linux server with root or sudo access.
• Access to your identity provider administration panel. You need the SAML metadata URL or the IdP certificate fingerprint.
• The SAML callback URL for Mastodon: https://YOUR_DOMAIN/auth/auth/saml/callback
• A registered user account on the Mastodon server with admin privileges to test the configuration.

Steps to Enable SAML Login on Mastodon

1. Add the omniauth-saml gem to your Gemfile
   SSH into your Mastodon server. Navigate to the Mastodon installation directory, typically /home/mastodon/live. Open the Gemfile with a text editor such as nano or vim. Add this line at the end of the file: gem 'omniauth-saml', '~> 2.1'. Save and close the file.
2. Install the gem with bundle
   Run bundle install as the mastodon user. This command reads the updated Gemfile and installs the omniauth-saml gem along with its dependencies. Wait for the installation to complete. If you encounter a permission error, run the command with sudo -u mastodon prefix.
3. Configure environment variables for SAML
   Edit the .env.production file located in the Mastodon installation directory. Add or modify the following variables. Replace YOUR_DOMAIN, YOUR_ISSUER, and YOUR_IDP_SSO_URL with values from your identity provider.
   SAML_ISSUER=https://YOUR_DOMAIN
SAML_IDP_SSO_TARGET_URL=https://YOUR_IDP_SSO_URL
SAML_IDP_CERT_FINGERPRINT=YOUR_CERT_FINGERPRINT
SAML_CALLBACK_URL=https://YOUR_DOMAIN/auth/auth/saml/callback
OMNIAUTH_ONLY=false
   If your IdP provides a metadata URL instead of a certificate fingerprint, set SAML_IDP_METADATA_URL instead of the fingerprint variable. Save and close the file.
4. Update the Mastodon configuration for OmniAuth
   Open the config/initializers/omniauth.rb file in the Mastodon directory. Add the SAML provider configuration block inside the existing OmniAuth setup. The block should look like this:
   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']
   If you use a metadata URL, replace the fingerprint line with idp_metadata_url: ENV['SAML_IDP_METADATA_URL']. Save and close the file.
5. Precompile assets and restart Mastodon services
   Run RAILS_ENV=production bundle exec rails assets:precompile to compile the updated OmniAuth configuration. Then restart the Mastodon services with systemctl restart mastodon-web and systemctl restart mastodon-sidekiq. If you use a different process manager, restart the appropriate services.
6. Test the SAML login flow
   Open a private browser window and navigate to your Mastodon instance sign-in page. You should see a SAML login button. Click it. You are redirected to your identity provider login page. Enter valid credentials. After successful authentication, you are redirected back to Mastodon and logged in. If the login fails, check the Mastodon production log at log/production.log for error messages.

Common SAML Configuration Mistakes and How to Avoid Them

SAML callback URL mismatch causes redirect errors

The callback URL in Mastodon must match exactly the ACS URL registered in your identity provider. Many IdPs require the full path including the trailing slash. Verify that the value in .env.production matches the ACS URL in your IdP configuration. A common mismatch is using http instead of https or omitting the /auth/auth/saml/callback path.

Certificate fingerprint validation fails

Mastodon expects the SHA1 fingerprint of the IdP certificate. If you provide a SHA256 fingerprint or the full certificate in PEM format, validation fails. Obtain the correct fingerprint by downloading the IdP metadata XML and extracting the SHA1 value from the element. Alternatively, use the metadata URL option to let Mastodon fetch the certificate automatically.

Users cannot sign up through SAML

By default, Mastodon creates a new local user account the first time a SAML-authenticated user logs in. If user registration is disabled on your instance, set OMNIAUTH_ONLY=true in .env.production. This setting allows SAML users to sign in even when open registration is turned off. Keep in mind that users must still have an existing account on the Mastodon database if you do not enable automatic account creation.

SAML Login vs Built-in Registration: Key Differences

Item	SAML Login	Built-in Registration
Authentication method	External identity provider	Local Mastodon database
Password management	Managed by IdP	Managed by Mastodon
Account creation	Automatic on first SAML login	Manual through registration form
Multi-factor authentication	Provided by IdP	Mastodon TOTP or WebAuthn
User attribute mapping	Email, username from SAML assertion	User-defined during registration

After successful SAML setup, your Mastodon instance can enforce centralized authentication policies from your organization. Users no longer need to remember a separate Mastodon password. To further tighten security, configure your identity provider to require multi-factor authentication before releasing the SAML assertion. If you later decide to switch identity providers, update only the environment variables in .env.production and restart the Mastodon web service. The SAML callback URL remains the same as long as your Mastodon domain does not change.