Configure PAM
Pluggable Authentication Modules (PAM) provide an authentication framework that allows multiple, low-level authentication schemes to be used by a single API. The Enterprise Edition of Couchbase Server, running on Linux, supports administrator-authentication through PAM’s Linux password-module.
PAM Features
Used with the Enterprise Edition of Couchbase Server, the PAM Linux password-module provides:
-
External authentication: Administrator-accounts defined on Linux systems, in the
/etc/shadow
directory, can be accessed for authentication-purposes by Couchbase Server. -
Password policy-management: Linux password-management can be used across different Couchbase Server-nodes; to synchronize, maintain, and expire administrator-passwords.
Version Requirements
Use of the PAM Linux password-module requires all cluster-nodes to be Linux-based, running the Enterprise Edition of Couchbase Server, version 4.6 or above.
Additionally, the saslauthd
library version must be 2.1.x or above.
Example: Linux Password-Authentication
The following sequence shows how the PAM Linux password-module can be used with Couchbase Server 5.0 and above, to validate usernames and passwords, when administrators log into Couchbase Server.
Supervisor access, via sudo
, is required to perform most of the steps; and an editor is required, to allow you to edit configuration files.
For PAM to be fully configured, the following procedure must be performed on each node in the cluster. |
Proceed as follows:
-
Bring up a terminal, and install the
saslauthd
library for your Linux distribution:Centos/RHEL
$ yum install cyrus-sasl
Ubuntu/Debian
$ apt-get install sasl2-bin
-
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 10.142.170.101:8091 -u Administrator -p U&y54wT --ldap-enabled 1
Note that
--ldap-enabled 1
enables external authentication, and--ldap-enabled 0
disables. See cli:cbcli/couchbase-cli-setting-ldap.adoc for further information. When successfully executed, the command provides the following notification:SUCCESS: LDAP settings modified
. -
Add the
couchbase
user to thesasl
group, to allow access tosaslauthd
:$ usermod -aG sasl couchbase
-
In the
saslauthd
configuration file, verify thatsaslauthd
is set up to use PAM, by using thegrep
command, and examining the output:Centos/RHEL
$ grep "MECH" /etc/sysconfig/saslauthd MECH=pam
If output to the above command does not confirm that
MECH
is set topam
, bring up the configuration file/etc/default/saslauthd
in an editor, and manually set theMECH
parameter topam
.Ubuntu/Debian
$ grep 'MECHANISMS' /etc/default/saslauthd MECHANISMS="pam"
If output to the above command does not confirm that
MECHANISMS
is set topam
, bring up the configuration file/etc/default/saslauthd
in an editor, and manually set theMECHANISMS
parameter topam
. -
Set up PAM to authenticate the Couchbase service, by copying
/etc/pam.d/passwd
to/etc/pam.d/couchbase
.$ cp /etc/pam.d/passwd /etc/pam.d/couchbase
-
Create a Linux user on the current system, and give them a password. For example, username
don
, and passwordsecretpa$$
. (This user is the administrator who will be authenticated by PAM.)$ useradd don $ passwd secretpa$$ Enter new UNIX password:
Enter and then verify your chosen password, as prompted.
-
Access Couchbase Web Console, at
localhost:8091
, and log in. Then, access the Security tab, on the upper, horizontal control-bar. This brings up the Security view: -
Left-click on the Add User button, situated near the right. This brings up the Add New User dialog. Select the External radio-button, in the Authentication Domain panel at the upper left. Then, enter the name of the new user you are creating, and specify a suitable role, such as Cluster Admin. The panel appears as follows:
Then, left-click on Save. The newly defined user now appears in the Security view.
-
In the terminal, restart the SASL service, to allow PAM authentication to take effect.
$ service saslauthd restart
Note: When this command is successful, the output confirms that the daemon has been started. If the command fails, and the output includes a line such as
To enable saslauthd, edit /etc/default/saslauthd and set START=yes
, bring up the file/etc/default/saslauthd
in an editor, locate the line that readsSTART=no
, and change it toSTART=yes
. Then, save the file, exit, and rerun the command. -
Restart the Couchbase service, to allow external authentication through PAM to take effect.
$ service couchbase-server restart
-
In the browser, access
localhost:8091
. When the Couchbase Web Console login-interface appears, enter the username and password you previously created:Left-click on the Sign In button. The user you created is now logged into Couchbase Server, as an administrator.