![[image of the Head of a GNU]](/graphics/gnu-head-sm.jpg)
|
|
PAM-Modules |
A Collection of Modules for PAM |
Sergey Poznyakoff |
PAM-modules Manual (split by chapter): 
The pam_ldaphome facilitates maintenance of a centralized
LDAP user database. It can be installed as a part of
authentication or session management stack. When invoked, it creates
the user home directory, if it does not already exist, and ensures his
.ssh/authorized_keys is in sync with the database.
Apart from common options, this module understands only one implementation-specific option:
Read configuration from file. Default is pam_ldaphome.conf in sysconfdir.
Actual module configuration is read from the configuration file.
pam_ldaphomePam_ldaphome reads its configuration from two files: the
configuration file supplied with the config command line
option and the system-wide LDAP configuration file
/etc/ldap.conf.
The syntax of the former is described in SQL configuration file. Allowed keywords are discussed below.
The syntax of the /etc/ldap.conf configuration file is
described in LDAP configuration file in ldap.conf(5) manpage. Its parsing can be suppressed using the
ldap-config statement (see below).
From /etc/ldap.conf, the following statements are used: ‘base’, ‘binddn’, ‘bindpw’, ‘tls_cacert’, ‘uri’. The ‘ssl’ statement is understood if its value is ‘start_tls’ or ‘off’. Other values are silently ignored.
In general, all statements defined below can appear in both files.
However, since /etc/ldap.conf is read by other system utilities
as well, we do not recommend using pam_ldaphome-specific
keywords in it.
The values read from pam_ldaphome configuration file
override those obtained from the standard LDAP configuration file.
Use searchbase as the starting point for the search instead of the default, e.g.:
base dc=gnu,dc=org,dc=ua
Use the Distinguished Name dn to bind to the LDAP directory. Example:
binddn cn=Manager,dc=gnu,dc=org,dc=ua
If binddn statement is used, this statement supplies the
password for simple authentication.
Read password for simple authentication from file.
Sets the LDAP filter expression to return a user profile. The expr should conform to the string representation for search filters as defined in RFC 4515.
Read LDAP configuration from file (default – /etc/ldap.conf). Special value ‘none’ disables this feature.
Sets the LDAP version to use. Valid values for v are ‘2’ and ‘3’ (the default).
Defines the name of the attribute which holds the user public key.
Controls whether TLS is desired or required. If val is ‘no’ (the default), TLS will not be used. If it is ‘yes’, the module will issue the ‘StartTLS’ command, but will continue anyway if it fails. Finally, if val is ‘only’, TLS is mandatory, and the module will not establish LDAP connection unless ‘StartTLS’ succeeds.
Full pathname to the CA certificate file. Used if TLS is enabled. The second form (‘tls_cacert’) is for use in /etc/ldap.conf file.
Sets the URI of the LDAP server to consult for the user profile. Example:
uri ldap://127.0.0.1/
If present, this option controls where pam_ldaphome should
try to create home directories. Its value is a list of directories
separated by colons. The user’s home directory will be created only
if the directory part of its name is listed in path.
Sets the size of the buffer used to copy files from the skeleton directory to the newly created home. The default size is 16384 bytes.
Sets the mode (octal) for the created user directories.
Supplies the name of a skeleton directory. The contents of this directory is copied to the newly created user home directory. The file modes and permissions are preserved.
Sets the pathname (relative to the home directory) for the authorized keys file. The default is ‘.ssh/authorized_keys’. For normal operation, this value must be the same as the value of ‘AuthorizedKeysFile’ variable in sshd_config. Unless you change the latter, there’s no need to edit it.
When set to ‘no’, disables importing public keys from LDAP. You
may wish to use this option if you are using openssh 6.1 or
later with ldappubkey as ‘AuthorizedKeysCommand’.
Sets the mode (octal) for the created authorized keys file.
User key files can contain both keys managed by pam_ldaphome
and added by the user. These two groups of keys must be separated by
a special comment line, which informs the module that all keys
below it must be retained.
This feature is enabled by the user-keys-boundary setting.
The delimiting comment is formed as ‘#string’. E.g. if the
configuration file contains:
user-keys-boundary :user-defined
then the line ‘#:user-defined’ can be used to delimit ldap-synchronized and user-specific keys.
Only handle members of the listed groups.
Sets the minimal GID. For users with GIDs less than n,
pam_ldaphome returns PAM_SUCCESS immediately.
Sets the minimal UID. For users with UIDs less than n,
pam_ldaphome returns PAM_SUCCESS immediately. This allows
you to have a set of basic users whose credentials are kept in the
system database and who will not be disturbed by
pam_ldaphome. See also ‘min-gid’ and
‘allow-groups’.
The following statements instruct pam_ldaphome to invoke an
external command after initializing the user home directory. This can
be used to customize the files copied from the skeleton directory
according to the user.
Sets maximum time the initrc-command is allowed to run. If
it runs longer than seconds, it will be terminated with a
‘SIGKILL’, and the module will return PAM_SYSTEM_ERR.
Run command after populating the user home directory with
files from the skeleton directory.
The user login name is passed to the command as its argument. Before invoking, the current working directory is changed to the user home, standard input is closed, and standard output is redirected to standard errror.
The command is run under the current user privileges, unless the variable initrc-root is set to true.
The command should exit with code 0 on success. If it exits with a
non-zero code, pam_ldaphome will report
‘PAM_SYSTEM_ERR’.
When set to true, initrc-command will be run with
root privileges. In this case, the environment variable
PAM_LDAPHOME_USER will be initialized to the name of the
user who is trying to log in.
This statement redirects the standard output and error from the
initrc-command to file.
Modifies the environment of initrc-command.
This statement takes one or more arguments. Each argument can be one of:
Clear the environment. This is understood only when used as the first argument.
Unset the environment variable name.
Unset the environment variable name only if its value is val.
Retain the environment variable name.
Define environment variable name to have given value.
Retain variable name and append value to its existing
value. If no such variable is present in the environment, it is
created and value is assigned to it. However, if value
begins with a punctuation character, this character is removed from it
before the assignment. This is convenient for using this construct with
environment variables like PATH, e.g.:
PATH+=:/sbin
In this example, if PATH exists, ‘:/sbin’ will be appended
to it. Otherwise, it will be created and ‘/sbin’ will be
assigned to it.
Retain variable name and prepend value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value ends with a punctuation character, this character is removed from it before assignment.
The value part can be enclosed in single or double quotes, in which case the usual shell dequoting rules apply.
This example assumes you are using GNU/Linux. The aim of this
configuration is to allow remote access via sshd to users present only
in the LDAP database, using ssh shared-key authentication. The exact
way of achieving this depends on the version of opennsh
daemon in use. The openssh version 6.2p1 introduced a
possibility to obtain public keys by invoking an external command,
so there are two main usage cases, as described in the subsections
that follow.
The user public keys are kept in ‘grayPublicKey’ attribute of his
LDAP entry. When a user logs in for the first time, his home directory
does not exist yet and consequently sshd is not able to verify his
key. Therefore it falls back to the interactive authentication (it is
supposed, of course, that ‘UsePAM’ is set to ‘yes’ in the
sshd configuration file). The authentication stage is supposed to
create user home directory, populate his .ssh/authorized_keys
with his public keys and present user with a descriptive text
prompting him to cancel his current authentication attempt and retry
it again. The corresponding pam.conf section looks as follows:
sshd auth [success=ok try_again=1 default=die] \
pam_ldaphome.so
sshd auth [success=done ignore=ignore default=die] \
pam_unix.so
sshd auth [default=die] pam_echo.so file=/etc/ldaphome.txt
The first line does most of the job. If pam_ldaphome.so
succeeds in creating the user directory it will return
‘try_again’. This will cause skipping the next stack entry, so
control will go to pam_echo.so, which will print a
descriptive text from /etc/ldaphome.txt and exit indicating
authentication failure.
The pam_ldaphome.so module returns ‘success’ if the
user who is trying to log in should not be handled by it (e.g. because
his UID is less than the ‘min-uid’ setting, etc.). In this case,
authentication will be handled by pam_unix.so. This allows
normal system accounts to function as usual. This is very important,
because it will allow to access the machine even when the LDAP
database is not available for some reason.
The pam_ldaphome.so configuration handles users with uids
and gids greater than or equal to 1000 and pertaining to the group
‘remote’. User home dirs are populated from the /etc/skel
directory.
min-uid 1000 min-gid 1000 allow-groups remote skel /etc/skel base dc=gnu,dc=org,dc=ua filter (&(objectClass=posixAccount)(uid=$user)) pubkey-attr grayPublicKey
The LDAP schema should include an attribute to keep the user public keys. The author uses the following schema:
# depends upon:
# nis.schema
# Attribute Definitions
attributetype ( 1.3.6.1.4.1.9163.2.1.0 NAME 'grayPublicKey'
DESC 'SSH public key'
EQUALITY caseExactIA5Match
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
# Object Class Definitions
objectclass ( 1.3.6.1.4.1.9163.2.2.0 NAME 'grayAccount'
DESC 'Abstraction of an employee account'
SUP posixAccount AUXILIARY
MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
MAY ( userPassword $ loginShell $ gecos $ grayPublicKey ) )
The ‘passwd’ and ‘group’ entries in /etc/nsswitch.conf file should be as follows:
passwd: files ldap group: files ldap
Versions of openssh starting from 6.2p1 are able to
read public keys from the standard output of an external program.
This can be used to improve the configuration described in the
previous subsection so that the user is not required to cancel
his session upon the very first connection. To that effect,
pam-modules includes the utility ldappubkey,
distributed in the examples subdirectory (see ldappubkey).
Copy that utility to a convenient location (/usr/libexec would
be a wise choice), and add the following two lines to your
/etc/ssh/sshd_config file:
AuthorizedKeysCommand /usr/libexec/ldappubkeys AuthorizedKeysCommandUser nobody
Two points should be observed. First, the argument to
AuthorizedKeysCommand (and all its pathname components) must be
owned by root and be writable only for the owner. Second, the use
of AuthorizedKeysCommandUser statement is mandatory. Of
course, you can chose any suitable user (not necessarily ‘nobody’).
After restarting sshd, it will invoke ldappubkeys
on each log in attempt with the login name of the user as its
argument. The utility will look up that user in the LDAP database,
and if found, will print his piblic keys on its standard output. The
sshd will then read the keys and try to authorize user
against each of them. If none of the keys matches the private key
supplied by the user, sshd will attempt public keys read
from the user’s ~/.ssh/authorized_keys file (or another file,
if overridden by the AuthorizedKeysFile statement in
/etc/ssh/sshd_config).
Most of the configuration described in the previous subsection remains
in effect. However, the authentication stack won’t be invoked if
ldappubkeys functions successfully. The
pam_ldaphome module must be invoked as a part of
‘session’ stack instead. The following example assumes
it is invoked at the top of the stack:
sshd session [success=ignore try_again=ignore default=die] \ pam_ldaphome.so
The ldappubkey utility is a simple Perl program which takes
user login name as its argument and produces on the standard output
public ssh keys for that user, each on a separate line. The program
is designed for use with openssh version 6.2p1 or higher.
It is distributed in the examples subdirectory and is not
installed by default. The only prerequisite for its use is the
Net::LDAP module. See Use of pam_ldaphome with
openssh version 6.2p1, for instructions of its use.
The utility looks up for its configuration in the following files: /etc/ldap.conf, /etc/ldap/ldap.conf and /etc/openldap/ldap.conf. These files are tried in this order and the first one of them that exists is read.
The following configuration statements are used (all keywords are case-insensitive):
Specifies the URI of the LDAP server (or servers) to connect to. The default is ‘ldap://127.0.0.1’.
Specifies the default base DN to use when performing LDAP operations. The base must be specified as a Distinguished Name in LDAP format.
Specifies the default DN to bind as.
Specifies the password to use with binddn.
Defines the name of the attribute to use instead of uid. The
LDAP record is searched using the following filter:
(&(objectClass=posixAccount)(attr=login))
List of attributes that hold the public keys. Default is ‘grayPublicKey’ (see ldap-schema).
LDAP filter used to retrieve the objects that contain public keys. The filter string can contain the following variables:
The value of the ‘uid’ setting (see above).
First command line argument.
Full hostname of the machine.
The default value is:
(&(objectClass=posixAccount)($uid=$arg))
The examples subdirectory of the pam-modules
distribution contains a program usergitconfig which
is designed to customize user’s .gitconfig file using
attributes from his LDAP entry.
The command reads the .gitconfig file and replaces any occurrence of ‘${attr}’ with the value of the LDAP attribute attr. Not defined attributes are replaced with empty strings.
To use this utility with pam_ldaphome, first make sure
you have Perl Net::LDAP module installed. Copy
usergitconfig to some location of preference (say,
/usr/libexec), and add the following to pam_ldaphome
configuration file:
skel /etc/skel initrc-command /usr/libexec/usergitconfig
The /etc/skel directory should contain the file .gitconfig. Suppose its contents is as follows:
[user]
name = ${cn}
email = ${mail}
Then, after successful completion of pam_ldaphome, the
user’s .gitconfig file will contain his real name and email
set properly from the database.
For the gituserconfig LDAP configuration options, see
ldap.conf statements.
PAM-modules Manual (split by chapter):
This document was generated on August 11, 2021 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.