Duo Two-Factor Authentication for macOS

Overview

Duo Authentication for macOS add Duo two-factor authentication to macOS local console logins. Duo for MacOS doesn't add 2FA for remote SSH connections. Looking for SSH login protection? Try Duo Unix.

Once installed, Duo authentication is required for new console logons, but not when unlocking the screensaver or when an already logged-on user wakes the system from sleep.

System Requirements

Duo's Mac authorization plugin 2.0.0 supports macOS 10.15 (Catalina) and later versions, which includes:

• 14 (Sonoma) - First supported in 2.0.2
• 13 (Ventura) - First supported in 2.0.0
• 12.3 (Monterey) - First supported in 1.1.1
• 12.0 (Monterey) - first supported in 1.1.0
• 11.0 (Big Sur) - first supported in 1.1.0
• 10.15 (Catalina)

As of Duo release 2.0.0, these macOS versions were not tested and may not work in the future. Consider updating to a newer version of macOS still supported by Apple.

• 10.14 (Mojave)
• 10.13 (High Sierra)
• 10.12 (Sierra)
• 10.11 (El Capitan)
• 10.10 (Yosemite)

Apple Silicon M Series Support

Duo for macOS versions 2.0.0 and later include Apple M1 and M2 support.

Duo Factor Support

Duo for macOS supports these factor types for online two-factor authentication:

• Duo Push (Duo Mobile)
• Duo Mobile Passcodes
• SMS Passcodes
• OTP Hardware Token Passcodes
• Phone Call
• Bypass Codes

Be aware that:

• Touch ID is not a valid factor for the Duo macOS application.
• Offline Access for Duo on macOS does not yet work with security keys.

Walkthrough Video

Important Notes

• Upgrading macOS versions may disable Duo's Mac Logon package. You can restore Duo after updating your operating system with the MacLogon-Restore-2.0.2.pkg package included in the Duo for macOS 2.0.2 zip file.

• For additional client security, we recommend setting a firmware password to prevent disabling Duo authentication via recovery mode.

Before You Begin

Before installing Duo for macOS, ensure any other login mechanisms present on your Mac client support Swift 5. Installing Duo for macOS without first verifying that any other installed auth plugins support Swift 5 may prevent user logins.

Enroll a User

Duo's macOS authorization plugin doesn't support inline self-service enrollment. Your users must be enrolled in Duo before logging in, and their Duo usernames must match the macOS username.

Add your first user to Duo, either manually or using bulk enrollment. The username should match your macOS logon name. You can obtain a list of your Mac's local users with this Terminal command:

dscl . ls /Users | grep -v _

If the user logging in to macOS after the Duo plugin is installed does not exist in Duo, the user may not be able to log in.

We recommend using bulk enrollment or directory sync to send your users unique self-enrollment links via email. Read the enrollment documentation to learn more.

First Steps

1. Sign up for a Duo account.

2. Log in to the Duo Admin Panel and navigate to Applications.

3. Click Protect an Application and locate the entry for macOS in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.

   Treat your secret key like a password

   The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

4. We recommend setting the New User Policy for your macOS application to Deny Access, as no unenrolled user may complete Duo enrollment via this application.

   If you're not ready to enforce Duo authentication for all users of this system yet, configure the New User Policy for your macOS application to "Allow Access". This only prompts users enrolled in Duo for 2FA approval, and lets users not yet enrolled in Duo log on to the system without seeing the Duo prompt.

   When you are ready to start requiring 2FA for macOS logins, update the policy applied to this application to deny access to unenrolled users as recommended.

5. If you'd like to enable offline access with Duo MFA you can do that now in the "Offline Access Settings" section of the Duo application page, or return to the Admin Panel later to configure offline access after first verifying logon success with two-factor authentication.

6. Download and uncompress the Duo macOS plugin installer package and scripts zip archive. This zip file contains the configuration script for the Duo installer package (configure_maclogon.sh) and the Duo plugin installer and uninstaller .pkg package files.

7. Ensure your Mac system's time is correct. You can set your Mac to obtain the correct time automatically. Open "System Preferences" and then click "Date & Time". On the "Date & Time" tab, check the box next to "Set date and time automatically" and pick a time server for your region from the drop-down list. Click save when done.

Run the Installer Package

