Configure saslauthd
saslauthd
is a daemon process that handles plaintext authentication requests on behalf of the SASL library.
LDAP and Legacy saslauthd Authentication
Couchbase Server provides Native LDAP support. This allows external users to be authenticated by LDAP, and provides support for LDAP groups. For details on using this recommended procedure, see Configure LDAP.
The saslauthd
process can still be used to support authentication on LDAP or other servers if required.
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.
The saslauthd
agent, which must be installed and configured on each Couchbase Server node.
Note that either Native LDAP Support or saslauthd
must be selected for the cluster.
The two cannot be used simultaneously.
Note also that both Native LDAP Support and saslauthd
require clients to use the PLAIN authentication mechanism, ideally with TLS.
For an overview of authentication options on Couchbase Server, see Authentication.
Migrating from saslauthd to Native LDAP
If you have been using saslauthd
with previous versions of Couchbase Server, you are strongly recommended to migrate to Native LDAP.
See Authentication Domains for a full account of the benefits.
To migrate, proceed as follows:
-
Configure Native LDAP. This is described in detail, in Configure LDAP.
Note that the procedure provides two principal options, which are Enable LDAP user authentication and Enable LDAP group authorization & sync. During your configuration procedure:
-
You must select Enable LDAP user authentication, and then configure associated details.
-
If LDAP group authorization is required, you can select Enable LDAP group authorization & sync, and then configure associated details. Alternatively, you can leave this option disabled for now: it does not need to have been enabled, for migration to succeed. Instead, it can be enabled and configured later, after migration has been completed.
-
-
Disable
saslauthd
authentication, as follows:couchbase-cli setting-saslauthd -c 10.143.192.101:8091 -u Administrator -p password --enabled 0
-
Perform appropriate tests, to ensure that authentication with Native LDAP is working correctly.
-
If you encounter any problems, you can re-enable
saslauthd
, and continue to rely on it while you troubleshoot your environment. -
If there are no problems, stop the
saslauthd
daemon. All authentication for external users is now handled by Native LDAP.
-
This completes the migration process.
Supported Packages
If you have chosen to support external authentication by means of saslauthd
, 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 7
-
saslauthd 2.1.26
or higher - Ubuntu
-
saslauthd 2.1.25
or higher - SUSE
-
saslauthd 2.1.23
or higher
Preparation
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 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
-
Ensure that the Couchbase Cluster is running. Then, enable external authentication on the cluster, using the Couchbase CLI
setting-saslauthd
command: specifying server IP-address and port number, username and password:/opt/couchbase/bin/couchbase-cli setting-saslauthd -c 10.143.192.101 \ -u Administrator \ -p password \ --enabled 1
Note that
--enabled 1
enables external authentication, and--enabled 0
disables. See setting-saslauthd for further information. When successfully executed, the command provides the following notification:SUCCESS: saslauthd settings modified
. -
Configure the
MECHANISMS
option forldap
.Red Hat Enterprise Linux, CentOS, and Amazon Linux AMI edit /etc/sysconfig/saslauthd (
/etc/default/saslauthd
on Debian/Ubuntu) to set the mechanismMECH
toldap
:MECH=ldap
Ubuntu and Debian edit /etc/default/saslauthd, setting
MECHANISMS
option toldap
:MECHANISMS=ldap
On Debian and Ubuntu, you should also add Couchbase to the
sasl
group:sudo adduser couchbase sasl
-
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.
-
Set up
ldap_servers
Specify URIs of the LDAP servers used for authentication, such as
ldap:///10.1.1.11/
,ldap://10.1.1.12/
. 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 valueldap://localhost:389
.If using LDAP over SSL, you can specify the value
ldaps://localhost:636
.ldap_servers: ldaps://10.1.1.25 ldaps://10.1.1.15
-
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 indc=company
anddc=com
.The administrative users created in LDAP with the attribute
uid
are placed under the user’s organizational unitou
under the two domain components (example
andcom
).ldap_search_base: ou=Users,dc=company,dc=com
-
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)
-
Running automatically
For sasld to run automatically on start up, you’ll need to change the
START
value toYES
.START = yes
-
Optionally, set up TLS.
If you wish to use saslauthd with TLS, add the following to your
saslauthd.conf
file:ldap_start_tls: yes ldap_tls_cacert_dir: <your-cert-directory> ldap_tls_cacert_file: <your-crt-file>
Note that once you have added these lines, your inclusion of
ldap_start_tls: yes
means that you may not now useldaps:<ldap_server>
in your LDAP server configurations: therefore, if necessary, remove it.Note also that you can use TCPtrace, to verify that TLS is enabled between saslauthd and LDAP.
-
Test your
saslauthd
set-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 tosaslauthd
.-
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
-
Test
saslauthd
by using thetestsaslauth
script to test LDAP authentication:sudo -u couchbase /usr/sbin/testsaslauthd -u <username> \ -p mypassword -f /var/run/saslauthd/mux 0: OK "Success."
-
-
Restart the Couchbase service, to allow authentication through the changed configuration.
$ sudo service couchbase-server restart
Example
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
SOCKETDIR=/var/run/saslauthd
# Make sure MECH is set to ldap (pam is default)
MECH=ldap
# 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.