Support your macOS Desktop MFA users

After Desktop MFA is configured and deployed, Okta prompts users to enroll one or more offline authentication factors. These factors allow secure access to the computer's apps and data, even if the computer or the user is offline.

For increased security, Desktop MFA times out after five minutes of inactivity during the enrollment process. This timeout isn't configurable. The device's display is locked, and the user must restart the registration process.

To prepare users for the changes to their sign-in flow, Okta provides a series of templates to communicate Desktop MFA plans. Download the templates from the Launch Kit for Okta Admins, and then copy the appropriate wording to help explain the new authentication process to users.

Establish a bug reporting channel

Ask users to report issues or bugs in Okta Verify from their mobile device. The Menu bar of their Okta Verify mobile app contains a Send Feedback link. Users should tap Report a bug and fill out the form. System Logs are automatically attached, and the report is sent to Okta. Users should then contact someone within your organization for assistance signing in to the computer.

Desktop MFA Recovery

Request a device recovery PIN

If you lost or don't have access to your Okta Verify enrolled MFA device and can't sign in to your computer using another authenticator, your IT administrator can provide you with a temporary device recovery PIN, which grants you computer access for a limited period of time.

  1. Contact your IT administrator. Make note of your computer's name, model, and serial number. You need this information to verify your identity and that of your computer. The computer name is available on the macOS login window when you click Contact Admin.

  2. After your IT administrator has authenticated your identity and that of your device, your IT administrator can provide you with a PIN. This recovery PIN is only valid for two minutes. If the two minutes pass without successfully gaining access to your computer, you must have the IT administrator generate a new recovery PIN.

  3. Enter the PIN provided and confirm that you can access the computer. The PIN allows you to sign in to the computer for as long as the PIN is valid. Your IT administrator should tell you when the PIN expires. This information is necessary because when the PIN expires, a new device recovery PIN must be generated if you haven't located your Okta Verify enrolled MFA device or located another enrolled authenticator to use.

  4. Recover the Okta Verify enrolled MFA device as soon as possible or obtain a new MFA device to enroll in Okta Verify.

The device recovery PIN provided works for the configured duration. When the duration expires, contact IT and get a new time-limited device recovery PIN.

System Logs

System Logs are found at /var/log/com.okta.deviceaccess/OktaDeviceAccess.log. Alternatively, run the following command from an account with root or sudo access: sudo log collect --start "2023-09-18 12:00:00" --output /tmp && tar cvf system_logs.logarchive.tar /tmp/system_logs.logarchive.

The output is stored at /tmp/system_logs.logarchive.tar.

Resolve sign-in issues

Ensure that you meet the Prerequisites before you attempt to resolve Desktop MFA issues.

Reset Desktop MFA for all users

Copy and run the following commands from terminal to reset Desktop MFA for all users.

Copy 
sudo sqlite3 /Library/Application\ Support/com.okta.deviceaccess.servicedaemon/OktaDMFA "delete from enrollment"
sudo sqlite3 /Library/Application\ Support/com.okta.deviceaccess.servicedaemon/OktaDMFA "delete from factors"
sudo sqlite3 /Library/Application\ Support/com.okta.deviceaccess.servicedaemon/OktaDMFA "delete from loginhistory"

Delete an offline factor

If you need to remove an offline authentication factor for a user, use the command sudo sqlite3 /Library/Application\ Support/com.okta.deviceaccess.servicedaemon/OktaDMFA "delete from factors". Push the command to the user's macOS computer through your MDM to delete an offline factor.

Turn off the Authentication Plugin

If the machine is inaccessible and the end user has access to an admin account, they can sign in to the system using recovery mode. If you're in recovery mode as an administrator, you don't need to sudo.

  1. Unlock the disk: click Utilities Share Disk, and then click the hard disk.

  2. Select Unlock, and then enter the admin password.

  3. Click Share Disk, and then select Quit Share Disk.

  4. Open terminal and run the following command: rm -rf /Library/Security/SecurityAgentPlugins/OktaDAAuthPlugin.bundle/.

This command removes the Authorization Plugin from the machine, and the user should be able to sign in to the machine.

Remove Desktop MFA from a device

Run the following commands to fully remove Desktop MFA from a macOS device:

  • Remove the symlink to the Auth Plugin in macOS Okta Verify: sudo rm -rf /Library/Security/SecurityAgentPlugins/OktaDAAuthPlugin.bundle

  • Stop the Service Daemon: sudo launchctl unload /Library/LaunchDaemons/com.okta.deviceaccess.servicedaemon.plist

  • Remove the symlink to the Service Daemon's plist in macOS Okta Verify: sudo rm -f /Library/LaunchDaemons/com.okta.deviceaccess.servicedaemon.plist

  • Remove the symlink to the Service Daemon executable in macOS Okta Verify: sudo rm -f /usr/local/bin/OktaDAServiceDaemon

  • Remove the Desktop MFA directory: sudo rm -rf /Library/Application\ Support/com.okta.deviceaccess.servicedaemon/

  • Remove macOS Okta Verify, which removes the Auth Plugin, Service Daemon, and plists: sudo rm -rf "/Applications/Okta Verify.app"

Related topics

Okta Device Access Support Hub