A newer version of this documentation is available.

View Latest

Configure saslauthd

      saslauthd is a daemon process that handles plaintext authentication requests on behalf of the SASL library.

      In LDAP authentication, the saslauthd process handles authentication requests on behalf of Couchbase Server while the LDAP protocol is used to connect to the LDAP server.

      Note that remote authentication with the LDAP server requires proper configuration of the saslauthd agent, which must be installed and configured on each Couchbase Server node.

      Supported Packages

      Install your Unix operating system with the saslauthd package that is supported for LDAP integration.

      Make sure that you have the prerequisites for the LDAP software you are installing, such as OpenLDAP libraries. On RPM-based distros, installation packages are a part of cyrus-sasl rpm, so make sure that it is installed.

      CentOS 6

      saslauthd 2.1.23 or higher

      CentOS 7

      saslauthd 2.1.26 or higher


      saslauthd 2.1.25 or higher


      saslauthd 2.1.23 or higher


      Make sure your LDAP setup is working, by running a test ldapsearch as follows:

      ldapsearch -LLL -H ldap://ldapserver:389 -D cn=someuser,ou=users,dc=mydomain,dc=com -w Passw0rd -x -bou=users,dc=mydomain,dc=com cn=someuser

      Install saslauthd

      Install the saslauthd package on your operating system. On Ubuntu, install saslauthd with the following command:

      sudo apt-get install sasl2-bin

      Determine mux File Location

      To communicate with the LDAP server, Couchbase Server makes use of the mux file provided by the saslauthd package. The location of the mux file varies, according to distribution. Couchbase Server checks for the file at two locations, which are /var/run/sasl2/mux and /var/run/saslauthd/mux.

      • Debian/Ubuntu: By default, the file is located at /var/run/sasl2/mux.

      • RHEL/CentOS 6: By default, the file is located at at /var/run/saslauthd/mux.

      • RHEL/CentOS 7: By default, the file is located at /run/saslauthd/mux; but a symlink from /var/run to /run/ allows Couchbase Server to access the file at /var/run/saslauthd/mux.

      If, on your system, the location of the mux file is neither /var/run/sasl2/mux nor /var/run/saslauthd/mux, set the CBAUTH_SOCKPATH environment variable to the mux file’s actual location. Couchbase Server will attempt to access the mux file there.

      Getting Started with saslauthd and LDAP

      1. Ensure that the Couchbase Cluster is running. Then, enable external authentication on the cluster, using the Couchbase CLI setting-ldap command: specifying server IP-address and port number, username and password:

         $ couchbase-cli setting-ldap -c -u Administrator -p passw0rd --ldap-enabled 1

        Note that --ldap-enabled 1 enables external authentication, and --ldap-enabled 0 disables. See setting-ldap for further information. When successfully executed, the command provides the following notification: SUCCESS: LDAP settings modified.

      2. Configure the MECHANISMS option for ldap.

        Red Hat Enterprise Linux, CentOS, and Amazon Linux AMI edit /etc/sysconfig/saslauthd (/etc/default/saslauthd on Debian/Ubuntu) to set the mechanism MECH to ldap:


        Ubuntu and Debian edit /etc/default/saslauthd, setting MECHANISMS option to ldap:


        On Debian and Ubuntu, you should also add Couchbase to the sasl group:

        sudo adduser couchbase sasl
      3. The default configuration file used to obtain the LDAP configuration parameters is located at /usr/local/etc/saslauthd.conf. Open this in your editor of choice.

      4. Set up ldap_servers

        Specify URIs of the LDAP servers used for authentication, such as ldap:///, ldap:// Multiple LDAP servers can be specified in the list, which is then tested to find out whether one of the servers is offline. If you install OpenLDAP on the local host machine, you can specify the value ldap://localhost:389.

        If using LDAP over SSL, you can specify the value ldaps://localhost:636.

        ldap_servers: ldaps:// ldaps://
      5. Set up ldap_search_base

        Specify the distinguished name to which the search is relative. The search includes the base or objects below.

        It also includes Domain Components (dc) such as in dc=company and dc=com.

        The administrative users created in LDAP with the attribute uid are placed under the user’s organizational unit ou under the two domain components (example and com).

        ldap_search_base: ou=Users,dc=company,dc=com
      6. Set up ldap_filter

        Specify the search filter. The values for these configuration options correspond to the values specific to the test. For example, to filter on email specify ldap_filter: (mail=%n).

        ldap_filter: (uid=%u)

        Configure LDAP options /etc/saslauthd.conf:

        ldap_servers: ldaps://ad.example.net
        ldap_search_base: ou=Users,dc=example,dc=com
        ldap_filter: (uid=%u)
      7. Running automatically

        For sasld to run automatically on start up, you’ll need to change the START value to YES.

        START = yes
      8. Test yoursaslauthdset-up.

        If the connection is properly working, the user couchbase must have access to /var/run/saslauthd/mux (or the appropriate alternate directory for SUSE), in order to communicate to saslauthd.

        1. Start the saslauthd service (or set it to start automatically with chkconfig).

          service saslauthd restart
          Stopping saslauthd:                             [  OK  ]
          Starting saslauthd:                             [  OK  ]
          chkconfig  saslauthd on
          chkconfig --list saslauthd
          saslauthd   	0:off   1:off   2:on	3:on	4:on	5:on	6:off
        2. Test saslauthd by using the testsaslauth script to test LDAP authentication:

          sudo -u couchbase /usr/sbin/testsaslauthd -u <username> \
          -p mypassword -f /var/run/saslauthd/mux
          0: OK "Success."
      9. Restart the Couchbase service, to allow authentication through the changed configuration.

        $ sudo service couchbase-server restart


      Putting the above steps into typical configuration files:

      cat /etc/saslauthd.conf
      # ldap_servers: ldap:<URI>:<PORT> or ldaps:<URI>:<PORT> for TLS protected connection
      ldap_servers: ldap://my.company.com:389
      # The administrative users created in LDAP with the attribute uid are placed under the user's
      # organizational unit ou under the two domain components (example and com).
      ldap_search_base: OU=InteractiveUsers,DC=my,DC=company,DC=com
      # Specifies the search filter. The values for these configuration options correspond to the
      # values specific to the test
      ldap_filter: uid=%u
      # Optional: specify a user to perform ldap queries
      ldap_bind_dn: CN=user_ldap,OU=Users,DC=my,DC=company,DC=com
      # Optional: specify ldap user’s password
      ldap_password: -sEcReTp#AssWoRd!
      cat /etc/sysconfig/saslauthd
      # Just keep the default
      # Make sure MECH is set to ldap (pam is default)
      # Include the config file described above
      FLAGS="-O /etc/saslauthd.conf"

      Configuring saslauthd with Windows Active Directory

      A common requirement is to delegate some or all authentication to another LDAP server. Here is a sample saslauthd configuration that uses Microsoft Active Directory (AD) as the LDAP server:

      Here is a sample saslauthd configuration with Microsoft Active Directory (AD):

      ldap_servers: ldap://dc1.example.com:<port>
      ldap_search_base: cn=Users,DC=ad,DC=example,DC=com
      ldap_filter: sAMAccountName=%u
      ldap_bind_dn: cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com
      ldap_password: secret

      Troubleshooting LDAP Settings

      After you set up the LDAP server, saslauthd, and LDAP administrators, likely causes of problems include:

      • Firewall ports are not open for LDAP.

      • The Proxy did not start or has started with an inappropriate protocol or hostname.

      • The configuration of saslauthd is incorrect (look at /etc/sysconfig/saslauthd or /etc/saslauthd.conf)

      • The LDAP filters are not correct.

      • You can also encounter error messages from the system. These errors belong either to issues caused by saslauthd or the LDAP server.