Configuring SciDB as a PAM Client

PAM is only supported in SciDB Enterprise Edition.

This page describes how to set up a SciDB server as a Pluggable Authentication Modules (PAM) client.  PAM is intended to hide the details of client authentication, so many different back end authentication services can be used.  By way of concrete example, this page focuses on using the pam_ldap.so module to authenticate against an external LDAP server.  Other PAM module / authentication service combinations should work with some configuration effort.  (The References section at the end of this page may be helpful.)

Even if you plan to use a non-LDAP authentication service, read over this page in its entirety to familiarize yourself with some of the issues involved in using PAM-based authentication.

LDAP Client Software

This section assumes that a server running LDAP software (such as OpenLDAP) is already up and running on host ldap.example.com .  To get SciDB to use that server for authentication, you must install an LDAP PAM client on every SciDB host that will act as a query coordinator—that is, on every host that will terminate an incoming SciDB client connection.

Installing the nss-pam-ldapd Package (CentOS 7, Red Hat 7, Ubuntu 14)

Most supported Linux distributions use the nss-pam-ldapd package for PAM authentication via LDAP.  This package installs both the pam_ldap.so module and nslcd, the LDAP name service daemon.  All PAM module LDAP queries are mediated by nslcd.

After installing the nss-pam-ldapd package, edit the /etc/nslcd.conf file to add base and uri entries.  (On some distributions, the package installer will interactively ask for this information during the install.)

base  dc=example,dc=com
uri   ldap://ldap.example.com

The base is the LDAP distinguished name (DN) of the root of the directory tree exported by the server.  (It corresponds to the olcSuffix value you use when configuring an OpenLDAP server.)  Usually (but not always) the base DN is derived from the server's domain name.

The uri has scheme ldap: and the hostname or IP address of the desired LDAP server.  If the LDAP server is configured for TLS transport layer encryption, the uri would start with ldaps: rather than ldap: .

The /etc/nslcd.conf file may require this line:

filter passwd (uid=*)

This directive should only be needed if user accounts on the LDAP server are not defined with an objectClass: posixAccount attribute.  See https://serverfault.com/questions/633802/ldap-authentication-on-centos-7 .

Starting nslcd on CentOS 7 / Red Hat 7

These distributions use the systemd systemctl command to manage system daemons.

Use systemctl(1) to register the nslcd daemon for startup on boot, and start it.

$ sudo systemctl enable nslcd.service
$ sudo systemctl start nslcd.service

Or, if the nslcd daemon was already running,

$ sudo systemctl restart nslcd.service

Starting nslcd on Ubuntu 14

This distribution uses the SysV chkconfig and service command to manage system daemons.

Use chkconfig(8) to register the nslcd daemon for startup on boot, then use service(8) to start it.

$ sudo chkconfig --add nslcd
$ sudo service nslcd status
nslcd is stopped
$ sudo service nslcd start
Starting nslcd:                                            [  OK  ]
$ sudo service nslcd status
nslcd (pid  8079) is running...

Installing the pam_ldap package (CentOS 6, Red Hat 6)

On CentOS 6 and Red Hat 6, install the pam_ldap package instead of nss-pam-ldapd.  This package installs a pam_ldap.so module that communicates directly with the LDAP server, rather than indirectly through an nslcd daemon.

After installing the pam_ldap package, edit the /etc/pam_ldap.conf file to add base, host, and uri entries.

base dc=example,dc=com
host ldap.example.com
uri ldap://ldap.example.com

If the LDAP server is configured for TLS transport layer encryption, the uri would start with ldaps: rather than ldap: .

On CentOS 6 and Red Hat 6 there is no additional daemon to configure and start, so you are done.

Encrypting PAM Back End Communication

Whether the back end authentication service is LDAP or something else, the PAM module will need to send cleartext passwords to it.  Therefore connections to the back end service must be protected using transport layer encryption, typically certificate-based encryption using TLS.  Managing TLS certificates varies not only across different operating system releases but also across organizational boundaries.  You should confer with your organization's IT staff about how to obtain and deploy the certificates you need.

