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

1. Description
2. Setup - The basics of getting started with duo_unix
   • What duo_unix affects
   • Setup requirements
   • Beginning with duo_unix
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. 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
• 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 distros
• duo_unix::pam_config: This class will configure PAM to require Duo
• duo_unix::pam_ssh_config: This class sets sshd up to use PAM
• duo_unix::params: Default parameter values for the duo_unix module
• duo_unix::repo: Add an apt/yum repo for Debian/RedHat based systems
• duo_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 for AllowTcpForwarding needs to be yes.
• 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 and http_proxy were always set in the config even when blank

Release 0.1.0

Features

Bugfixes

Known Issues