1 nss-pam-ldapd - NSS and PAM libraries for name lookups and authentication 2 using LDAP 3 4 nss-pam-ldapd started as nss-ldapd which was a fork from nss_ldap which was 5 originally written by Luke Howard of PADL Software Pty Ltd. 6 7 In 2006 Arthur de Jong of West Consuling forked the library to split it 8 into a thin NSS part and a server part. Most of the code was rewritten. 9 10 The software was renamed to nss-pam-ldapd when PAM code contributed by 11 Howard Chu for the OpenLDAP nssov module was integrated. Solaris 12 compatibility was developed by Ted C. Cheng of Symas Corporation. 13 14 https://arthurdejong.org/nss-pam-ldapd/ 15 16 Copyright (C) 1997-2006 Luke Howard 17 Copyright (C) 2006-2007 West Consulting 18 Copyright (C) 2006-2018 Arthur de Jong 19 Copyright (C) 2009 Howard Chu 20 Copyright (C) 2010 Symas Corporation 21 22 This library is free software; you can redistribute it and/or 23 modify it under the terms of the GNU Lesser General Public 24 License as published by the Free Software Foundation; either 25 version 2.1 of the License, or (at your option) any later version. 26 27 This library is distributed in the hope that it will be useful, 28 but WITHOUT ANY WARRANTY; without even the implied warranty of 29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 30 Lesser General Public License for more details. 31 32 You should have received a copy of the GNU Lesser General Public 33 License along with this library; if not, write to the Free Software 34 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 35 02110-1301 USA 36 37 38INTRODUCTION 39============ 40 41This is the nss-pam-ldapd library which consists of an NSS module to do name 42lookups to an LDAP directory server and a PAM module to do authentication to 43an LDAP server. The NSS part of this library was forked from nss_ldap as 44provided by Luke Howard of PADL Software Pty Ltd. The PAM module was mostly 45provided by Howard Chu of the OpenLDAP project. 46 47The NSS library allows distributing account, group, host and other 48configuration information from a central LDAP server. Because LDAP is a 49hierarchical directory service, information can be organised in a manner which 50reflects an organisational structure. This contrasts with the flat, single 51domain policy of NIS. LDAP has many of the advantages of NIS+ (security and 52scalability) without the complexity. The system will work alongside your 53existing NIS, NIS+, DNS and flat file name services. 54 55The PAM library (module) can be used to perform authentication based on 56information inside the LDAP directory. 57 58Both libraries consist of a thin NSS or PAM part that proxies the requests to 59a local daemon (nslcd) that handles the LDAP lookups. This simplifies the 60software architecture and fixes some scalability and locking problems in the 61original design of nss_ldap. 62 63It is also possible to use the thin NSS and PAM modules together with the 64nssov overlay in the OpenLDAP server (slapd). 65 66The three parts (NSS module, PAM module, and nslcd server) can be built 67separately and are not strongly tied together. This means that for instance 68you can still use pam_ldap and use the NSS module from nss-pam-ldapd or use an 69alternative implementation of nslcd (for instance with the nssov slapd overlay 70or the pynslcd implementation). 71 72improvements over nss_ldap 73-------------------------- 74 75The fork from nss_ldap was done to implement some major design changes to fix 76some structural problems in the library. 77 78One of those problems were host name lookups through LDAP which could cause 79deadlocks. Another is that nss_ldap loaded an SSL library into executables 80that may not be designed to load it (e.g. problem with suid applications). 81 82A number of refactoring steps were done to simplify the code and improve 83maintainability. Legacy code was removed and support for non-Linux operating 84systems was initially removed to make the code more readable. Portability was 85re-added using compatibility wrappers. 86 87The most practical improvements over nss_ldap are: 88- the LDAP library is not loaded for every process doing LDAP lookups 89- the number of connections to the LDAP server is limited, because not every 90 process will open its own connection 91- hostname lookups should now be deadlock-free because the LDAP server name is 92 no longer looked up using the ldap method 93- avoid problems with TLS connections in suid binaries and other process-local 94 configuration 95- it is easier to debug because logging in nslcd can be enabled without 96 the need to restart all processes doing name lookups 97- unavailability timeouts are global instead of per-process 98 99comparison to pam_ldap 100---------------------- 101 102The PAM module that is currently implemented contains functionality for 103authentication, account management, password management and session 104management. The nslcd daemon currently implements authentication, 105authorisation and password modification. The OpenLDAP nssov overlay also 106implements session functionality. 107 108supported C libraries (for NSS module) 109-------------------------------------- 110 111This library currently supports the GNU C Library, the Solaris C library and 112the FreeBSD C library. 113 114supported name databases 115------------------------ 116 117Currently the following name databases are supported: 118 119 aliases, ethers, group, hosts, netgroup, networks, passwd, protocols, rpc, 120 services and shadow 121 122When using IPv6 ipHostNumber attributes, the address in LDAP must be in the 123preferred form as defined in section 2.2 of RFC1884, specifically the format 124as returned by inet_ntop(3). All leading zeros should be omitted and the 125longest range of zeroes should be replaced with :: (e.g. 126fe80::218:bff:fe55:c9f). 127 128MAC addresses in the macAddress attribute should be in maximal, colon 129separated hex notation (e.g. 00:00:92:90:ee:e2). 130 131automounter map lookups (which are also defined in /etc/nsswitch.conf) are 132currently not supported because the NSS interface is not used for these. The 133common autofs implementation (on GNU/Linux) currently uses its own method for 134getting the maps from LDAP. 135 136Although mail aliases are exposed through NSS, most mail servers parse 137/etc/aliases themselves (bypassing NSS) and getting aliases from LDAP requires 138some configuration in the mail server. 139 140The publickey, bootparams and netmasks are currently unsupported. Some 141investigation should be done if these are needed for anything, which 142interfaces should be exported and how the LDAP schema part should look like. 143 144supported PAM implementation 145---------------------------- 146 147The PAM module is currently only regularly tested on Linux PAM but other PAM 148implementations should also work. 149 150supported LDAP libraries 151------------------------ 152 153The current version of nss-pam-ldapd has been developed with OpenLDAP 2.4 but 154other LDAP libraries and older versions of OpenLDAP may also work. 155 156unsupported features 157-------------------- 158 159Since nss-pam-ldapd was forked from nss_ldap most of the features that came 160with nss_ldap are available. The most important differences: 161- the configuration file formats are not fully compatible 162- rootbinddn/rootbindpw support is removed and is not likely to return 163 (the rootpwmoddn and rootpwmodpw work differently but accomplish the same 164 thing) 165 166For the PAM module some functionality is missing. Comparing it to pam_ldap: 167- only BIND authentication is supported 168- only LDAP password modify EXOP is supported as password changing mechanism 169 170Some things work a little different in nss-pam-ldapd. For instance the 171attribute defaults and overrides of nss_ldap are implemented with mapping 172expressions and pam_ldap's pam_check_*_attr options can be implemented with 173the pam_authz_search option. 174 175 176INSTALLATION 177============ 178 179The nss-pam-ldapd library uses autoconf and automake for building. Installing 180nss-pam-ldapd should be as simple as: 181 182 % ./configure 183 % make 184 % make install 185 186It is a good idea to first go through the options of configure by running: 187 188 % ./configure --help 189 190The last step (make install) should install the libnss_ldap.so.* and 191pam_ldap.so files and the daemon (nslcd). The proper location of the NSS and 192PAM modules are guessed. The boot process needs to be modified to start the 193nslcd daemon at the right time. 194 195It is recommended to create a dedicated user for the nslcd daemon. Configure 196this user in /etc/nslcd.conf using the uid and gid options. 197 198 199CONFIGURATION 200============= 201 202After installation, the name service switch configuration file 203(/etc/nsswitch.conf) needs to be modified to do name lookups using the new 204module. This consist mostly of adding ldap in the list of lookup methods in 205the right place. See the nsswitch.conf(5) manual page for details on the 206format. As an example the file could look a little like this: 207 208 # the following contain normal unix user and group information 209 passwd: files ldap 210 group: files ldap 211 shadow: files ldap 212 213 # hostname lookups through ldap before dns should work now 214 hosts: files ldap dns 215 networks: files ldap 216 217 # normal flat-file definitions 218 protocols: files ldap 219 services: files ldap 220 ethers: files ldap 221 rpc: files ldap 222 netgroup: ldap 223 224 # whether alias lookups really use NSS depends on the mail server 225 aliases: files ldap 226 227Configuring PAM differs a little from platform to platform but this is a 228minimal set-up for files under /etc/pam.d: 229 230 auth sufficient pam_unix.so 231 auth sufficient pam_ldap.so use_first_pass 232 auth required pam_deny.so 233 234 account required pam_unix.so 235 account sufficient pam_ldap.so 236 account required pam_permit.so 237 238 session required pam_unix.so 239 session optional pam_ldap.so 240 241 password sufficient pam_unix.so nullok md5 shadow use_authtok 242 password sufficient pam_ldap.so try_first_pass 243 password required pam_deny.so 244 245Lastly, a configuration file for nslcd (by default /etc/nslcd.conf) needs to 246be made. See the shipped manual page for details on the format and options. It 247should at the very least contain something like: 248 249 # the location of LDAP server 250 uri ldap://localhost/ 251 252 # search base for all queries. 253 base dc=example,dc=net 254 255service discovery through DNS 256----------------------------- 257 258nss-pam-ldapd supports looking up LDAP server names through DNS SRV records as 259specified in RFC 2782. However, Priority and Weight are not considered 260separately and a single list of servers in added as if they had been specified 261with uri options in the configuration file. 262 263To use this feature specify DNS as an uri in the configuration file and 264include something like the following in your zone: 265 266 _ldap._tcp SRV 10 0 389 ldapserver 267 268 269LDAP SCHEMA 270=========== 271 272nss-pam-ldapd supports a wide range of possible LDAP schema configurations and 273it can be customized heavily. The LDAP schema used is described in RFC 2307. 274Groups using the member attribute that hold distinguished names (RFC 2307bis) 275are also supported (but see group membership below for more information). 276 277default attributes 278------------------ 279 280This paragraph describes the mapping between the NSS lookups and the LDAP 281database. The mapping may be modified by changing the nslcd.conf configuration 282file. See the nslcd.conf(5) manual page for details. 283 284aliases (objectClass=nisMailAlias) 285 cn - alias name 286 rfc822MailMember - members of the alias (recipients) 287ethers (objectClass=ieee802Device) 288 cn - host name 289 macAddress - ethernet address 290group (objectClass=posixGroup) 291 cn - group name 292 userPassword - password (by default mapped to "*") 293 gidNumber - gid 294 memberUid - members (user names) 295 member - members (DN values) 296hosts (objectClass=ipHost) 297 cn - host name (and aliases) 298 ipHostNumber - addresses 299netgroup (objectClass=nisNetgroup) 300 cn - netgroup name 301 nisNetgroupTriple - triplets describing netgroup entries 302 memberNisNetgroup - reference to other netgroup 303networks (objectClass=ipNetwork) 304 cn - network name 305 ipNetworkNumber - network address 306passwd (objectClass=posixAccount) 307 uid - account name 308 userPassword - password (by default mapped to "*") 309 uidNumber - uid 310 gidNumber - gid 311 gecos - gecos 312 homeDirectory - home directory 313 loginShell - shell 314protocols (objectClass=ipProtocol) 315 cn - protocol name 316 ipProtocolNumber - protocol number 317rpc (oncRpc) 318 cn - rpc name 319 oncRpcNumber - rpc number 320services (objectClass=ipService) 321 cn - service name 322 ipServicePort - service port 323 ipServiceProtocol - service protocol 324shadow (objectClass=shadowAccount) 325 uid - use name 326 userPassword - password 327 shadowLastChange - date of last password change 328 shadowMin - days before password may be changed again 329 shadowMax - days after which password must be changed 330 shadowWarning - days before max password age to present a warning 331 shadowInactive - days after max password age that account is disabled 332 shadowExpire - account expiration date 333 shadowFlag - reserved field 334 335using Microsoft Active Directory 336-------------------------------- 337 338When using Microsoft Active Directory server some changes need to be made to 339the nslcd.conf configuration file. The included sample configuration file has 340some commented out attribute mappings for such a set-up. 341 342group membership 343---------------- 344 345Currently, two ways of specifying group membership are supported. The first, 346by using the memberUid attribute, is the simplest and by far the fastest 347(takes the least number of lookups). The attribute values are user names (same 348as the uid attribute for posixAccount entries) and are returned without 349further processing. 350 351The second method is to use DN values in the member attribute (attribute names 352can be changed by using the attribute mapping options as described in the 353manual page). This is potentially a lot slower because in the worst case every 354DN has to be looked up in the LDAP server to find the proper value for the uid 355attribute. 356 357If the LDAP server supports the deref control (provided by the deref overlay 358in OpenLDAP) the DN to uid expansing is performed by the LDAP server. 359 360If the DN value already contains a uid value (e.g. uid=arthur, dc=example, 361dc=com) a further lookup is skipped and the uid value from the DN is used. 362 363For other DN values an extra lookup is performed to expand it to a uid. These 364lookups are cached and are configurable with the cache dn2uid configuration 365option. 366 367The member attribute may also contain the DN of another group entry. These 368nested groups are parsed recursively depending on the nss_nested_groups 369option. 370 371Currently, the memberOf attribute in posixAccount entries is unsupported. 372 373case sensitivity 374---------------- 375 376Most values in NSS databases are considered case-sensitive (e.g. the user 377"Foo" is a different user from the user "foo"). Most values in an LDAP 378database are however considered case-insensitive. nss-pam-ldapd tries to solve 379this problem by adding an extra filtering layer to ensure that when looking 380for the user "foo" it will not consider a user "Foo" that is found in LDAP. 381 382For the group, netgroup, passwd, protocols, rpc, services and shadow maps the 383matches will be checked case-sensitively and for aliases, ethers, hosts and 384networks matches will be case-insensitive (this seems to be what Glibc is 385doing currently in flat files). Only searching for groups by user is done 386case-insensitive. In all cases the case-use in the LDAP directory is returned. 387 388This behaviour can be disabled with the ignorecase configuration option but 389may be a security risk. 390 391Note that having entries that only differ in case is a bad idea and will 392likely get you in trouble. One example of such a problem is that the DN 393uid=test,dc=example,dc=com is considered the same in LDAP as 394uid=TEST,dc=example,dc=com. 395 396 397REPORTING BUGS 398============== 399 400If you find any bugs or missing features please send email to 401 nss-pam-ldapd-users@lists.arthurdejong.org 402If you are using a packaged version of nss-pam-ldapd you are encouraged to use 403the distributor's bug tracking system. Please include as much information as 404possible (platform, output of configure if compilation fails, error messages, 405output of nslcd -d, etc). Patches are more than welcome (also see the file 406HACKING). 407