1LOGIN_DUO(8) BSD System Manager's Manual LOGIN_DUO(8)
2
4 login_duo — second-factor authentication via Duo login service
5
7 login_duo [-d] [-c file] [-h host] [-f user] [command [args...]]
8
10 login_duo provides secondary authentication via the Duo authentication
11 service, executing the user's login shell or command only if successful.
12 The following options are available:
14 -c Specify an alternate configuration file to load. Default is
16 /etc/duo/login_duo.conf
17 -d Debug mode; send logs to stderr instead of syslog.
19 -h Specify the remote IP address for this login (normally taken
21 from the SSH_CONNECTION environment variable, if set).
22 -f Specify an alternate Duo user to authenticate as.
24 If login_duo is installed setuid root (the default), these options are
26 only available to the super-user.
27 After successful Duo authentication, the user's login shell is invoked,
29 or if an alternate command or SSH_ORIGINAL_COMMAND environment variable
30 is specified, it will be executed via the user's shell with a -c option.
31
33 The INI-format configuration file must have a “duo” section with the fol‐
34 lowing options:
35 host Duo API host (required).
37 ikey Duo integration key (required).
39 skey Duo secret key (required).
41 groups If specified, Duo authentication is required only for users
43 whose primary group or supplementary group list matches one of
44 the space-separated pattern-lists (see PATTERNS below).
45 failmode On service or configuration errors that prevent Duo authentica‐
47 tion, fail “safe” (allow access) or “secure” (deny access). De‐
48 fault is “safe”.
49 pushinfo Send command to be approved via Duo Push authentication. De‐
51 fault is “no”.
52 http_proxy
54 Use the specified HTTP proxy, same format as the HTTP_PROXY en‐
55 vironment variable.
56 autopush Upon successful first-factor authentication, automatically send
58 a login request to the primary second-factor (usually Duo
59 Push). Can be “yes” or “no”. Default is “no”.
60 motd Print the contents of /etc/motd to screen after a successful
62 login. Either "yes" or "no." Default is "no".
63 prompts Number of login attempts a user gets. Default is 3. If using
65 autopush, it is recommended to set prompts to 1.
66 accept_env_factor
68 Look for factor selection or passcode in the DUO_PASSCODE envi‐
69 ronment variable, before prompting the user. Can override auto‐
70 push. Default is "no".
71 fallback_local_ip
73 If unable to determine the authentication users's IP address,
74 fallback on the IP address of the server. Default is "no".
75 https_timeout
77 Set to the number of seconds to wait for HTTPS responses from
78 Duo Security. If Duo Security takes longer than the configured
79 number of seconds to respond to the preauth API call, the con‐
80 figured failmode is triggered. Other network operations such as
81 DNS resolution, TCP connection establishment, and the SSL hand‐
82 shake have their own independent timeout and retry logic. De‐
83 fault is 0, which disables the HTTPS timeout.
84 An example configuration file:
86 [duo]
88 host = api-deadbeef.duosecurity.com
89 ikey = SI9F...53RI
90 skey = 4MjR...Q2NmRiM2Q1Y
91 pushinfo = yes
92 autopush = yes
93 If installed setuid root (the default), login_duo performs Duo authenti‐
95 cation as a dedicated privilege separation user, requiring that the con‐
96 figuration file be owned and readable only by this user.
97
99 A pattern consists of zero or more non-whitespace characters, ‘*’ (a
100 wildcard that matches zero or more characters), or ‘?’ (a wildcard that
101 matches exactly one character).
102 A pattern-list is a comma-separated list of patterns. Patterns within
104 pattern-lists may be negated by preceding them with an exclamation mark
105 (‘!’). For example, to specify Duo authentication for all users (except
106 those that are also admins), and for guests:
107 groups = users,!wheel,!*admin guests
109
111 login_duo can be enabled system-wide by specifying its full path as a
112 ForceCommand in sshd_config(5) to capture any SSH remote login (including
113 subsystems, remote commands, and interactive login):
114 ForceCommand /usr/local/sbin/login_duo
116 Similarly, a group of administrators could require two-factor authentica‐
118 tion for login to a shared root account by specifying login_duo as the
119 forced command for each public key in ~root/.ssh/authorized_keys:
120 command="/usr/local/sbin/login_duo -f alice"
122 ssh-rsa AAAAB2...19Q== alice@example.net
123 command="/usr/local/sbin/login_duo -f bob"
124 ssh-dss AAAAC3...51R== bob@example.net
125 A user without root access could configure their own account to require
127 Duo authentication via the same ~/.ssh/authorized_keys forced command
128 mechanism and a user-installed (non-setuid) login_duo.
129
131 /etc/duo/login_duo.conf
132 Default configuration file path
133
135 login_duo was written by Duo Security <support@duosecurity.com>
136
138 When used to protect remote SSH access, only interactive sessions support
139 interactive Duo login. For scp(1), sftp(1), rsync(1), and other ssh(1)
140 remote commands, login_duo automatically tries the user's default out-of-
141 band factor (smartphone push or voice callback) and disables real-time
142 login progress reporting to provide a clean shell environment.
143BSD September 3, 2010 BSD