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: .

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.

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

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;
   $ 

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:

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

• How to migrate local users to LDAP accounts by RAJ itzgeek.com
• LDAP Authentication on CentOS 7, importance of nslcd.conf filter directive

• Step by Step OpenLDAP Server Configuration for CentOS 7 / RHEL 7 by RAJ at itzgeek.com

• Your OpenSSL CSR command is out of date by Mike at certsimple.com

• Why systemd? by Jorgen Schäfer

Books, e- and tree

• Butcher, Matt, Mastering OpenLDAP

• Lucas, Michael, PAM Mastery

• Zytrax.com, LDAP for Rocket Scientists

Software docs

• OpenLDAP
• nss-pam-ldapd