A newer version of this documentation is available.

View Latest

Pluggable Authentication Modules

Pluggable Authentication Modules (PAM) is an authentication framework used by Linux and other operating systems. It enables you to integrate multiple low-level authentication schemes into a high-level application programming interface (API). Starting from version 4.6, the Enterprise Edition of Couchbase Server supports administrator authentication using PAM.

Using PAM, administrators can set up the following features:

  • External authentication: PAM support enables Linux administrator accounts defined in/etc/shadow to be used in Couchbase Server.

  • Password policy management: PAM enables you to easily control password expiration rules, and synchronize administrator passwords on all servers through Linux password management.

Although PAM provides several authentication modules, Couchbase Server PAM authentication supports only the Linux password module. PAM authentication in Couchbase Server is an enterprise only feature, and is only available on Linux platforms.

Getting Started with PAM Authentication

Linux Password Authentication Using PAM

The following walks through a sample authentication scenario which uses PAM only to check Linux user login names and passwords. Every administrator permitted to connect to Couchbase Server should have a Linux user account that is mapped to an administrator role in Couchbase Server. You’ll need root access to perform the following tasks.

  1. Install the saslauthd library for your Linux distribution, if it is not already installed, version 2.1.x or above is required.


    $ yum install cyrus-sasl


    $ apt-get install sasl2-bin
  2. If running on Ubuntu/Debian, ensure that the couchbase user is in the sasl group to allow access to saslauthd.

    $ usermod -aG sasl couchbase
  3. In the saslauthd config file, verify that saslauthd is set up to use PAM.


    $ grep "MECH" /etc/sysconfig/saslauthd

    If the above command does not return that MECH is set to pam then adjust the parameter in the config file accordingly.


    $ grep 'MECHANISMS' /etc/default/saslauthd

    If the above command does not return that MECHANISMS is set to "pam" then adjust the parameter in the config file accordingly.

  4. Set up PAM to authenticate the Couchbase service by creating a file named /etc/pam.d/couchbase. As Linux users are supported, copy /etc/pam.d/passwd to /etc/pam.d/couchbase.

    $ cp /etc/pam.d/passwd /etc/pam.d/couchbase
  5. Test that Linux authentication permits you to log in. For example, use user name: don and password: secretpa$$. You can execute this step with any other Linux credentials as well, if the user already exists then there is no need to perform the following step.

    To create a Linux user and set password, you can use the following commands:

    $ useradd don
    $ passwd don
  6. Map the Linux login name (user name) to one or many Couchbase Server administrator roles.

    security pam auth linux
  7. Re-start the SASL service for PAM authentication to take effect.

    $ service saslauthd restart
  8. Restart the Couchbase service for external authentication through PAM to take effect.

    $ service couchbase-server restart
  9. Try connecting using the Linux user credentials created earlier, don/secretpa$$.

    Couchbase Server should permit the connection, and once authenticated, the privileges of that user in Couchbase Server should be as per the role mapping.

Congratulations! You’ve successfully logged in as a Linux user, using the privileges granted through the administrator role membership.

By default, saslauthd is not started on boot. To ensure that Couchbase Server’s PAM authentication continues to work correctly after a system reboot, you should start saslauthd in your boot scripts.