1. Change to the extracted MacLogon directory and run the configuration script:

   ./configure_maclogon.sh

   If the configuration script is in a different directory than the Duo MacLogon .pkg file, specify the full path to MacLogon-NotConfigured-2.0.2.pkg when running the script.

   ./configure_maclogon.sh /path/to/MacLogon-NotConfigured-2.0.2.pkg

   Supply the following information when prompted by the script:

   Enter ikey	Provide the integration key from the macOS application page in the Duo Admin Panel.
   Enter skey	Provide the secret key from the macOS application page in the Duo Admin Panel.
   Enter API hostname	Provide the API hostname from the macOS application page in the Duo Admin Panel.
   Should fail open	Specify true to allow user logon without completing two-factor authentication if the Duo Security cloud service is unreachable or false to prevent user logon when Duo is unreachable. Defaults to false. If any user of the system sets up offline access then users on that system who have not set up offline access may not log in, even if the fail open configuration is set to allow it.
   Should bypass 2FA when using smartcard	Specify true to permit smart card logon as an alternative to Duo authentication after successful submission of primary credential. If a PIV card reader with the smart card of the authenticating user is attached to the system then the Duo Prompt is not shown. Specify false to disable smart card logon and require Duo 2FA. Defaults to false. Do not enable this for Duo versions prior to 2.0.0.
   Should auto push if possible	Specify true to automatically send a Duo Push or phone call authentication request after primary credential validation or false to let the user initiate Duo authentication via interactive factor selection.

   The configuration script creates a new deployment package with the values you specify. For example, this command configures the Duo for macOS installation package located in the same directory as the configuration script, with fail open enabled, smart card login disabled, and automatic push enabled, and then creates the deploy package MacLogon-2.0.2.pkg:

   ./configure_maclogon.sh /path/to/MacLogon-NotConfigured-2.0.2.pkg
   
    Duo Security Mac Logon configuration tool v2.0.2.
    See https://duo.com/docs/macos for documentation
   
    Enter ikey: DIXXXXXXXXXXXXXXXXX
    Enter skey: gdk2261xxc9c73fdxx9w73ffsi23xxbak282gebxxs
    Enter API Hostname: api-xxxxxxxx.duosecurity.com
    Should fail open (true or false) [default: false]: true
    Should bypass 2FA when using smartcard (true or false) [default: false]: false
    Should auto push if possible (true or false): true
   
    Modifying ./MacLogon-NotConfigured-2.0.2.pkg...
   
    Updating config.plist ikey, skey, host, fail_open, smartcard_bypass, and auto_push config...
   
    Finalizing package, saving as ./MacLogon-2.0.2.pkg
   
    Cleaning up temp files...
   
    Done! The package ./MacLogon-2.0.2.pkg has been configured for your use.

2. Double-click the newly-created Duo MacLogon deploy .pkg file to start installation. Follow the prompts to select the destination disk and enter the sudo password when prompted by the installer.

You'll need to run the script again if you want to change any of the configuration values, then reinstall the package and restart your Mac for the change to take effect.

Verify Duo Configuration

If you want to verify the Duo MacLogon application settings you can view the /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist file. This file is read-only and viewable by administrators.

Changing Options After Install

Modifying Duo options with the plutil command requires administrator-level sudo privileges.

Fail Mode

Change the fail mode configuration post-installation with the following syntax, specifying true to fail-open or false to fail-closed:

sudo plutil -replace fail_open -bool false /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist

Automatic Push

Turn automatic push on or off post-installation with the following syntax, specifying true to send an automatic Duo Push or false to wait for the user to select a factor:

sudo plutil -replace auto_push -bool false /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist

Smart Card Bypass

Enable or disable two-factor authentication for a user when they log in with a smart card post-installation with the following syntax, specifying true to skip 2FA after smart card for primary credentials or false to require 2FA after smart card login:

sudo plutil -replace smartcard_bypass -bool false /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist

Test Your Setup

To test your setup, attempt to log in to your newly-configured system as a user enrolled in Duo. The Duo Prompt appears after you successfully submit your macOS credentials.

If you enabled automatic push during install then check your phone for a Duo Push login request to approve. Otherwise, select any available factor to verify your identity to Duo:

• Send Push: Send a request to your smartphone. You can use Duo Push if you've installed and activated Duo Mobile on your device.
• Call Me: Perform phone callback authentication.
• Enter a Passcode: Log in using a passcode generated with Duo Mobile, received via SMS, generated by your hardware token, or provided by an administrator. To have a new batch of SMS passcodes sent to you click the Send me new codes button. You can then authenticate with one of the newly-delivered passcodes.

Offline Access

Duo Authentication for macOS v2.0.0 introduces offline access, allowing secure local logons to macOS systems even when unable to contact Duo’s cloud service.

Offline Access Requirements

