LDAP Authentication
From LinuxWiki
The Lightweight Directory Access Protocol (LDAP) is a very common way to store account information. Once stored, it can be retrieved easily and quickly by machines on the network for any purpose from userid lookup to login authentication to email address searches. And because all this information is stored in one place, it is easy to manage and backup.
Contents |
The LDAP article has more information but, in brief, an LDAP server
stores objects within a hierarchy of groups. The posixAccount
object class holds all the information normally found in
/etc/passwd and /etc/shadow. The posixGroup
object class holds the information found in /etc/group.
Every object is uniquely identified by a "distinguishedName" (or
"dn") that also tells where in the hierarchy the object is stored.
For example, the object with the distinguished name
uid=bcwhite,ou=People,dc=precidia
would be the "uid=bcwhite" object in the "ou=People" section that is a branch off the base "dc=precidia". Neither a section or the base (sometimes called the "suffix") has to be a single item; in fact, it's common to use multiple "dc" ("domainComponent") items when specifying the base (i.e. dc=precidia,dc=com).
When performing authentication, it is typical to create the "organizationalUnit" ("ou" for short) sections "People" and "Groups" to start. Other common sections are "Hosts" (or "Machines") and "Services". In fact, units can be created for protocols, netgroups, automounts, and more, but only those first four will be discussed below. In truth, it doesn't really matter what these sections are named since the authentication matches against the class type and not the name of the unit it is stored within. Still, it's good to be consistent as many management programs default to those names.
The LDAP Server
Before account information can be stored, there must first be a place to store it. The OpenLDAP project provides the SLAPD server and the tools (ldapadd, ldapsearch, and ldapmodify) to manually access the directory.
Package installation of the server is possible with every major Linux distribution but it can always built/installed from source if so desired.
SLAPD v2.2
What follows was done against v2.2.23 of the SLAPD server but is assumed to be accurate for all versions in the 2.2 branch. If you wish to add information about a later version of SLAPD, please duplicate this section; don't just list the differences. If anything, older versions should be a diff from newer versions.
Once the server is installed, it is necessary to make sure it has all the required information to store the people and group objects. Usually, this will have all been done by the package maintainer and will involve the following in the global section (at the top) of the /etc/ldap/slapd.conf configuration file:
# Schema and objectClass definitions include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema #include /etc/ldap/schema/samba.schema
The last line will be needed for supporting Windows authentication via Samba but doesn't come with the SLAPD software. We'll add it later if needed.
Further below, within a database definition, you'll want to set the base/suffix and the password hashing mechanism. The most secure password hash supported is "SSHA" (Salted-SHA). Also, set a global administration access DN ("distinguishedName") that can be used for initial configuration and population of the directory. This should reasonably secure but it'll eventually be disabled so a simple "crypt" password will suffice. Generate one of these using perl:
# "secret" is password, "XX" is salt (use any two letters or numbers)
perl -e 'print crypt("secret","XX"),"\n"'
XXIABNgk3eFuw
Make sure you use a password that will not be used anywhere else! Include this value in the "rootpw" line below.
# The base of your directory in database #1 suffix "dc=precidia"
# password hash algorithm
password-hash {SSHA}
# Admin (root) access
rootdn cn=root,dc=precidia
rootpw {crypt} XXIABNgk3eFuw
Be sure to change all "dc=precidia" fields to match whatever is appropriate for your network. E.g. dc=example,dc=com
Next, add some rules to allow appropriate access to the fields. Some of these may have come in the default configuration file. This assumes an actual "admin" user (uid number 2000 or higher) with a valid login. This account should exist but not have a valid shell (since it is to be used for services administration and not actual login).
# The userPassword by default can be changed by the entry owning it if they
# are authenticated. Others should not be able to see it, except the admin.
access to attrs=userPassword
by dn="uid=admin,ou=People,dc=precidia" write
by anonymous auth
by self write
by * none
When using password aging to force password changing, the following is also needed:
access to attrs=shadowLastChange
by dn="uid=admin,ou=People,dc=precidia" write
by self write
by * read
Note: There seems to be a small security security problem with this in that it is possible for a user to update their shadowLastChange entry without actually changing their password. It should also be possible to combine the previous two rules by just listing the attributes together separated by a comma, but it didn't work when I tried it.
Lastly, create all the appropriate indices for best possible performance:
index objectClass eq index cn pres,sub,eq index sn pres,sub,eq index uid pres,sub,eq index displayName pres,sub,eq index uidNumber eq index gidNumber eq index memberUid eq index sambaSID eq index sambaDomainName eq index default sub
Once all these changes are in, stop the SLAPD server, remove all the files in the directory where the database is stored, and then restart it. It is now ready to accept account information.
References
Account Information
Once an LDAP server is available, it must be populated either by hand or via an automated migration script using existing /etc/passwd and /etc/group information.
Migrating Existing UNIX Information
The easiest way to get started is with an ldapmigrate script. It will read the existing system information and populate the LDAP server with basic account information.
Before you do the migration, perform any user maintenence you wish to do. It is a good idea to have the id numbers of all network users and groups fall within a certain range. Mixing the id numbers of different account types can cause complications later on. For example:
- 0-999: System Accounts (not network authenticated)
- 1000-1999: Local Users (not network authenticated)
- 2000-2999: Administration Accounts (network authenticated)
- 3000-3999: Service Accounts (network authenticated)
- 4000-9999: reserved
- 10000-39999: Network Users (network authenticated)
- 40000-59999: Network Hosts (network authenticated)
- 60000-64999: reserved
- 65000-65535: System Accounts (not network authenticated)
With a set-up like this, you can have the LDAP server manage all accounts with numbers ranging from 2000 to 60000. If using number ranges different than this, it will be necessary to modify some of the values listed below.
Create all the groups that will be used/needed. This may include domain administrators, domain users, and domain guests. The accounts all need special RIDs but those can be changed later.
Now, run the ldapmigrate script to import your current information: (shell variables are used for convienence and to shorten the command lines)
LDAPBIND="cn=root,dc=precidia" LDAPPASS="secret" LDAPBASE="dc=precidia" LDAPHOST="localhost" ldapmigrate -D $LDAPBIND -w $LDAPPASS -b $LDAPBASE -h $LDAPHOST --extschema --extconts --prepdb ldapmigrate -D $LDAPBIND -w $LDAPPASS -b $LDAPBASE -h $LDAPHOST --extschema --minuid=2000 --mingid=2000 -f /etc/passwd passwd ldapmigrate -D $LDAPBIND -w $LDAPPASS -b $LDAPBASE -h $LDAPHOST --extschema --minuid=2000 --mingid=2000 -f /etc/group group
It's important to use the "--extschema" option so that the objects will be ready to accept Samba information. If you're not going to be doing Windows authentication, this parameter can be omitted but it doesn't really save anything and will be quite limiting if it becomes necessary to include Windows in the future.
Starting From Scratch
Creating the directory manually involves using ldapadd to create all of the organizationalUnits by hand.
dn: ou=Domains,dc=precidia ou: Domains objectClass: top objectClass: organizationalUnit
The LDAP Account Manager (described below) can do most of this for you.
Please expand on this point if you actually do it this way.
References
- Linux Journal -- OpenLDAP Everywhere
- Guru Labs -- ldapmigrate script page
- Guru Labs -- original ldapmigrate script
Account Managment
Once the directory is created, it still has to be managed. An administrator must be able to create and alter account information. This section describes some tools for doing that.
The LDAP Account Manager is for a joint Unix and Windows account system but should be perfectly usable for just one or the other.
The PHP LDAP Administrator is a generic LDAP interface. It knows nothing about the organization of accounts but rather provides a raw interface to the objects and structure themselves.
LDAP Account Manager v0.4
What follows was done against v0.4.9 of the LDAP Account Manager but is assumed to be accurate for all versions in the 0.4 branch. If you wish to add information about a later version of LAM, please duplicate this section; don't just list the differences. If anything, older versions should be a diff from newer versions.
Once the LDAP Account Manager is installed, it is necessary to perform initial configuration via it's web interface. Just point a web browser at
http://ldap-server/lam/
and a login screen should appear. If not, then re-check the installation. Before logging in, first go to the "configuration login" selection in the upper-right corner. The default password is "lam". Change the settings to include the LDAP base/suffix that was defined in the SLAPD configuration, above.
UserSuffix: ou=people,dc=precidia GroupSuffix: ou=groups,dc=precidia HostSuffix: ou=hosts,dc=precidia DomainSuffix: ou=domains,dc=precidia PasswordHash: SSHA
Then set the "ranges" fileds according to how your userids are organized. To match the example given above, these would be set to:
Minimum UID Number: 2000 Maximum UID Number: 40000 Minimum GID Number: 2000 Maximum GID Number: 40000 Minimum Machine Number: 40000 Maximum Machine Number: 60000
The list of valid users is all the people that can do account management. In the SLAPD configuration above, there was only one defined; enter it here:
uid=admin,ou=People,dc=precidia
Finally, set a new configuration password (to replace the default "lam"). NOTE: This is not the "admin" password! It is used only to allow access to this configuration screen and is not served in any way by the LDAP server.
Submit these settings and go back to the main login screen. It should now be possible to log in using as "admin" with the password for that account. If not, something is misconfigured above. Try LDAP Troubleshooting.
Congratulations! You just accomplished your first authentication against the LDAP server. Life is good.
LAM will likely prompt to create some new structures upon first login. Do that. It will then prompt to create a new Windows/Samba domain account. To get the SID from a Samba server, run the command
net getlocalsid precidia
on that server where "precidia" is the domain's name. Enter the resulting number string in to LAM and create the domain.
Once past all that and in to the main interface, all user and group information is available for change. See the LDAP Account Manager article for more information on using this tool.
LDAP Account Manager v1.0
What follows was done against v1.0.1 of the LDAP Account Manager but is assumed to be accurate for all versions in the 1.0 branch. If you wish to add information about a later version of LAM, please duplicate this section; don't just list the differences. If anything, older versions should be a diff from newer versions.
Once the LDAP Account Manager is installed, it is necessary to perform initial configuration via it's web interface. Just point a web browser at
http://ldap-server/lam/
and a login screen should appear. If not, then re-check the installation. Before logging in, first go to the "configuration login" selection in the upper-right corner. The default password is "lam". Click "Edit Account Types" to set these:
Users Suffix: ou=People,dc=precidia Groups Suffix: ou=Groups,dc=precidia Hosts Suffix: ou=Hosts,dc=precidia Domains Suffix: ou=Domains,dc=precidia
Then click on the "Edit Modules" to set these modules:
Users: sambaSamAccount, posixAccount, shadowAccount, inetOrgPerson Groups: posixGroup, sambaGroupMapping Hosts: account, sambaSamAccount, posixAccount Domains: sambaDomain
Change the settings to include the LDAP base/suffix that was defined in the SLAPD configuration, above.
Server Address: ldap://ldap-server:389 Tree Suffix: dc=precidia PasswordHash: SSHA
Then set the "ranges" fileds according to how your userids are organized. To match the example given above, these would be set to:
Users: Minimum UID Number: 2000 Maximum UID Number: 40000 Hosts: Minimum UID Number: 40000 Maximum UID Number: 60000 Groups: Minimum GID Number: 2000 Maximum GID Number: 40000
The list of valid users is all the people that can do account management. In the SLAPD configuration above, there was only one defined; enter it here:
uid=admin,ou=People,dc=precidia
Finally, set a new configuration password (to replace the default "lam"). NOTE: This is not the "admin" password! It is used only to allow access to this configuration screen and is not served in any way by the LDAP server.
Submit these settings and go back to the main login screen. It should now be possible to log in using as "admin" with the password for that account. If not, something is misconfigured above. Try LDAP Troubleshooting.
Congratulations! You just accomplished your first authentication against the LDAP server. Life is good.
LAM will likely prompt to create some new structures upon first login. Do that. It will then prompt to create a new Windows/Samba domain account. To get the SID from a Samba server, run the command
net getlocalsid precidia
on that server where "precidia" is the domain's name. Enter the resulting number string in to LAM and create the domain.
Once past all that and in to the main interface, all user and group information is available for change. See the LDAP Account Manager article for more information on using this tool.
PHP LDAP Admin v?.?
todo
References
Linux Authentication
Now that an LDAP server exists, it is time to configure the linux hosts to use it for user account information and authentication.
The keys to it all are nsswitch (network service switch) and PAM (pluggable authentication modules). The former defines where to look up user and general network information while the latter defines a sequence of modules to try for all authentication related activities; one of the supported modules is the pam_ldap module.
Network Service Switch
The file /etc/nsswitch.conf defines how to look up all user and network information. Each line gives a type of information followed by a list of places to look for that information. Each is tried in order until a match is found. These three lines will do it all; other lines can usually be left untouched.
# /etc/nsswitch.conf passwd: files ldap group: files ldap shadow: files ldap
To configure the nsswitch-ldap module, edit the /etc/libnss-ldap.conf and place the following lines:
# /etc/libnss-ldap.conf: uri ldap://hostname.of.ldap.server base dc=precidia
As soon as this is done, the system should be able to look up network usernames for files when doing "ls -l".
Pluggable Authentication Modules
Being able to lookup user information is the first part; PAM allows authentication so users can log in. Configuration of this system involves several files in /etc/pam.d but the exact nature of these files may differ across distributions. There should be one file for each authentication service (login, account, session, passwd, etc.) but there may be more, too.
Debian PAM
The Debian GNU/Linux system, once installed uses "@include" directives within the files to include a set of common files. This ensures that all activities are performed with the same set of applicable settings.
# /etc/pam.d/common-account account sufficient pam_unix.so account sufficient pam_ldap.so account required pam_deny.so
# /etc/pam.d/common-auth auth sufficient pam_ldap.so auth sufficient pam_unix.so shadow use_first_pass auth required pam_deny.so
# /etc/pam.d/common-session session sufficient pam_ldap.so session required pam_unix.so
# /etc/pam.d/common-password password requisite pam_passwdqc.so min=12,10,10,8,6 random=25 retry=3 passphrase=2 password sufficient pam_ldap.so type=network use_authtok first_pass password sufficient pam_unix.so type=machine use_authtok md5 password required pam_deny.so
The first line here can be omitted if you don't want to support quality checking of new passwords.
Lastly, the pam_ldap module itself needs to be configured so it knows how to reach the server.
# /etc/pam_ldap.conf host admin1.ott.precidia.com base dc=precidia ldap_version 3 rootbinddn uid=admin,ou=People,dc=precidia pam_filter &(objectclass=posixAccount)(!(uidNumber=0)) pam_password exop
Once all of this is done, you should be able to "su - user" and become that user. Simple, no?
Red Hat PAM
Red Hat comes with the configuration tool authconfig that can be used to set up authentication through a LDAP server. As of the moment I have been able to configure Red Hat PAM to correctly look users up but checking encrypted password is broken, this applies to both passwords encrypted on the server and the LDAP directory. If anyone has a good solution to this please add it here.
SSH
The SSH daemon needs
UsePAM yes
in its /etc/ssh/sshd_config file in order to use PAM and LDAP authentication. Without this, users can log in with a public key but not with password authentication.
Caching
There is a programm called "nscd" (network services cache daemon) that can be installed (and may have been done so automatically) to locally cache this information. This will reduce the number of calls to the LDAP server, thus reducing its load and improving local response time.
References
Samba Authentication
Samba is a open-source system for interfacing with Windows systems using the SMB (aka "LanMan") protocol. The main project page for Samba is here.
All Linux distributions should provide packages for the installation of Samba.
Samba v3.0
What follows was done against v3.0.14a and v3.0.22 of the Samba system but is assumed to be accurate for all versions in the 3.0 branch. If you wish to add information about a later version of Samba, please duplicate this section; don't just list the differences. If anything, older versions should be a diff from newer versions.
First off, within the Samba package, find the samba.schema file. It's location varies and it may be compressed. Once found, uncompress it (if neccessary) and copy the file under the /etc/ldap/schema directory. Then add (or uncomment) the line to include this schema:
# /etc/ldap/slapd.conf include /etc/ldap/schema/samba.schema
Within the /etc/samba/smb.conf file, change or add the following lines to describe how to access the LDAP server.
# /etc/samba/smb.conf passdb backend = ldapsam:ldap://hostname.of.ldap.server ldap admin dn = uid=samba,ou=Services,dc=precidia ldap suffix = dc=precidia ldap user suffix = ou=People ldap group suffix = ou=Groups ldap idmap suffix = ou=Idmap ldap machine suffix = ou=Hosts ldap replication sleep = 1000 ldap passwd sync = true ldapsam:trusted = true
Note: Some smb.conf man pages incorrectly state that each of the specific suffices (i.e. user, group, idmap, & machine) replace the default "ldap suffix" for that item. In fact, they only prepend to that default. Also, don't put quotes around the values.
These settings assume a user "samba" created in the "Services" unit of te directory. This can be created via a program like [[PHP LDAP Admin]] or manually on the command like as such:
$ ldapadd -D cn=root,dc=precidia -w secret -b dc=precidia -h localhost dn: uid=samba,ou=Services,dc=precidia objectClass: top objectClass: account objectClass: posixAccount cn: Samba Server uid: samba uidNumber: 3000 gidNumber: 3000 homeDirectory: /tmp ^D ldappasswd -x -D cn=root,dc=precidia -w secret -h localhost -s SOMETHING uid=samba,ou=Services,dc=precidia
The last command sets the password for the "uid=samba,ou=Services,dc=precidia" account to "SOMETHING". Obviously, choose something other than SOMETHING. The reason for creating a special service account with these permissions is because it's stored on disk by Samba. As such, it's not good to use an ordinary user account which may require it's password changed if an employee leaves or something. To tell samba wat the access password is, do:
smbpasswd -w SOMETHING
Finally, that account has to be given special permission in the "slapd.conf" file so Samba can update records in the directory as it runs. To do that, change the admin rule (given previously) to something like:
access to *
by dn="uid=admin,ou=People,dc=precidia" write
by dn="uid=samba,ou=Services,dc=precidia" write
by * read
At the same time, add the following so that the Samba passwords are protected against casual viewing. Why? These encrypted passwords are actually "plain text equivalents" which means that knowing them allows access just as though one knew the original password from which they were derived -- thank you, Microsoft security experts.
access to attrs=sambaLMPassword,sambaNTPassword
by dn="uid=samba,ou=Services,dc=precidia" write
by * none
Restarting Samba should happen quickly. If it appears to hang while starting "smbd" then there is probably problems accessing the ldap server. The /var/log/syslog file on the LDAP server may have useful information as to what was being accessed. Also, try the Troubleshooting page.
If Samba's log level is set to zero, some versions of the "smbd" process will exit quietly on an LDAP failure. The LDAP activity found in /var/log/syslog can be quite helpful but don't expect it to be easy. Setting the "log level" parameter in the smb.conf file to 10 (ten) may provide enough information to diagnose the problem.
At this point, it should be possible to use Windows Explorer to browse the Samba host (just type "\\hostname" in to the address field) and access shared drives using usernames and password that were imported in to the LDAP directory. Connecting to the domain still needs more work, though.
Connecting new hosts to a domain needs a privileged account. The "admin" account used previously won't suffice because that had its information originally imported from a unix account, a non-root account to be specific (since the minuid was non-zero). For domain connections to work in samba, though, the privileged account provided must be user-id 0 (yes, ZERO). This is unfortunate as it means you have a root account in the ldap directory, but we'll mitigate this risk as much as possible. Log out of the LDAP Account Manager and do a "configuration login". Set the minimum UID number to "0" (zero), submit, and login normally. Edit the "admin" user (or even better, create a new user) and set the UID number to 0 and, for extra security, make sure the login shell to /bin/false, too. UID number 0 is also prevented from login via the part of the "pam_filter" line that says "!(uidNumber=0)". When done change the minimum UID back to what you want.
Aside: Why is this? I understood this requrirement when Samba had to create new local accounts and thus access system files, but it seems to still be the case for LDAP directories where full permission is given via the admin's DN.
Lastly, you have to choose between manual or automatic addition of new hosts.
Manual Host Addition
You can use the LDAP Account Manager to manually add all new hosts before connecting them to the domain, or you can have samba create those accounts during the first join attempt.
Automatic Host Addition
For now, I'm just sticking with the manual addition. There appears to be no easy way to get samba to do it automatically via LDAP, though there are some instructions here. Configuration is complex and I was unable to get the tools to work properly. That's annoying! This should be a built-in feature of Samba! (Or perhaps it is, and I just couldn't find it.)
References
- Samba -- Account Information Databases
- Samba v3 PDC HowTo
- Storing Samba's User/Machine Account information in an LDAP Directory
- LDAP Samba on Solaris 9
- Samba TNG and Unix Accounts with LDAP
Cyrus Authentication
The Cyrus mail server can be configured to use either SASL for authentication and thus PAM like general user authentication or LDAP directly. Which will be used is done as part of the installation. You'll need v2 (or later) of Cyrus for this to work.
Cyrus PAM
todo
Cyrus LDAP
Edit the /etc/saslauthd.conf file so it looks like this:
ldap_servers: ldap://ldap.host.domain/ ldap_search_base: dc=precidia
Once the saslauthd program is running, test it with a command like:
testsaslauthd -u userid -p password
If it doesn't work (i.e. you don't get an "OK" result), you may need more options in the /etc/saslauthd.conf file. You may have received a LDAP_SASLAUTHD file (perhaps somewhere under /usr/share/doc) with details of those options. If not, try one of the references below or search Google.
Once that is working, you still need to tell cyrus to use this service. In the /etc/imapd.conf, make sure of the following settings:
# Authentication via SASL and LDAP sasl_pwcheck_method: saslauthd sasl_mech_list: PLAIN allowplaintext: yes
The documents I used while writing this specified "allowplaintext: no" but that did not work for me. This does.
If you have the imtest program installed, you can test this out with a command like
imtest -a userid localhost
It should tell you "authenticated" if everything is okay.
References
Clean Up
Disable (comment-out) your "rootdn" and "rootpw" lines within the /etc/ldap/slapd.conf file now that you're done with them.
Additional Steps
Well, that's it. The steps given above should yield a fully functional authentication system supporting both Linux and Windows. Of course, there is always more you can do...
Replication
When managing a large site, it may be beneficial to create one or more slave servers. These slaves keep copies of the directory, informed immediately by the master upon any change, and serve the information to clients. If a modification request is made, they automatically redirect that request to the master. See SLAPD#Replication for more information.
Secure LDAP
How to enable and use LDAPS...
Host Name Resolution
How to use LDAP for hostname resolution instead of DNS...
Be sure to use IP addresses when specifying LDAP hosts! You can't use LDAP hostname resolution to find the address for an LDAP server from it's hostname.
