table of contents
LOGIN_DUO(8) | System Manager's Manual | LOGIN_DUO(8) |
NAME¶
login_duo
—
second-factor authentication via Duo login
service
SYNOPSIS¶
login_duo [-d
] [-c
file] [-h
host] [-f
user] [command
[args...]]
DESCRIPTION¶
login_duo
provides secondary
authentication via the Duo authentication service, executing the user's
login shell or command only if successful.
The following options are available:
-c
- Specify an alternate configuration file to load. Default is /etc/duo/login_duo.conf
-d
- Debug mode; send logs to stderr instead of syslog.
-h
- Specify the remote IP address for this login (normally taken from the
SSH_CONNECTION
environment variable, if set). -f
- Specify an alternate Duo user to authenticate as.
If login_duo
is installed setuid root (the
default), these options are only available to the super-user.
After successful Duo authentication, the user's login shell is
invoked, or if an alternate command or
SSH_ORIGINAL_COMMAND
environment variable is
specified, it will be executed via the user's shell with a -c option.
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
- Upon successful first-factor authentication, automatically send a login
request to the primary second-factor (usually Duo Push). Can be
“
yes
” or “no
”. Default is “no
”. motd
- Print the contents of /etc/motd to screen after a successful login. Either "yes" or "no." Default is "no".
prompts
- Number of login attempts a user gets. Default is 3. If using autopush, it is recommended to set prompts to 1.
accept_env_factor
- Look for factor selection or passcode in the DUO_PASSCODE environment variable, before prompting the user. Can override autopush. Default is "no".
fallback_local_ip
- If unable to determine the authentication users's IP address, fallback on the IP address of the server. Default is "no".
https_timeout
- Set to the number of seconds to wait for HTTPS responses from Duo Security. If Duo Security takes longer than the configured number of seconds to respond to the preauth API call, the configured failmode is triggered. Other network operations such as DNS resolution, TCP connection establishment, and the SSL handshake have their own independent timeout and retry logic. Default is 0, which disables the HTTPS timeout.
An example configuration file:
[duo] host = api-deadbeef.duosecurity.com ikey = SI9F...53RI skey = 4MjR...Q2NmRiM2Q1Y pushinfo = yes autopush = yes
If installed setuid root (the default),
login_duo
performs Duo authentication as a dedicated
privilege separation user, requiring that the configuration file be owned
and readable only by this user.
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
EXAMPLES¶
login_duo
can be enabled system-wide by
specifying its full path as a ForceCommand
in
sshd_config(5) to capture any SSH remote login (including
subsystems, remote commands, and interactive login):
ForceCommand /usr/local/sbin/login_duo
Similarly, a group of administrators could require two-factor
authentication for login to a shared root account by specifying
login_duo
as the forced command for each public key
in ~root/.ssh/authorized_keys:
command="/usr/local/sbin/login_duo -f alice" ssh-rsa AAAAB2...19Q== alice@example.net command="/usr/local/sbin/login_duo -f bob" ssh-dss AAAAC3...51R== bob@example.net
A user without root access could configure their own account to
require Duo authentication via the same
~/.ssh/authorized_keys forced command mechanism and
a user-installed (non-setuid) login_duo
.
FILES¶
- /etc/duo/login_duo.conf
- Default configuration file path
AUTHORS¶
login_duo
was written by
Duo Security
⟨support@duosecurity.com⟩
NOTES¶
When used to protect remote SSH access, only interactive sessions
support interactive Duo login. For scp(1),
sftp(1), rsync(1), and other
ssh(1) remote commands, login_duo
automatically tries the user's default out-of-band factor (smartphone push
or voice callback) and disables real-time login progress reporting to
provide a clean shell environment.
September 3, 2010 | Debian |