Forge Home


A Puppet Module to install the yubikey PAM module and manage users/keys on a system.


7,618 latest version

4.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.0.7 (latest)
  • 1.0.6
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
  • 0.9.7
  • 0.9.6
  • 0.9.5
  • 0.9.4
  • 0.9.3
  • 0.9.2
  • 0.9.1
released Apr 1st 2016
This version is compatible with:
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'ncorrare-yubikey', '1.0.7'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add ncorrare-yubikey
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install ncorrare-yubikey --version 1.0.7

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



ncorrare/yubikey — version 1.0.7 Apr 1st 2016


by Nicolas Corrarello

Coverage Status Build Status

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with yubikey
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module


This module installs, configures and assigns Yubikeys in a system.

Module Description

The module installs the yubico PAM libraries that enable using yubikeys as a supported authentication method. Using the default variables it will enable system wide yubikey authentication for all users defined using the yubikey::key type. It assumes a default PAM configuration, but for complex environments the setup can be adjusted.


What yubikey affects

  • The PAM yubico libraries will be installed from either the distribution repo or Yubico's depending on the Linux Distribution.
  • As default, it will be configured as sufficient authentication before the PAM Unix module. Please review your PAM configuration.
  • As with any PAM change, it is strongly suggested to test it with a shell open, since it may lock you out of the system.

Beginning with yubikey

To configure a system, begin with adding the class.

class profile::yubikey {
  include ::yubikey


The module will install the require bits, and update the PAM configuration to have yubikey as a "sufficient" authentication method, before (i.e. before user/password). By default, it will also enable debugging. Consider editing the arguments for production systems:

class { '::yubikey::config' :
  arguments => ['id=16']

For other arguments, or using with the Yubico Radius, please check the documentation on which parameters to use on .

To configure a user, define a new key:

yubikey::key { 'username' :
  token   => 'array of tokens' #Since version 1.0.0
  homedir => 'homedir'
  group   => 'group'

Where token is the Yubikey token ID. So far it only accepts a string and not an array. This will create a new file in the user's home directory (that you should provide) in a given path (~/.yubico/authorized_yubikeys) with the authorization mapping.


The ::yubikey class accepts all parameters for ::yubikey::install and ::yubikey::config.

The ::yubikey::install accepts the following variables:

  • $pkgname: String. Defaults to sane values in both RedHat and Debian derivatives.
  • $managedeps: Bool. If set to true it will configure EPEL, or APT, if required.

The ::yubikey::config class accepts the following variables:

  • $arguments: Array. Defaults to ['debug','id=16']. Arguments are documented in .
  • $service: Array. Defaults to system-auth & password-auth in RedHat systems and common-auth in Ubuntu systems. Depending on your implementation, you might want to have yubikey authentication on a particular service (like sshd) so check your distribution documentation on how PAM is configured for your system.
  • $control: String. Defaults to 'sufficient'. Again, depending on your setup, you may want to add other authentication controls. Refer to the PAM documentation. Module will accept requisite, required, sufficient or optional.
  • $beforemod: String. Defaults to ''. Works with most default PAM setups.

The ::yubikey::key type accepts the following parameters:

  • $token: Array of 12 char strings (Yes, it will validate that!). Be careful!, this used to be a string! of your Yubikey ID.
  • $home: String. User home directory.
  • $gid: String. User's primary group.


So far this has only been tested in Ubuntu and Centos. Should work in RHEL, Fedora, and Debian. Please test it and let me know. Also do know that this code is not endorsed by Yubico in any way, so use it at your own risk.


Regular rules apply, clone, PR, and I'll have a look. Generally on irc (#puppet and others on Freenode), my nick is sgtpepper so feel free to contact me if you have any doubts.

Tested in Puppetconf