View source for Pluggable Authentication Modules (PAM)

'''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works.

=PAM introduction=

==What is PAM==
Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you.

Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file.

This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks.

Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework.

Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it.

It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files.

== Why use PAM ==

= PAM Principles =

== PAM modules - in general ==
So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this.

== PAM module types ==
So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: modules can answer questions in one or more categories. Currently, there are four module types, and they are explained below.

=== module type ''auth'' ===
''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?"

=== module type ''account'' ===
''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera.

=== module type ''password'' ===
When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with.

=== module type ''session'' ===
''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed before running the actual program or service. ''session'' type modules can load user limits, mount directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt.

== Invoking PAM ==
As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail.

Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example.

Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines:
 auth       required       pam_unix.so
 session    optional       pam_motd.so
This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists.

Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this:
 auth       required       pam_env.so
 auth       required       pam_env.so envfile=/etc/default/locale
 auth       sufficient     pam_unix.so nullok_secure
 auth       requisite      pam_succeed_if.so uid >= 1000 quiet
 auth       sufficient     pam_ldap.so use_first_pass
 auth       required       pam_deny.so
 account    required       pam_access.so
 account    sufficient     pam_unix.so
 account    sufficient     pam_succeed_if.so uid < 1000 quiet
 account    [default=bad success=ok user_unknown=ignore] pam_ldap.so
 account    required       pam_permit.so
 session    required       pam_limits.so
 session    required       pam_unix.so
 session    required       pam_mkhomedir.so skel=/etc/skel/ umask=0022
 session    optional       pam_ldap.so
 session    optional       pam_motd.so
 session    optional       pam_mail.so standard noenv
 session    required       pam_limits.so
 password   sufficient     pam_unix.so md5 obscure min=4 nullok try_first_pass
 password   sufficient     pam_ldap.so
 password   required       pam_deny.so
Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own!




== A line of PAM configuration code ==

== PAM control flags ==
== A line of PAM configuration code - revisited ==

= PAM on Debian=
== PAM modules in Debian 5.0 'Lenny'==
== PAM configuration files ==

= Configuration example=
== Configuring PAM for LDAP ==