Version information
This version is compatible with:
- Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
- Puppet >= 7.0.0 < 9.0.0
- , , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'iu-duo_unix', '4.2.4'
Learn more about managing modules with a PuppetfileDocumentation
duo_unix
The duo_unix module handles the deployment of duo_unix (login_duo
or
pam_duo
) across a range of Linux distributions. The module will handle
repository dependencies, installation of the duo_unix package, configuration
of OpenSSH, and PAM alterations as needed.
For further information about duo_unix, view the official documentation.
Table of Contents
- Description
- Setup - The basics of getting started with duo_unix
- Usage - Configuration options and additional functionality
- Limitations - OS compatibility, etc.
- Contributing
Description
The duo_unix Puppet module installs and manages duo_unix (login_duo or pam_duo).
This module is meant to be a drop-in replacement for the abandoned official puppet module.
Setup
What duo_unix affects
This module will add the official Duo Inc. repository. It will also then install the appropriate package(s) for your system.
It will also optionally alter some files on your system to help ensure that user login attempts will correctly require Duo to succeed.
If usage
is set to login
, it will set the following directives in
/etc/ssh/sshd_config
ForceCommand /usr/sbin/login_duo
PermitTunnel no
AllowTcpForwarding no
If usage
is set to pam
, it will alter your pam config. Those changes are
distribution-specific. To see exactly what is changed, please refer to the
manifests/pam_config.pp
file.
If accept_env_factor
is set to yes
, it will configure your sshd_config
to allow DUO_PASSCODE as an AcceptEnv value to enable out-of-band 2FA
in the shell for use cases such as scp. This feature is only possible if
usage
is set to login
.
Setup Requirements
This module requires some additional modules, but it is highly likely that they are already installed on your puppet server. They are as follows:
puppetlabs/apt
6.0 - 9.0
puppetlabs/augeas_core
1.0.0 - 2.0.0
puppetlabs/stdlib
5.0.0 - 10.0.0
puppetlabs/yumrepo_core
1.0.0 - 2.0.0
Beginning with duo_unix
The very basic steps needed for a user to get the module up and running. This can include setup steps, if necessary, or it can be an example of the most basic use of the module.
Usage
class { 'duo_unix':
usage => 'login',
ikey => 'your integration key',
skey => 'your secret key',
host => 'api-yourhost.duosecurity.com',
motd => 'yes',
accept_env_factor => 'no',
duo_rsyslog => false,
}
Notes
- accept_env_factor is set to 'no' by default, but when set to 'yes', enables DUO_PASSCODE as desribed above for out-of-band 2FA
- duo_rsyslog is set to false by default, but when set to true, enables sending duo auth messages to the OS-default auth log (this is also very helpful for simplifying fail2ban config if also used)
Limitations
In the past the official Duo module supported various RedHat derivatives. This module currently only makes minor attempts to support them.
Contributing
Pull requests are welcome, but all code must meet the following requirements
- Is fully tested
- Note: Unit testing uses the rspec-puppet-augeas Ruby gem, which requires the following local packages (at least in Debian-based environments) to be installed:
ruby-augeas augeas-tools augeas-lenses libaugeas-dev
- Note: Unit testing uses the rspec-puppet-augeas Ruby gem, which requires the following local packages (at least in Debian-based environments) to be installed:
- All tests must pass
- Follows the Puppet language style guide
- All commits must be signed
Reference
Table of Contents
Classes
duo_unix
: This class installs and configures duo for various Linux distrosduo_unix::pam_config
: This class will configure PAM to require Duoduo_unix::pam_ssh_config
: This class sets sshd up to use PAMduo_unix::params
: Default parameter values for the duo_unix moduleduo_unix::repo
: Add an apt/yum repo for Debian/RedHat based systemsduo_unix::ssh_config
: This command sets ssh up to require duo through ForceCommand
Classes
duo_unix
Copyright © 2019 The Trustees of Indiana University SPDX-License-Identifier: BSD-3-Clause
This class is the entry point for the duo_unix class. It will install and configure duo for various Linux distros.
Examples
include duo_unix
Parameters
The following parameters are available in the duo_unix
class:
usage
manage_pam
manage_ssh
manage_repo
ikey
skey
host
package_ensure
config_ensure
fallback_local_ip
failmode
pushinfo
autopush
motd
prompts
accept_env_factor
proxy
groups
show_diff
usage
Data type: Enum['login', 'pam']
Whether it is expected that duo will be enforced through ssh or pam
manage_pam
Data type: Boolean
Whether to alter the pam config to require Duo The default is true
Default value: $duo_unix::params::manage_pam
manage_ssh
Data type: Boolean
Whether to alter the ssh config to require Duo The default is true
Default value: $duo_unix::params::manage_ssh
manage_repo
Data type: Boolean
Whether to manage the duo repo The default is true
Default value: $duo_unix::params::manage_repo
ikey
Data type: String
The Integration Key for Duo
skey
Data type: String
The Secret Key for Duo
host
Data type: StdLib::Host
The API hostname (i.e. api-XXXXXXXX.duosecurity.com
package_ensure
Data type: Enum['latest', 'present', 'absent']
This controls the package and config states The default is "present"
Default value: $duo_unix::params::package_ensure
config_ensure
Data type: Enum['file', 'absent']
This controls the presence or absense of the configuration file The default is "file"
Default value: $duo_unix::params::config_ensure
fallback_local_ip
Data type: Enum['no', 'yes']
If Duo Unix cannot detect the IP address of the client, setting fallback_local_ip = yes will cause Duo Unix to send the IP address of the server it is running on. The default is "no"
Default value: $duo_unix::params::fallback_local_ip
failmode
Data type: Enum['secure', 'safe']
On service or configuration errors that prevent Duo authentication, fail "safe" (allow access) or "secure" (deny access). The default is "safe".
Default value: $duo_unix::params::failmode
pushinfo
Data type: Enum['no', 'yes']
Include information such as the command to be executed in the Duo Push message. Either "yes" or "no". The default is "no".
Default value: $duo_unix::params::pushinfo
autopush
Data type: Enum['no', 'yes']
Either "yes" or "no". Default is "no". If "yes", Duo Unix will automatically send a push login request to the user's phone, falling back on a phone call if push is unavailable. Note that this effectively disables passcode authentication. If "no", the user will be prompted to choose an authentication method. When configured with autopush = yes, we recommend setting prompts = 1 The default is "no"
Default value: $duo_unix::params::autopush
motd
Data type: Enum['no', 'yes']
Print the contents of /etc/motd to screen after a successful login. Either "yes" or "no". The default is "no"
Default value: $duo_unix::params::motd
prompts
Data type: Integer[1, 3]
If a user fails to authenticate with a second factor, Duo Unix will prompt the user to authenticate again. This option sets the maximum number of prompts that Duo Unix will display before denying access. Must be 1, 2, or 3. Default is 3.
Default value: $duo_unix::params::prompts
accept_env_factor
Data type: Enum['no', 'yes']
Look for factor selection or passcode in the $DUO_PASSCODE environment variable before prompting the user for input. When $DUO_PASSCODE is non-empty, it will override autopush. Default is "no"
Default value: $duo_unix::params::accept_env_factor
proxy
Data type: Optional[StdLib::Httpurl]
Whether to use a proxy.
Default value: undef
groups
Data type: Optional[String]
The groups to assign.
Default value: undef
show_diff
Data type: Boolean
Whether to display differences when the file changes.
Default value: true
duo_unix::pam_config
Copyright © 2019 The Trustees of Indiana University SPDX-License-Identifier: BSD-3-Clause
This class sets up the appropriate file in the PAM stack to require Duo 2fa to successfully authenticate.
Examples
include duo_unix::pam_config
duo_unix::pam_ssh_config
Copyright © 2019 The Trustees of Indiana University SPDX-License-Identifier: BSD-3-Clause
This class will set the following parameters in the sshd_config file
- UsePAM yes
- UseDNS no
- ChallengeResponseAuthentication yes
Examples
include duo_unix::pam_ssh_config
duo_unix::params
Copyright © 2019 The Trustees of Indiana University SPDX-License-Identifier: BSD-3-Clause
This class just holds some parameter values for use elsewhere
duo_unix::repo
Copyright © 2019 The Trustees of Indiana University SPDX-License-Identifier: BSD-3-Clause
This class will add a repository to use to install the duo_unix package from Duo Inc.
Examples
include duo_unix::repo
duo_unix::ssh_config
This class sets values in the sshd config file. Specifically:
- ForceCommand /usr/sbin/login_duo
- PermitTunnel no
Examples
include duo_unix::ssh_config
Changelog
Release 4.2.4
- Fixes idempotency in ssh_config and adds sshd_config_path as a params default.
Release 4.2.3
- Writes sshd config to file in sshd_config.d instead of sshd_config file
Release 4.2.2
- Major change that should have coincided with 4.2.0: changing the use of augeas in favor of stdlib's file_line resource.
Release 4.2.1
- Resolves dependency issues
Release 4.2.0
- Adds duo_rsyslog option to the module - when activated, it sends Duo's syslog messages into the OS default auth log (also helpful for fail2ban use cases)
Release 4.1.0
- Adds pdk auto-added .config directory to gitignore
- Format linting on manifests/ssh_config.pp
- Adds 'with accept_env_factor => yes' context to spec/classes/duo_unix_spec.rb, to test when yes is specified for that class
- Adds jammy and noble Ubuntu releases to Duo repo setup
- Seemingly small but VERY significant changes to augeas blocks in manifests/ssh_config.pp to actually get this module to touch sshd_config at all, and to ensure idempotency when specifying an AcceptEnv option using Puppet's 'onlyif' f eature (augeas was NOT designed to do conveniently this)
Release 4.0.3
- Accordingly updates sshd_config file if the accept_env_factor parameter is set to 'yes'
Release 4.0.2
- Support Puppet 8, Drop Puppet 6, support stdlib 9.x
Release 4.0.1
- PDK update
- Merge pull request for optional cafile parameter (treydock)
Release 4.0.0
- Split ensure parameter to package_ensure and config_ensure
- Add reference file
Release 3.0.0
- Fixed unit tests
- Fixed puppet-lint issues
- Updated legacy facts
- Updated PDK
- Updated DUO GPG keys
- Updated README
- Dropped Ubuntu 14.04 support
- Dropped Ubuntu 16.04 support
- Dropped CentOS 6 support
- Dropped Debian 8 support
- Dropped Debian 9 support
- Added Ubuntu 20.04 support
- Added CentOS 9 support
- Added RedHat 9 support
- Added Debian 11 support
- Removed deprecated
puppetlabs/translate
module
Release 2.1.1
- Fixed some code quality issues
Release 2.1.0
- Added initial support for Rocky and Alma Linux
- They will be using the RedHat version of Puppet, not CentOS
Release 2.0.0
- Removed older unsupported versions of various operating systems
- This is why this is version 2x
- Switched how OS code name is derived on debian based systems
- Added some more documentation to the example
Release 1.0.11
- Updated PPA pgp key fingerprint
- Bumped version of PDK
Release 1.0.10
- Removed
AllowTcpForwarding no
as this conflicts in environments where the requirement forAllowTcpForwarding
needs to beyes
. - Updated pdk
- Updated Changelog
- Updated Metadata.json
- Removed vscode extension
Release 1.0.9
- scorgatelli-docutech added conditional repo management and fixed some bugs
Release 1.0.8
- Changed ssh service name to 'sshd' on RedHat based systems
Release 1.0.7
- Parameterize displaying diff
- Updated Yum Repo key
- Fix groups usage
Release 1.0.6
- Updated pdk
- Updated dependency upbound limit in metadata.json
Release 1.0.5
- Fixed my fix for the config template
Release 1.0.4
Bugfixes
- Fixed issue where
group
andhttp_proxy
were always set in the config even when blank
Release 0.1.0
Features
Bugfixes
Known Issues
Dependencies
- puppetlabs/apt (>= 6.0.0 < 11.0.0)
- puppetlabs/augeas_core (>= 1.0.0 < 2.0.0)
- puppetlabs/stdlib (>= 5.0.0 < 10.0.0)
- puppetlabs/yumrepo_core (>= 2.0.0 < 3.0.0)
BSD 3-Clause License Copyright (c) 2019, Indiana University All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.