diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2014-05-21 12:22:05 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2014-05-21 12:22:05 +0300 |
commit | 4edfb36f053eac1eb5e0250c73d9e7eef29016dd (patch) | |
tree | 104504241346ec744baac979ae987c429ec7e07f | |
parent | f664b904fde206c6c7e0dc45b690ed7d28bea571 (diff) | |
download | pam-modules-4edfb36f053eac1eb5e0250c73d9e7eef29016dd.tar.gz pam-modules-4edfb36f053eac1eb5e0250c73d9e7eef29016dd.tar.bz2 |
Document the use of ldappubkey
-rw-r--r-- | doc/pam-modules.texi | 160 | ||||
-rwxr-xr-x | examples/ldappubkey | 2 |
2 files changed, 145 insertions, 17 deletions
diff --git a/doc/pam-modules.texi b/doc/pam-modules.texi index bf101f7..8d9a1c8 100644 --- a/doc/pam-modules.texi +++ b/doc/pam-modules.texi @@ -37,3 +37,5 @@ * pam_groupmember (pam_modules)groupmember Test group membership. -* pamck: (pam-modules)pamck. Verify PAM Access. +* pamck: (pam-modules)pamck. Verify PAM Access. +* usergitconfig: (pam-modules)usergitconfig. Initialize user @file{.gitconfig} file. +* ldappubkey: (pam-modules)ldappubkey. Get user's public ssh keys from the LDAP database. @end direntry @@ -1145,6 +1147,6 @@ The @var{query} is subject to item expansion (@pxref{item expansion}). The @command{pam_ldaphome} facilitates maintenance of a centralized -LDAP user database. It should be installed as a part of -authentication stack. When invoked, it creates the user home -directory, if it does not already exist, and updates his -@file{.ssh/authorized_keys} file with the keys from the database. +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 +@file{.ssh/authorized_keys} is in sync with the database. @@ -1359,2 +1361,3 @@ which case the usual shell dequoting rules apply. * ldaphome example:: +* ldappubkey:: * usergitconfig:: @@ -1366,6 +1369,20 @@ 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 user -public keys are kept in @samp{grayPublicKey} attribute of his LDAP -entry. When a user logs in for the first time, his home directory -does not exist yet and consequently ssh is not able to verify his +in the LDAP database, using ssh shared-key authentication. The exact +way of achieving this depends on the version of @command{opennsh} +daemon in use. The @command{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. + +@menu +* 5.x:: Openssh versions prior to 6.2p1. +* 6.2p1:: Openssh versions 6.2p1 and newer. +@end menu + +@node 5.x +@subsection Openssh versions prior to 6.2p1 + +The user public keys are kept in @samp{grayPublicKey} attribute of his +LDAP entry. When a user logs in for the first time, his home directory +does not exist yet and consequently @command{sshd} is not able to verify his key. Therefore it falls back to the interactive authentication (it is @@ -1378,3 +1395,3 @@ it again. The corresponding @file{pam.conf} section looks as follows: -@subheading pam.conf +@subsubheading pam.conf @example @@ -1400,3 +1417,3 @@ database is not available for some reason. -@subheading pam_ldaphome.conf +@subsubheading pam_ldaphome.conf The @command{pam_ldaphome.so} configuration handles users with uids @@ -1416,3 +1433,4 @@ pubkey-attr grayPublicKey -@subsection Schema +@subsubheading Schema +@anchor{ldap-schema} The LDAP schema should include an attribute to keep the user public @@ -1437,3 +1455,3 @@ objectclass ( 1.3.6.1.4.1.9163.2.2.0 NAME 'grayAccount' -@subheading /etc/nsswitch.conf +@subsubheading /etc/nsswitch.conf The @samp{passwd} and @samp{group} entries in @@ -1446,2 +1464,107 @@ group: files ldap +@node 6.2p1 +@subsection Openssh versions 6.2p1 and newer + +@kindex AuthorizedKeysCommand +@kindex AuthorizedKeysCommandUser +Versions of @command{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, +@command{pam-modules} includes the utility @command{ldappubkey}, +distributed in the @file{examples} subdirectory (@pxref{ldappubkey}). +Copy that utility to a convenient location (@file{/usr/libexec} would +be a wise choice), and add the following two lines to your +@file{/etc/ssh/sshd_config} file: + +@example +AuthorizedKeysCommand /usr/libexec/ldappubkeys +AuthorizedKeysCommandUser nobody +@end example + +@noindent +Two points should be observed. First, the argument to +@code{AuthorizedKeysCommand} (and all its pathname components) must be +owned by root and be writable only for the owner. Second, the use +of @code{AuthorizedKeysCommandUser} statement is mandatory. Of +course, you can chose any suitable user (not necessarily @samp{nobody}). + +After restarting @command{sshd}, it will invoke @command{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 +@command{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, @command{sshd} will attempt public keys read +from the user's @file{~/.ssh/authorized_keys} file (or another file, +if overridden by the @code{AuthorizedKeysFile} statement in +@file{/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 +@command{ldappubkeys} functions successfully. The +@command{pam_ldaphome} module must be invoked as a part of +@samp{session} stack instead. The following example assumes +it is invoked at the top of the stack: + +@example +sshd session [success=ignore try_again=ignore default=die] \ + /usr/lib/security/pam_ldaphome.so +@end example + +@node ldappubkey +@section ldappubkey +@cindex ldappubkey + +The @command{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 @command{openssh} version 6.2p1 or higher. +It is distributed in the @file{examples} subdirectory and is not +installed by default. The only prerequisite for its use is the +@command{Net::LDAP} module. @xref{6.2p1,, 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: +@file{/etc/ldap.conf}, @file{/etc/ldap/ldap.conf} and +@file{/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): + +@anchor{ldap.conf statements} +@deffn {ldap.conf} uri ldap[si]://[@var{name}[:@var{port}]] ... +Specifies the URI of the LDAP server (or servers) to connect to. The default +is @samp{ldap://127.0.0.1}. +@end deffn + +@deffn {ldap.conf} base @var{dn} +Specifies the default base DN to use when performing LDAP operations. +The base must be specified as a Distinguished Name in LDAP format. +@end deffn + +@deffn {ldap.conf} binddn @var{dn} +Specifies the default DN to bind as. +@end deffn + +@deffn {ldap.conf} bindpw @var{password} +Specifies the password to use with @code{binddn}. +@end deffn + +@deffn {ldap.conf} uid @var{attr} +Defines the name of the attribute to use instead of @code{uid}. The +LDAP record is searched using the following filter: + +@example +(&(objectClass=posixAccount)(@var{attr}=@var{login})) +@end example +@end deffn + +@deffn {ldap.conf} publickeyattribute @var{attr} +Name of the attribute which holds the public key. Default is +@samp{grayPublicKey} (@pxref{ldap-schema}). +@end deffn + @node usergitconfig @@ -1460,5 +1583,7 @@ empty strings. -To use this utility with @command{pam_ldaphome}, copy it to -some location of preference (say, @file{/usr/libexec}), and -add the following to @command{pam_ldaphome} configuration file: +To use this utility with @command{pam_ldaphome}, first make sure +you have Perl @command{Net::LDAP} module installed. Copy +@command{usergitconfig} to some location of preference (say, +@file{/usr/libexec}), and add the following to @command{pam_ldaphome} +configuration file: @@ -1483,2 +1608,5 @@ set properly from the database. +For the @command{gituserconfig} LDAP configuration options, see +@ref{ldap.conf statements}. + @node umotd diff --git a/examples/ldappubkey b/examples/ldappubkey index 2451505..50fd97e 100755 --- a/examples/ldappubkey +++ b/examples/ldappubkey @@ -32,3 +32,3 @@ Produces on the standard output public ssh keys for the user I<LOGIN>, each on a separate line. The program is designed for use with B<sshd>(8) version -6.x or higher. Public keys are obtained from a LDAP database. The +6.2p1 or higher. Public keys are obtained from a LDAP database. The configuration is looked up in the following files: B</etc/ldap.conf>, |