mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-11-29 09:24:22 +01:00
351 lines
11 KiB
Plaintext
351 lines
11 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. The primary mode of
|
||
operation is by doing online validation using a YubiKey validation
|
||
service (such as the YubiCloud, or a private one configured using
|
||
the 'url' parameter).
|
||
|
||
In version 2.6, offline validation was also made possible through
|
||
the use of HMAC-SHA1 Challenge-Response found in YubiKey 2.2 and
|
||
later. This has introduced a dependency of libykpers-1 from the
|
||
ykpersonalize package. Pass `--without-cr' to `configure' to avoid
|
||
this dependency.
|
||
|
||
The development community is co-ordinated via Google Code and GitHub :
|
||
|
||
http://code.google.com/p/yubico-pam/
|
||
https://github.com/Yubico/yubico-pam/
|
||
|
||
The split is roughly Google Code hosting the bug tracker and downloads
|
||
with GitHub hosting the Wiki and code repository.
|
||
|
||
The project is licensed under a BSD license. See the file COPYING for
|
||
exact wording. For any copyright year range specified as YYYY-ZZZZ in
|
||
this package note that the range specifies every single year in that
|
||
closed interval.
|
||
|
||
|
||
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, and
|
||
libyubikey. Get libyubikey from
|
||
|
||
http://code.google.com/p/yubico-c/
|
||
|
||
The new Challenge-Response offline authentication requires libykpers-1
|
||
from the yubikey-personalization project :
|
||
|
||
http://code.google.com/p/yubikey-personalization/
|
||
|
||
|
||
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
|
||
------
|
||
|
||
|
||
Ubuntu PPA
|
||
----------
|
||
|
||
There is an Ubuntu PPA (Personal Package Archive) for yubico-pam that
|
||
can be installed using the following commands on reasonably modern
|
||
Ubuntu platforms :
|
||
|
||
$ sudo add-apt-repository ppa:yubico/stable
|
||
$ sudo apt-get update
|
||
$ sudo apt-get install libpam-yubico
|
||
|
||
See the file /usr/share/doc/libpam-yubico/README.Debian after installing.
|
||
|
||
|
||
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/ (or wherever PAM modules
|
||
live in your system) :
|
||
|
||
------
|
||
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.
|
||
The client key is also known as API key, and provides
|
||
integrity in the communication between the client (you)
|
||
and the validation server.
|
||
If you want to get one for use with the default YubiCloud
|
||
service, visit this URL :
|
||
|
||
https://upgrade.yubico.com/getapikey/
|
||
|
||
"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
|
||
|
||
or
|
||
|
||
http://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s
|
||
|
||
depending on your version of yubico-c-client.
|
||
|
||
"capath": specify the path where X509 certificates are stored. This is
|
||
required if 'https' or 'ldaps' are used in 'url' and 'ldap_uri'
|
||
respectively.
|
||
|
||
"verbose_otp":
|
||
This argument is used to show the OTP (One Time Password) 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.
|
||
|
||
"yubi_attr_prefix":
|
||
specify the prefix of the LDAP attribute's value, in case
|
||
of a generic attribute, used to store several types of ids.
|
||
|
||
"token_id_length":
|
||
Length of ID prefixing the OTP (this is 12 if using the
|
||
YubiCloud).
|
||
"mode":
|
||
Mode of operation. Use "client" for online validation with
|
||
a YubiKey validation service such as the YubiCloud, or use
|
||
"challenge-response" for offline validation using YubiKeys
|
||
with HMAC-SHA-1 Challenge-Response configurations. See the
|
||
man-page ykpamcfg(1) for further details on how to configure
|
||
offline Challenge-Response validation.
|
||
|
||
------
|
||
|
||
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:
|
||
|
||
------
|
||
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:….
|
||
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:….
|
||
------
|
||
|
||
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 ID1>:<Yubikey token ID2>
|
||
------
|
||
|
||
This is much the same concept as the SSH authorized_keys file.
|
||
|
||
|
||
Obtaining the Yubikey token ID (a.k.a. public ID)
|
||
-------------------------------------------------
|
||
You can obtain the Yubikey token ID in two places. One is by removing the
|
||
last 32 characters of any OTP (One Time Password) 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 characters and listed as:
|
||
|
||
Modhex encoded: XXXXXXX
|
||
|
||
|
||
Not sure what that last bit meant? Here is how to get a copy of your OTP.
|
||
|
||
Fast way
|
||
========
|
||
* Open a terminal
|
||
* Press yubikey button
|
||
|
||
It will output an OTP into the shell:
|
||
|
||
------
|
||
$ cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj
|
||
bash: cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj: command not found
|
||
------
|
||
|
||
This can be pasted into the Modhex_Calculator page.
|
||
|
||
Harder way
|
||
==========
|
||
This requires you to have the pam module enabled with 'debug' turned on. When
|
||
prompted for the yubikey press the button. The pam module will print out debug
|
||
information including the OTP and ID of your token to the shell - copy the ID
|
||
into your config file and you should be up and going.
|
||
|
||
------
|
||
Yubikey for `youruser':
|
||
[pam_yubico.c:pam_sm_authenticate(867)] conv returned 44 bytes
|
||
[pam_yubico.c:pam_sm_authenticate(885)] Skipping first 0 bytes. Length is 44, token_id set to 12 and token OTP always 32.
|
||
[pam_yubico.c:pam_sm_authenticate(892)] OTP: ccccccclabcabkhbdncicglfltnukadfoifadfhhhhfe ID: cccccclabcab
|
||
------
|
||
|
||
|
||
Yubico PAM module and SELinux.
|
||
------------------------------
|
||
Users with SELinux in enforcing mode (the default on Fedora 17+) may experience
|
||
login problems with services including those validated via
|
||
polkit-agent-helper-1, sshd and login.
|
||
|
||
This is documented in the PAM Yubico issue tracker [1] and Red Hat bugzilla
|
||
including a work around [2] for ssh (Equivalent files could be created for
|
||
other services). Systems in 'permissive' mode will generate AVC warnings but
|
||
authentication will succeed.
|
||
|
||
[1] http://code.google.com/p/yubico-pam/issues/detail?id=43
|
||
[2] https://bugzilla.redhat.com/show_bug.cgi?id=841693#c3
|
||
|
||
To determine if you have SELinux enforcing or not run the 'sestatus' command.
|
||
|
||
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 e-mail the mailing list yubico-devel@googlegroups.com.
|
||
|