| .Dd September 3, 2010 |
| .Dt LOGIN_DUO 8 |
| .Os |
| .Sh NAME |
| .Nm login_duo |
| .Nd second-factor authentication via Duo login service |
| .Sh SYNOPSIS |
| login_duo |
| .Op Fl d |
| .Op Fl c Ar file |
| .Op Fl h Ar host |
| .Op Fl f Ar user |
| .Op Ar command Op Ar args... |
| .Sh DESCRIPTION |
| .Nm |
| provides secondary authentication via the Duo authentication service, |
| executing the user's login shell or command only if successful. |
| .Pp |
| The following options are available: |
| .Bl -tag -width ".Cm failmode" |
| .It Fl c |
| Specify an alternate configuration file to load. Default is |
| .Pa /etc/duo/login_duo.conf |
| .It Fl d |
| Debug mode; send logs to stderr instead of syslog. |
| .It Fl h |
| Specify the remote IP address for this login (normally |
| taken from the |
| .Ev SSH_CONNECTION |
| environment variable, if set). |
| .It Fl f |
| Specify an alternate Duo user to authenticate as. |
| .El |
| .Pp |
| If |
| .Nm |
| is installed setuid root (the default), these options are |
| only available to the super-user. |
| .Pp |
| After successful Duo authentication, the user's login shell is |
| invoked, or if an alternate |
| .Ar command |
| or |
| .Ev SSH_ORIGINAL_COMMAND |
| environment variable is specified, it will be executed via the user's |
| shell with a -c option. |
| .Sh CONFIGURATION |
| The INI-format configuration file must have a |
| .Dq Li duo |
| section with the following options: |
| .Pp |
| .Bl -tag -width ".Cm failmode" |
| .It Cm host |
| Duo API host (required). |
| .It Cm ikey |
| Duo integration key (required). |
| .It Cm skey |
| Duo secret key (required). |
| .It Cm groups |
| If specified, Duo authentication is required only for users whose |
| primary group or supplementary group list matches one of the |
| space-separated |
| .Em pattern-lists |
| (see |
| .Sx PATTERNS |
| below). |
| .It Cm failmode |
| On service or configuration errors that prevent Duo authentication, fail |
| .Dq Li safe |
| (allow access) or |
| .Dq Li secure |
| (deny access). Default is |
| .Dq Li safe . |
| .It Cm pushinfo |
| Send command to be approved via Duo Push authentication. Default is |
| .Dq Li no . |
| .El |
| .Pp |
| An example configuration file: |
| .Bd -literal -offset 8n |
| [duo] |
| host = api-deadbeef.duosecurity.com |
| ikey = SI9F...53RI |
| skey = 4MjR...Q2NmRiM2Q1Y |
| pushinfo = yes |
| .Ed |
| .Pp |
| If installed setuid root (the default), |
| .Nm |
| performs Duo authentication as a dedicated privilege separation user, |
| requiring that the configuration file be owned and readable only by |
| this user. |
| .Sh PATTERNS |
| A |
| .Em pattern |
| consists of zero or more non-whitespace characters, |
| .Sq * |
| (a wildcard that matches zero or more characters), |
| or |
| .Sq ?\& |
| (a wildcard that matches exactly one character). |
| .Pp |
| A |
| .Em pattern-list |
| is a comma-separated list of patterns. Patterns within pattern-lists |
| may be negated by preceding them with an exclamation mark |
| .Pq Sq !\& . |
| For example, to specify Duo authentication for all users (except those |
| that are also admins), and for guests: |
| .Pp |
| .Dl groups = users,!wheel,!*admin guests |
| .Sh EXAMPLES |
| .Nm |
| can be enabled system-wide by specifying its full path as a |
| .Cm ForceCommand |
| in |
| .Xr sshd_config 5 |
| to capture any SSH remote login (including subsystems, remote |
| commands, and interactive login): |
| .Bd -literal -offset 8n |
| ForceCommand /usr/local/sbin/login_duo |
| .Ed |
| .Pp |
| Similarly, a group of administrators could require two-factor |
| authentication for login to a shared root account by specifying |
| .Nm |
| as the forced command for each public key in |
| .Pa ~root/.ssh/authorized_keys : |
| .Pp |
| .Bd -literal -offset 8n |
| 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 |
| .Ed |
| .Pp |
| A user without root access could configure their own account to |
| require Duo authentication via the same |
| .Pa ~/.ssh/authorized_keys |
| forced command mechanism and a user-installed (non-setuid) |
| .Nm . |
| .Sh FILES |
| .Bl -tag -width ".Cm failmode" |
| .It Pa /etc/duo/login_duo.conf |
| Default configuration file path |
| .El |
| .Sh AUTHORS |
| .Nm |
| was written by |
| .An "Duo Security" Aq duo_unix@duosecurity.com |
| .Sh NOTES |
| When used to protect remote SSH access, only interactive sessions |
| support interactive Duo login. For |
| .Xr scp 1 , |
| .Xr sftp 1 , |
| .Xr rsync 1 , |
| and other |
| .Xr ssh 1 |
| remote commands, |
| .Nm |
| 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. |
