mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-11-29 09:24:22 +01:00
235 lines
6.7 KiB
Plaintext
235 lines
6.7 KiB
Plaintext
Yubico PAM module
|
||
-----------------
|
||
|
||
The Yubico PAM module provides an easy way to integrate the Yubikey
|
||
into your existing user authentication infrastructure. PAM is used by
|
||
GNU/Linux, Solaris and Mac OS X for user authentication, and by other
|
||
specialized applications such as NCSA !MyProxy.
|
||
|
||
|
||
Status and Roadmap
|
||
------------------
|
||
|
||
The module is working for multi-user systems. It does not support
|
||
disconnected mode, for that there is another Yubico PAM module that
|
||
stores the AES key on disk.
|
||
|
||
The development community is co-ordinated via Google Code :
|
||
|
||
http://code.google.com/p/yubico-pam/
|
||
|
||
The license for pam_yubico is the 2-clause BSD license, which is
|
||
compatible with the Linux-PAM BSD/GPL license. See the file COPYING
|
||
for more information.
|
||
|
||
|
||
Building from Git
|
||
-----------------
|
||
|
||
Skip to the next section if you are using an official packaged
|
||
version.
|
||
|
||
You may check out the sources using Git with the following command:
|
||
|
||
------
|
||
$ git clone git://github.com/Yubico/yubico-pam.git yubico-pam
|
||
------
|
||
|
||
This will create a directory 'yubico-pam'.
|
||
|
||
Autoconf, automake and libtool must be installed to create a compilable
|
||
source tree.
|
||
|
||
Generate the build system using:
|
||
|
||
------
|
||
$ cd yubico-pam
|
||
$ autoreconf --install
|
||
------
|
||
|
||
|
||
Building
|
||
--------
|
||
|
||
You will need to have libykclient (ykclient.h, libykclient.so) and
|
||
libpam-dev (security/pam_appl.h, libpam.so) installed. Get the
|
||
ykclient library from:
|
||
|
||
http://code.google.com/p/yubico-c-client/
|
||
|
||
It in turn requires Curl, which you need to have installed.
|
||
|
||
The build system uses Autoconf, to set up the build system run:
|
||
|
||
------
|
||
./configure
|
||
------
|
||
|
||
Use --without-ldap to disable ldap support.
|
||
|
||
Then build the code, run the self-test and install the binaries:
|
||
|
||
------
|
||
make check install
|
||
------
|
||
|
||
|
||
Configuration
|
||
-------------
|
||
|
||
Install it in your PAM setup by adding a line to an appropriate file
|
||
in /etc/pam.d/:
|
||
|
||
------
|
||
auth sufficient pam_yubico.so id=16 debug
|
||
------
|
||
|
||
and move pam_yubico.so into /lib/security/ :
|
||
|
||
------
|
||
mv /usr/local/lib/security/pam_yubico.so /lib/security/
|
||
------
|
||
|
||
For more information, see the project Wiki page.
|
||
|
||
Supported PAM module parameters are:
|
||
|
||
------
|
||
"authfile": to indicate the location of the file that holds the
|
||
mappings of yubikey token IDs to user names.
|
||
|
||
"id": to indicate your client identity.
|
||
|
||
"key": to indicate your client key in base64 format.
|
||
|
||
"debug": to enable debug output to stdout.
|
||
|
||
"alwaysok": to enable all authentication attempts to succeed
|
||
(aka presentation mode).
|
||
|
||
"try_first_pass":
|
||
Before prompting the user for their password, the module
|
||
first tries the previous stacked module´s password in case
|
||
that satisfies this module as well.
|
||
|
||
"use_first_pass":
|
||
The argument use_first_pass forces the module to use a previous
|
||
stacked modules password and will never prompt the user - if no
|
||
password is available or the password is not appropriate, the user
|
||
will be denied access.
|
||
|
||
"url": specify the URL template to use, this is set by calling
|
||
yubikey_client_set_url_template, which defaults to:
|
||
http://api.yubico.com/wsapi/verify?id=%d&otp=%s
|
||
|
||
"verbose_otp":
|
||
This argument is used to show the OTP when it is entered,
|
||
i.e. to enable terminal echo of entered characters.
|
||
You are advised to not use this, if you are using two factor
|
||
authentication because that will display your password on the
|
||
screen.
|
||
|
||
This requires the service using the PAM module to
|
||
display custom fields. For example, OpenSSH requires
|
||
you to configure "ChallengeResponseAuthentication no".
|
||
|
||
"ldap_uri": specify the LDAP server URI (e.g. ldap://localhost).
|
||
|
||
|
||
"ldapserver": specify the LDAP server host (default LDAP port is used).
|
||
_Deprecated. Use "ldap_uri" instead._
|
||
|
||
"ldapdn": specify the dn where the users are stored
|
||
(eg: ou=users,dc=domain,dc=com).
|
||
|
||
"user_attr": specify the LDAP attribute used to store user names (eg:cn).
|
||
|
||
"yubi_attr": specify the LDAP attribute used to store the yubikey id.
|
||
|
||
"capath": Path to a directory with SSL CA certs you trust.
|
||
------
|
||
|
||
If you are using "debug" you may find it useful to create a
|
||
world-writable log file:
|
||
|
||
------
|
||
touch /var/run/pam-debug.log
|
||
chmod go+w /var/run/pam-debug.log
|
||
------
|
||
|
||
|
||
Authorization Mapping Files
|
||
---------------------------
|
||
A mapping must be made between the yubikey token ID and the user ID it is
|
||
attached to. There are two ways to do this, either centrally in one file, or
|
||
individually, where users can create the mapping in their home directories.
|
||
If the central authorization mapping file is being used, user home directory
|
||
mappings will not be used and the opposite applies if user home directory
|
||
mappings are being used, the central authorization mappings file will not
|
||
be used.
|
||
|
||
Central authorization mapping
|
||
-----------------------------
|
||
|
||
Create a /etc/yubikey_mappings, the file must contain a user name and the
|
||
yubikey token ID separated by colons (same format as the passwd file) for
|
||
each user you want to allow onto the system using a yubikey.
|
||
|
||
The mappings should look like this, one per line:
|
||
|
||
------
|
||
<user name>:<yubikey token ID>:<yubikey token ID>:….
|
||
<user name>:<yubikey token ID>:<yubikey token ID>:….
|
||
------
|
||
|
||
Now add authfile=/etc/yubikey_mappings to your PAM configuration line, so it
|
||
looks like:
|
||
|
||
------
|
||
auth sufficient pam_yubico.so id=16 authfile=/etc/yubikey_mappings
|
||
------
|
||
|
||
|
||
Individual authorization mapping by user
|
||
----------------------------------------
|
||
Each user creates a ~/.yubico/authorized_yubikeys file inside of their home
|
||
directory and places the mapping in that file, the file must have only one
|
||
line:
|
||
|
||
------
|
||
<user name>:<yubikey token ID>:<yubikey token ID>
|
||
------
|
||
|
||
This is much the same concept as the SSH authorized_keys file.
|
||
|
||
|
||
Obtaining the yubikey token ID
|
||
------------------------------
|
||
You can obtain the yubikey token ID in two places, one is by capturing the
|
||
the first twelve digits of any OTP generated with your yubikey, the other
|
||
is by using the modhex calculator located here:
|
||
|
||
http://radius.yubico.com/demo/Modhex_Calculator.php
|
||
|
||
Enter your yubikey OTP and convert it, your yubikey token ID is 12 digits and listed as:
|
||
|
||
Modhex encoded: XXXXXXX
|
||
|
||
|
||
Examples
|
||
--------
|
||
|
||
If you want to use the Yubikey to authenticate you on linux console
|
||
logins, add the following to the top of /etc/pam.d/login:
|
||
|
||
------
|
||
auth sufficient pam_yubico.so id=16 debug
|
||
------
|
||
|
||
|
||
Feedback
|
||
--------
|
||
|
||
If you want to discuss anything related to the Yubico PAM module,
|
||
please contact Simon Josefsson <simon@yubico.com>.
|