README.duo

This README file explains how to use base::duo.

VERSION 4->5 UPGRADE NOTE: If your code involves base::duo, that's not going to 
work anymore.  Have a look at base::duo::config instead, or README.ssh.

The term Duo uses is "integration", to refer to a set of credentials that a 
client (like your system) will use to authenticate itself to Duo.  base::duo 
manages the process of fetching and customizing 'duo-unix' integrations, which 
is the type of integration that can be used for things like login, sudo, and 
web-based two-step (such as something that your web application might trigger).

Duo integrations are keyed on the system name, so if you have multiple Duo uses 
on a single system (e.g. SSH and sudo), all uses will share the same Duo 
integration, but _may_ use different Duo configuration files: If the Duo uses 
on a single system have different needs (such as one failing safe and one 
failing secure), that will require separate Duo configuration files.

Duo integration keys do not change or expire, unless a `wallet destroy` or a 
Duo administrator manually deletes a Duo integration.

If you do ever need to destroy a Duo integration, here's the command to use:

        wallet destroy pam-duo hostname.stanford.edu

To generate a Duo configuration file, instantiate an object of 
base::duo::config, where the name is the path to the Duo configuration file.  
For example:

base::duo::config { '/etc/secure/duo_webapp.conf':
  ensure     => present,
  failsecure => true,
}

To see the options available, have a look at the header text in 
manifests/duo/config.pp.  There are other classes in the base::duo namespace, 
but they're all invoked as needed by base::duo::config.

To be honest, the only time you'll need to invoke base::duo::config directly is 
when you have a custom thing that wants to leverage Duo.  If you're interested 
in using Duo to authenticate SSH or sudo, have a look in README.ssh or 
README.sudo instead.