LOGIN_DUO(8)

✨ LOGIN_DUO ✨

okay bestie, gather round, because we're talking about login_duo — the manual page lives in section 8 (system manager's manual territory, iykyk) and it's literally the second-factor bouncer for your login. no cap. 💅

---

🌸 NAME 🌸

login_duo — second-factor authentication via Duo login service

---

🦋 SYNOPSIS 🦋

login_duo [-d] [-c file] [-h host] [-f user] [command [args...]]

---

💖 DESCRIPTION 💖

So here's the vibe: login_duo gives you secondary authentication through the Duo authentication service, and it only runs the user's login shell (or whatever command) if that auth actually succeeds. like, no passing go, no collecting $200, no shell. 🙈

the following options are available, bestie:

• -c — point it at an alternate configuration file to load. the default is /etc/duo/login_duo.conf.
• -d — debug mode, babes. logs go to stderr instead of syslog.
• -h — specify the remote IP address for this login (normally it's taken from the SSH_CONNECTION environment variable, if that's set).
• -f — specify an alternate Duo user to authenticate as.

🚨 if login_duo is installed setuid root (which is the default, jsyk), these options are only available to the super-user. so don't come for them unless you're root, periodt.

After successful Duo authentication, the user's login shell gets invoked — or, if an alternate command or the SSH_ORIGINAL_COMMAND environment variable is specified, that gets executed via the user's shell with a -c option. cute, efficient, iconic. 🎀

---

🧚 CONFIGURATION 🧚

the INI-format configuration file must have a "duo" section with the following options. mandatory. non-negotiable. the way that config file needs a duo section… 💀

• host — Duo API host (required). yes bestie, required.
• ikey — Duo integration key (required). also required, don't skip it.
• skey — Duo secret key (required). required!! three for three.
• groups — if you set this, Duo authentication is only required for users whose primary group or supplementary group list matches one of the space-separated pattern-lists (peep the "PATTERNS" section below 👀).
• failmode — on service or configuration errors that prevent Duo authentication, fail "safe" (allow access) or "secure" (deny access). default is "safe".
• pushinfo — send the 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".
• verified_push — enable support for Duo Verified Push authentication. cannot be used together with autopush. 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 you're using autopush, it's 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 it's unable to determine the authentication user's IP address, fall back 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, for the girlies who like a visual 🍓:

[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. so lock that file down, bestie, it's giving security girlie. 🔒

---

🌈 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

see how that works? the ! is the "not her" of the pattern world. 💅

---

🔥 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). obsessed with a one-liner that does all that:

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

and 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. main character energy fr fr. 👑

---

💜 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. so don't panic when you don't see the little progress dance — it's intentional, bestie. 😭

---

that's the whole page, and this one's from the Debian crowd, dated September 3, 2010 — yes, 2010, a true elder icon in section 8 of the System Manager's Manual. thanks for coming to my ted talk, go forth and second-factor responsibly 🫶💖