#language: en

= Authentication by querying a ldap-server =

Any user who is a member of our institute can log in to all machines which
are enabled to authenticate via ldap.
This way of authentication works, because the TU Wien provides information
on its members via a central ldap server, dc.intern.tuwien.ac.at.

In Linux, all authentication and authorization is handled by the pam stack
(Pluggable Authentication Module). To enable authentication by ldap,
a pam-ldap module is added to the stack. With that in place, if a user is not found in the
local passwd file, a bind to the ldap-server is tried. If the credentials by the
user match the credentials at the ldap-server, which remain unknown to the local
machine, the user can log in. The bind to the ldap-server is done via an
specifically created account given in the configuration file.

In addition the name service switch, nss, provides information on services to
the operating system.
For instance, an `ls -l` maps the user id of file owners and displays user
names.
The nss library provides the user name.

The packages needed for authentication via ldap are installed with
{{{
apt-get install libpam-cap libpam-systemd libpam-ldapd libnss-ldapd
# Useful is a name service caching daemon
apt-get install nscd
}}}

== Pam stack ==

The pam-stack is made ldap-aware by running `pam-auth-update ldap`,
after installing the packages given above.
This will add the lines containing `pam_ldap.so` to the files
attachment:common-account,
attachment:common-auth,
attachment:common-password,
attachment:common-session and
attachment:common-session-noninteractive
which reside in `/etc/pam.d`, see below.

In addition, the pam_mkhomedir module, see man pam_mkhomedir(8), is added
manually in [attachment:common-session /etc/pam.d/common-session]
to create a users home directory on login if it does not exist yet.

{{{
pam-auth-update ldap

--- /etc/pam.d./common-account.orig
+++ /etc/pam.d/common-account
# and here are more per-package modules (the "Additional" block)
+account [success=ok new_authtok_reqd=done ignore=ignore user_unknown=ignore authinfo_unavail=ignore default=bad]        pam_ldap.so minimum_uid=1000
# end of pam-auth-update config

--- /etc/pam.d./common-auth.orig
+++ /etc/pam.d/common-auth
# here are the per-package modules (the "Primary" block)
-auth    [success=1 default=ignore]      pam_unix.so nullok_secure
+auth    [success=2 default=ignore]      pam_unix.so nullok_secure
+auth    [success=1 default=ignore]      pam_ldap.so minimum_uid=1000 use_first_pass
# here's the fallback if no module succeeds

--- /etc/pam.d./common-password.orig
+++ /etc/pam.d/common-password
# here are the per-package modules (the "Primary" block)
-password        [success=1 default=ignore]      pam_unix.so obscure sha512
+password        [success=2 default=ignore]      pam_unix.so obscure sha512
+password        [success=1 default=ignore]      pam_ldap.so minimum_uid=1000 try_first_pass
# here's the fallback if no module succeeds

--- /etc/pam.d./common-session.orig
+++ /etc/pam.d/common-session
# and here are more per-package modules (the "Additional" block)
session required        pam_unix.so
+session [success=ok default=ignore]     pam_ldap.so minimum_uid=1000
session optional        pam_systemd.so
# end of pam-auth-update config
+
+# Thomas Loimer, 2015-11-06
+session required        pam_mkhomedir.so        skel=/etc/skel umask=0022

--- /etc/pam.d./common-session-noninteractive.orig
+++ /etc/pam.d/common-session-noninteractive
# and here are more per-package modules (the "Additional" block)
session required        pam_unix.so
+session [success=ok default=ignore]     pam_ldap.so minimum_uid=1000
# end of pam-auth-update config
}}}

== Nslcd daemon ==

The pam_ldap modules from the package libpam_ldapd and the Name Service Switch
library libnss_ldap.so connect to the ldap server via an ldap daemon.
The ldap daemon is provided by the package nslcd.
The account E322_LDAP is used to bind to the ldap-server.
This account was created by zid.
The configuration of the ldap daemon is given in
[attachment:nslcd.conf /etc/nslcd.conf].

It is necessary to install the nslcd daemon, because this daemon can use
variables to construct attributes from the record retrieved from the ldap
server.
See, for instance, the construction of the homeDirectory attribute in the passwd
database from the content of sAMAccountName in the ldap record.

To construct gid-numbers, it is necessary to pass the part of the
objectSid which should be shadowed, i.e., the domain SID, see nslcd.conf and man
nslcd.conf(5).

== Name service switch ==

To make the nss-library ldap aware, add `ldap` after `compat` in
the passwd, group and shadow lines in
[attachment:nsswitch.conf /etc/nsswitch.conf].

== Name service cache daemon ==

To reduce network load and, for instance,
avoid querying the ldap server for each `ls`,
name service information is cached by the name service cache daemon.
This daemon is provided by the package nscd.
In the configuration file, [attachment:nscd.conf /etc/nscd.conf],
timeouts of caching were increased, and caching for some services  was disabled.

== Tests ==

Try ldapsearch from any machine to see whether a bind to the ldap-server works.
For intance, to list people affiliated with E322, do
{{{
ldapsearch -D CN="Loimer Thomas (tloimer)",OU=people,OU=TU,DC=intern,DC=tuwien,DC=ac,DC=at \
    -b "ou=people,ou=tu,dc=intern,dc=tuwien,dc=ac,dc=at" -H ldaps://dc.intern.tuwien.ac.at
    -LLL -W departmentNumber=E322 sAMAccountName
}}}

On s15, the following should list all users who can log in to s15:
{{{
# On s15
getent passwd
getent shadow
}}}