Skip navigation

Duo Two-Factor Authentication for macOS

Last Updated: March 22nd, 2022

Duo integrates with macOS to add two-factor authentication to macOS console logons.

Issues with macOS 12.3 and Duo Authentication for macOS

Duo Authentication for macOS versions 1.1.0 and earlier are not compatible with macOS 12.3. If you use or plan to use Duo Authentication for macOS you must upgrade to version 1.1.1 before updating to macOS 12.3.
If you update a system with Duo Authentication for macOS 1.1.0 or earlier to the recent macOS 12.3 release then Duo authentication may not function, allowing users to log in without 2FA. In addition, the uninstall Python script will not work due to removal of a required dependency.

Duo Authentication for macOS does not support Apple M1 ARM-based processors. Do not install Duo on these systems.


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 1.1.1 supports macOS 10.13 (High Sierra) and later versions, which includes:

  • 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)
  • 10.14 (Mojave)
  • 10.13 (High Sierra)

As of Duo release 1.1.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.12 (Sierra)
  • 10.11 (El Capitan)
  • 10.10 (Yosemite)

Connectivity Requirements

This application communicates with Duo's service on TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review this Duo KB article.

Duo Factor Support

Duo for macOS supports these factor types for 2FA:

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

Touch ID is not a valid factor for the Duo macOS application.

Walkthrough Video


Important Notes

  • Upgrading from macOS 12.x to macOS 12.3 disables Duo's Mac Logon package. You can restore Duo after updating your operating system with the restore_after_upgrade script included in the Duo for macOS 1.1.1 zip file.

    If you upgrade to macos 12.3 before installing Duo Mac Logon 1.1.1, then your currently installed Duo 2FA application becomes inactive. You must download and install Duo Mac Logon 1.1.1, which is the first release with macOS 11 support. There is no need to also run the restore script after installing Duo 1.1.1.

  • Upgrading from macOS 10.x to macOS 11.0 disables Duo's Mac Logon package. You can restore Duo after updating your operating system with the restore_after_upgrade script included in the Duo for macOS 1.1.1 zip file.

    If you upgrade to macos 11 before installing Duo Mac Logon 1.1.0 or later, then your currently installed Duo 2FA application becomes inactive. You must download and install the current release of Duo Mac Logon. There is no need to also run the restore script after installing Duo 1.1.0 or later.

    This is also seen when upgrading from 10.11 El Capitan to 10.12 Sierra or 10.11 El Capitan to 10.13 High Sierra. After these updates you can either restore Duo using the script or reinstall the Duo application.

    OS upgrades directly from 10.12 Sierra to 10.13 High Sierra or between macOS 10 versions beyond 10.13 do not experience this issue.

  • 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. 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 ( and the Duo plugin installer and uninstaller .pkg package files.

  6. 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:


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

    ./ /path/to/MacLogon-NotConfigured-1.1.1.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.

    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 smart card is attached to the system then the Duo Prompt is not shown. Specify false to disable smart card logon and require Duo 2FA.

    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-1.1.1.pkg:

    ./ /path/to/MacLogon-NotConfigured-1.1.1.pkg
     Duo Security Mac Logon configuration tool v1.1.1.
     See for documentation
     Enter skey: gdk2261xxc9c73fdxx9w73ffsi23xxbak282gebxxs
     Enter API Hostname:
     Should fail open (true or false): true
     Should bypass 2FA when using smartcard (true or false): false
     Should auto push if possible (true or false): true
     Modifying ./MacLogon-NotConfigured-1.1.1.pkg...
     Updating config.plist ikey, skey, host, fail_open, smartcard_bypass, and auto_push config...
     Finalizing package, saving as ./MacLogon-1.1.1.pkg
     Cleaning up temp files...
     Done! The package ./MacLogon-1.1.1.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 for administrators only.

Do not change the permissions of the com.duosecurity.maclogon.plist file!
$ sudo cat /private/var/root/Library/Preferences/com.duosecurity.maclogon.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

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.

Duo Prompt on macOS

Select any available factor to verify your identity to Duo:

  • Duo 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.
  • 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.

Uninstalling Duo

If you'd like to remove Duo authentication for macOS from your system, double-click the MacLogon-Uninstaller-1.1.1.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 with the restore_after_upgrade script included in the Duo MacLogon 1.1.1 and later zip file.

In a Terminal window, change to the extracted MacLogon directory and run the restore script:

sudo restore_after_upgrade


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

Network Diagram

Duo Mac Logon 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