• Duo Essentials, Advantage, or Premier plan subscription (learn more about Duo's different plans and pricing)
• Duo Authentication for macOS v2.0.0 or later
  • When any one user of a given macOS system completes offline access setup, then Duo effectively will "fail closed" for users who have not completed offline access setup even if the fail open configuration is "true".
  • If you set Should fail open to "true" to allow fail-open access during installation, you can change it to "false" after installation.

To enroll in and complete offline authentication users must have:

• Duo Mobile for Android or iOS version 3.22 or later.

Note these functional limitations for offline access authentication devices:

• Duo on macOS does not support security keys for offline access as of v2.0.0.
• Users may only register one authenticator for offline access, so it is not possible to register backup devices for approving offline login. Registering a second offline device deactivates the first one.

Offline Access Configuration

1. Return to your "macOS" application page in the Duo Admin Panel. You may have given the Duo macOS application a different name when you created it, but the "Type" will always be shown as "macOS" on the Applications page.

2. Scroll down to the bottom of the macOS application’s page to locate the Offline Access Settings. Check the box next to Enable offline login and enrollment to turn on offline access.

3. Check the Only allow offline login from users in certain groups to specify a group or groups of Duo users permitted to use offline access. Users who are not members of the groups you select here won't be able to enroll in offline access or login in with MFA when the macOS system is unable to contact Duo.

   If you also configured permitted groups on your macOS application, users need to be members of both the permitted and the offline login groups to use offline access.

4. Choose from the two options for expiring offline access in the Prevent offline login after setting:

   • Enter the maximum number of offline logins allowed to users. With this option, there is no expiration date for offline access.

     Users may log on to the Duo-protected macOS system while offline the number of times you specify here. They'll need to reconnect their offline computer to the internet upon reaching this limit. The next time they perform an online Duo authentication, the computer’s offline counter resets.

   • Enter the maximum number of days offline, up to 365. With this option, there is no limit to the number of times a user logs in while offline during the allowed period.

     Users need to reconnect their offline computer to the internet upon reaching the end of the period you define here. The next time they perform an online Duo authentication, the computer’s offline expiration date resets. If the user does not perform online Duo authentication before the maximum number of days specified here is reached, they can no longer log in offline, and so must connect to Duo's service in order to log in at all.

5. The only available authenticator for macOS offline access is Duo Mobile passcodes generated by the Duo Mobile application for iOS or Android. Enable the available offline authentication method in the Offline authentication methods setting. You may not save the offline settings without the available authenticator option checked.

   Any authentication method enabled for offline access is always permitted, overriding any other policy setting restricting authentication methods for the macOS application.

6. Click the Save button.

Note that changes to the offline access settings apply at the next online authentication per user on systems with multiple users. For example, if a given Mac system has two users enrolled in offline access and you change the maximum number of offline logins while that system is offline, when one user performs a subsequent online authentication your setting change will become effective only for that user, not for both users of that system. The second user must also complete an online authentication to receive the updated configuration.

Offline Access Logging

No information about logins using offline access is reported in Duo Admin Panel authentication reports while the macOS system is offline. At the next online authentication, login events that occurred while the system was offline are sent to Duo's service. These events show up in the Authentication Log with other user access results, and show the offline authentication method used.

Offline access events are stored locally at /var/root/Library/com.duosecurity.maclogon/ as <username>.auth for each user while the system is offline. Administrators can view the log file contents in Terminal.

Advanced Configuration

Force Offline Reactivation for a User

To force offline reactivation for a previously activated user on a given macOS system, an administrator can delete their existing offline registration with the following syntax:

sudo rm /var/root/Library/com.duosecurity.maclogon/<username>-policy.json

Offline Access Activation and Login

The next time you (or your end user) logs in the workstation while it’s online and able to contact Duo, the offline activation prompt displays after successful two-factor authentication.

Step through the guided activation process to configure Duo Mobile for offline MFA.

Once you’ve activated offline access for your account, when your computer isn’t able to contact Duo’s cloud service you’ll automatically be offered the option to login with an offline code after successfully submitting your macOS username and password.

You can also reactivate offline access from the online Duo prompt. Note that only one authentication device — a single phone with Duo Mobile — may be activated for offline login. Activating a second device via the reactivation process deactivates the first.

See the full offline activation and login experience in the Duo User Guide for macOS Logon.

Uninstalling Duo

If you'd like to remove Duo authentication for macOS from your system, double-click the MacLogon-Uninstaller-2.0.2.pkg package included in the Duo MacLogin zip file and follow the installer prompts.

Restoring Duo

If upgrading macOS to a new version removed Duo logon protection from your system, restore it by running the MacLogon-Restore-2.0.2.pkg script included in the Duo MacLogon 2.0.0 and later zip file.

Troubleshooting

Need some help? Take a look at our macOS Logon Knowledge Base articles or Community discussions. For further assistance, contact Support.

Log Filtering Levels

You may need to increase the local logging level when troubleshooting issues with Duo. To change the logging level run the following command as an administrator, specifying the -integer value as 0 for informational, 1 for debug, or 2 for trace:

sudo plutil -replace debug -integer 1 /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist

Network Diagram

1. Primary authentication at Mac console
2. Duo macOS Logon connection established to Duo Security over TCP port 443
3. Secondary authentication request via Duo Security’s service
4. User approves Duo authentication request
5. Authentication response from Duo sent to Mac authentication plugin
6. Console session logged in