Directives in the /etc/nslcd.conf file (or the /etc/pam_ldap.conf file for CentOS 6 or Red Hat 6) determine how PAM will encrypt traffic to the LDAP server and what certificates and ciphers will be used.  Consult the nslcd.conf(5) or pam_ldap(5) manual page.

OpenLDAP can serve both TLS and non-TLS traffic using the ldap: URI scheme.  Use a packet sniffer such as wireshark to make sure authentication traffic between the query coordinator hosts and the LDAP server is encrypted.

Set up SciDB's PAM configuration

Create a mode 644 file named /etc/pam.d/scidb with the following contents:

auth     sufficient pam_ldap.so
auth     required   pam_deny.so
account  sufficient pam_ldap.so
password sufficient pam_ldap.so
session  optional   pam_ldap.so

You can enable debug logging by placing the token debug at the end of each pam_ldap.so line.  PAM log messages are written to /var/log/secure .

Start SciDB in security=pam mode

  1. Load the namespaces library with iquery -aq "load_library('namespaces')"
  2. Edit the /opt/scidb/<version>/etc/config.ini file to set security=pam
  3. Restart the SciDB cluster
  4. Try to log in as one of the LDAP users:

    $ cat /tmp/alice.auth 
    [security_password]
    user-name=alice
    user-password=alpha
    $
    $ iquery -A /tmp/alice.auth -a
    AFL% 
    AFL% show_user();
    {i} name
    {0} 'alice'
    AFL%
    AFL%  -- Victory!  ;
    AFL% quit;
    $ 

The SciDB user scidbadmin (and its compatibility alias root) can always log in to SciDB, even if PAM authentication is not working.  The scidbadmin user need not have an entry in the LDAP directory tree.

THEREFORE, THE scidbadmin USER'S DEFAULT PASSWORD MUST BE CHANGED BEFORE MAKING SciDB AVAILABLE TO USERS.  If you do not change the scidbadmin password, attackers can use the factory default password to log in to SciDB with full privileges, even though other users must be authenticated by PAM.   See User Accounts for a description of how to change passwords for local users, and follow the directions there to change the password of the scidbadmin account.

Other PAM Configuration Options

SciDB's PAM behavior can be tailored using the pam-options parameter in the /opt/scidb/<version>/etc/config.ini file.  The value of this parameter is a comma-separated list that can contain the following keywords:

KeywordDefault?Meaning
dba-Authenticate the scidbadmin user via PAM.  (If PAM authentication fails, try to authenticate locally as a last resort.)
nodbaXAuthenticate the scidbadmin user locally, without calling PAM library routines.  This is the default.
session-Call pam_open_session(3) (and pam_close_session(3)) when opening (and closing) an iquery shell or SciDB TCP connection.
nosessionXDo not call pam_open_session(3) or pam_close_session(3). This is the default.
setcred-Call pam_setcred(3) when opening an iquery shell or SciDB TCP connection.
nosetcredXDo not call pam_setcred(3). This is the default.

For example, to enable both credential setting and session management, add this line to config.ini :

pam-options=session,setcred


Troubleshooting Tips

nslcd

To see debug logging from the LDAP client-side daemon, stop it with sudo systemctl stop nslcd.service (or sudo service nslcd stop for CentOS 6 or Red Hat 6) and run it from the shell with sudo /usr/bin/nslcd -d

PAM

The PAM module pam_ldap.so sends log messages to /var/log/secure .  For maximum debug logging, add the debug keyword to each pam_ldap.so line in the /etc/pam.d/scidb file.

The SciDB namespaces plugin PAM code uses the same logger, scidb.services.network.auth, that is used by all the authentication code, and 17.7 ships with this logger configured for TRACE logging.

LDAP

You will need to disable TLS to see unencrypted packet contents with wireshark.  LDAP uses TCP port 389 for unencrypted traffic, and TCP port 636 for TLS traffic.

On an OpenLDAP server, you can dump the database contents to stdout using slapcat(8C).  With no arguments it shows the directory information tree (DIT), with -n 0 it shows the cn=config configuration.

For maximum debug output on the OpenLDAP server host, stop the slapd server and run it from the command line:

$ sudo /usr/sbin/slapd -d 65535 -u ldap -h "ldap:/// ldaps:///"

References

Blog posts, HOWTOs and tutorials

Books, e- and tree

Software docs