NAME

pam_duo —

PAM module for Duo authentication

SYNOPSIS

pam_duo.so [conf=⟨FILENAME⟩]

DESCRIPTION

pam_duo provides secondary authentication (typically after successful password-based authentication) through the Duo authentication service.

OPTIONS

PAM module configuration options supported:

conf: Specify an alternate configuration file to load. Default is /usr/local/etc/duo/pam_duo.conf
debug: Debug mode; send log messages to stderr instead of syslog.

CONFIGURATION

The INI-format configuration file must have a “duo” section with the following options:

host: Duo API host (required).
ikey: Duo integration key (required).
skey: Duo secret key (required).
groups: If specified, Duo authentication is required only for users whose primary group or supplementary group list matches one of the space-separated pattern-lists (see PATTERNS below).
failmode: On service or configuration errors that prevent Duo authentication, fail “safe” (allow access) or “secure” (deny access). Default is “safe”.
pushinfo: Send command to be approved via Duo Push authentication. Default is “no”.
http_proxy: Use the specified HTTP proxy, same format as the HTTP_PROXY environment variable.
autopush: Automatically send a login request to the first factor (usually push), instead of prompting the user. Default is "no".
prompts: Set the maxiumum number of prompts pam_duo will show before denying access. Default is 3.
fallback_local_ip: If unable to detect the authorizing user's IP address, fallback on the server's IP. Default is "no".
send_gecos: Instead of using the unix username, send Duo the contents of the GECOS field from /usr/local/etc/passwd. Default is "no".

An example configuration file:

[duo]
host = api-deadbeef.duosecurity.com
ikey = SI9F...53RI
skey = 4MjR...Q2NmRiM2Q1Y
pushinfo = yes
autopush = yes

Other authentication restrictions may be implemented using pam_listfile(8), pam_access(8), etc.

PATTERNS

A pattern consists of zero or more non-whitespace characters, ‘*’ (a wildcard that matches zero or more characters), or ‘?’ (a wildcard that matches exactly one character).

A pattern-list is a comma-separated list of patterns. Patterns within pattern-lists may be negated by preceding them with an exclamation mark (‘!’). For example, to specify Duo authentication for all users (except those that are also admins), and for guests:

groups = users,!wheel,!*admin
  guests

FILES

/usr/local/etc/duo/pam_duo.conf: Default configuration file path

AUTHORS

pam_duo was written by Duo Security ⟨support@duosecurity.com⟩

NOTES

When used with OpenSSH's sshd(8), only PAM-based authentication can be protected with this module; pubkey authentication bypasses PAM entirely. OpenSSH's PAM integration also does not honor an interactive pam_conv(3) conversation, prohibiting real-time Duo status messages (such as during voice callback).