File README.SUSE of Package duo_unix

Duo Unix provides two-factor authentication via their service; see
<https://duo.com/docs/duounix> and the pam_duo(8) and pam.conf(5) man pages for
details.  It is implemented via two methods:
- the PAM module pam_duo
- the binary login_duo

login_duo can be run interactively, but it is most commonly used as a
ForceCommand setting in sshd_config.  It requires additional permissions to
run, as described in /etc/permissions.d/duo_unix.  In most cases pam_duo is the
preferred solution and login_duo is not needed.  Each method has its own
configuration file under /etc/duo.

To configure pam_duo, add it to the authentication stack such that it is
invoked after a successful login.  You can either add it directly to
common-auth, which will apply to all services, or copy common-auth to an
alternate file (e.g. duo-auth) and configure specific services (sshd, login,
gdm, etc.) to include duo-auth instead of common-auth.

NOTE: If you modify common-auth, make sure it is a normal file and not a
symlink to common-auth-pc, so that pam-config does not overwrite your changes!
Unfortunately pam-config is not extensible, so we must work around it.

Here is an example PAM auth stack with both local authentication (pam_unix) and
central authentication (sssd) using Duo; Duo is only invoked for central
accounts:
# THIS IS AN EXAMPLE, DO NOT BLINDLY COPY!
auth	required			pam_env.so
auth	[default=1 success=ok]		pam_localuser.so
auth	[success=done default=die]	pam_unix.so try_first_pass
auth	requisite			pam_sss.so
auth	required			pam_duo.so

It does these things:
1. Skip pam_unix if pam_localuser fails (i.e. user is not in the local passwd
file).

2. If we reached pam_unix, attempt authentication and immediately exit with the
result, whether success or failure.

3. Invoke sssd auth; if it fails, immediately return failure; otherwise invoke
Duo.

4. Duo must succeed.

Again, this is only an example and you must adapt to your own environment.
There are alternate methods of achieving the same result.  (A common
alternative workflow is using 'auth required pam_deny.so' at the end and
"sufficient" for previous services.)

Keep in mind the following principles:
- Test both successful and failed logins for every authentication provider
  after making any changes.  Duo should only be invoked for successful logins,
  not failed ones, and failed logins (including failure to approve the Duo
  prompt) MUST NOT allow access.
- Ensure that both authentication factors (password and Duo) are invoked.  If
  one can be skipped, your 2FA is now just a single factor!
- Note that some SSH authentication methods such as public key or GSSAPI do not
  invoke PAM (and thus Duo).  You must determine if this is acceptable in your
  environment, or if it is better to disable those.  Duo has some articles on
  this in their knowledge base.
- Keep a root shell open while making any changes to the PAM configuration, to
  avoid locking yourself out.