documentation/Running-Mastodon/Enabling-LDAP-login.md

Enabling LDAP login

Follow this guide to use LDAP for external authentication of users. When a user logs in to the Mastodon instance, their username and password will be verified by authenticating (binding) to an LDAP server. If a user exists in the LDAP directory and logs in to the Mastodon instance for the first time, a user account will be auto-created on the Mastodon instance for them.

Configuring LDAP settings

Then, edit your .env.production file to contain the following settings. Example values are given here, but you'll need to fill in values appropriate for your site.

• LDAP_ENABLED=true
  • This enables LDAP authentication. Note that you'll also need to set this environment variable when running Mastodon and when running bundle install, e.g. during upgrades, so that the gem(s) required for LDAP support are installed.
• LDAP_METHOD=start_tls
  • This sets the method to use for TLS encryption of the communications between Mastodon and the LDAP server. The possible values are:
    • start_tls - Connect to the LDAP server, send an LDAP request to perform a Start TLS operation, wait for a successful LDAP response, then start the TLS handshake. Normally uses port 389.
    • simple_tls - Immediately start the TLS handshake after connecting to the LDAP server, before sending any LDAP traffic. Normally uses port 636.
• LDAP_HOST=your.ldap.server
• LDAP_PORT=389
  • Set these to the hostname and port to connect to of your LDAP server. The standard port for LDAP is 389, but if you are using LDAP_METHOD=simple_tls you will need to specify the port that your LDAP server is expecting TLS connections on - this is normally port 636.
• LDAP_BASE=dc=your,dc=domain
  • Mastodon will search for user accounts in the subtree rooted at this base. Set this to the base DN (Distinguished Name) of your directory tree in the LDAP server.
• LDAP_BIND_DN=uid=mastodon,ou=example,dc=your,dc=domain
• LDAP_PASSWORD=somepassword
  • When Mastodon needs to search for a user account in your LDAP server, it will first authenticate (bind) to the server using these credentials to do the search. It's recommended to create a service account for Mastodon in your LDAP directory, and give it a strong password. Then use the DN (Distinguished Name) and password of the service account for these settings.
• LDAP_UID=uid
  • Set this to the LDAP attribute name that you want to use for the username part of Mastodon account names, when users log in using LDAP authentication. For example, if your Mastodon instance name is social.your.domain, and your LDAP user accounts have uid attributes with values like alice and bob, you can use LDAP_UID=uid here, and their corresponding Mastodon account names will be @alice@social.your.domain and @bob@social.your.domain

Troubleshooting

• If you see an error like Net::LDAP::Error (SSL_connect returned=1 errno=0 state=error: certificate verify failed) logged when a user attempts to log in, this is probably because your LDAP server's TLS certificate is not trusted by default by OpenSSL. You need to add the LDAP server's CA certificate to the default OpenSSL trusted certificate store on the machine Mastodon runs on. For example, on Debian or Ubuntu you should add the LDAP server's CA certificate to /usr/local/share/ca-certificates/ and then run update-ca-certificates as root.
• If you see an error like this logged when a user attempts to log in:

  NoMethodError (undefined method `split' for nil:NilClass):
  app/models/email_domain_block.rb:18:in `block?'
  app/validators/blacklisted_email_validator.rb:15:in `on_blacklist?'
  app/validators/blacklisted_email_validator.rb:11:in `blocked_email?'
  app/validators/blacklisted_email_validator.rb:5:in `validate'
  app/models/user.rb:122:in `ldap_setup'
  app/models/user.rb:293:in `ldap_get_user'
  lib/devise/ldap_authenticatable.rb:29:in `authenticate!'
  app/controllers/concerns/localized.rb:14:in `set_locale'
  

  This is probably because the user has an invalid or missing mail attribute in their LDAP entry. Check the user's mail attribute in the LDAP directory.