Configure and deploy Desktop MFA policies for macOS

Configure Desktop MFA behavior and deploy managed profiles to your macOS computers.

You can use any device management (MDM) solution that supports deploying macOS installer packages and configuration profiles. These instructions assume the use of Jamf Pro for device management.

When you deploy the Desktop MFA MDM profiles, ensure that they've been successfully pushed to devices before deploying the macOS Okta Verify package. If the MDM profile doesn't exist on the user's device when the package installer runs, Desktop MFA isn't installed.

Tasks

Upload the Okta Verify for macOS package
Configure the installation of Desktop MFA for macOS
Add Desktop MFA policies

Upload the Okta Verify for macOS package

Take the Okta Verify for macOS package that you downloaded from the Okta Admin Console and upload it to your MDM solution.
In Jamf Pro, go to Settings > Computer management > Packages.
Click + New to configure the package details.

Configure the installation of Desktop MFA for macOS

In Jamf Pro, click Computers > Policies and click + New.
Enter a Display Name and select Login for the policy Trigger.
Click Packages and then click Configure.
Locate the Okta Verify package that you uploaded in the previous step and click Add next to the package.
Configure the Distribution point.
Using the dropdown menu, select Install as the Action.
Click Save.

Ensure that the MDM profile has been successfully deployed to end user devices before deploying the macOS Okta Verify package.

Add Desktop MFA policies

In Jamf Pro, click Configuration Profiles and then click + New.
Enter a name for the profile.
Click Application & Custom Settings to configure the payload. Click Upload.
Click + Add.
Enter com.okta.deviceaccess.servicedaemon as the Preference Domain.

Add the values for your organization as a plist file. Here's an example plist file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>DMFAClientID</key>
    <string>add-your-client-ID-here</string>
    <key>DMFAClientSecret</key>
    <string>add-your-client-secret-here</string>
    <key>DMFAOrgURL</key>
    <string>https://add-your-org-URL-with-prefix-here</string>
    <key>AccountLinkingMFAFactor</key>
    <string>OV_Push</string>
    <key>AdminEmail</key>
    <string>admin@yourorg.com</string>
    <key>AdminPhone</key>
    <string>111-222-3333</string>
    <key>AllowedFactors</key>
    <array>
        <string>*</string>
    </array>
    <key>DeviceRecoveryPINDuration</key>
    <real>60</real>
    <key>DeviceRecoveryValidityInDays</key>
    <real>90</real>
    <key>LoginPeriodWithoutEnrolledFactor</key>
    <real>48</real>
    <key>LoginPeriodWithOfflineFactor</key>
    <real>168</real>
    <key>MFANotRequiredList</key>
    <array/>
    <key>MFARequiredList</key>
    <array>
        <string>*</string>
    </array>
    <key>OfflineLoginAllowed</key>
    <true/>
</dict>
</plist>

Policy parameters

Use the following table to configure the appropriate parameters for your Desktop MFA policies.

Parameter	Description
Name: `AccountLinkingMFAFactor` Type: `String` Default: `OV_Push`	The verification method that you want to use when linking an Okta account to the local macOS account. Possible values for this setting: `OV_Push`: Okta Verify push notification. `OV_TOTP`: Okta Verify Time-based one-time password. `FIDO2_USB_key`: Use a FIDO2 authenticator.
Name:`AdminEmail` Type: `String` Default: Empty	Enter an email address for end users to get support. This value is empty by default.
Name: `AdminPhone` Type: `String` Default: Empty	Enter a phone number for end users to get support. This value is empty by default.
Name: `AllowedFactors` Type: `String array`	List of factors that users can authenticate with. The allowed factors appear in the order that they're listed in your configurations. Possible values for this setting: `*`: all factors are allowed. `OV_Push` `OV_TOTP` `Offline_TOTP` `FIDO2_USB_key` If you don't specify any factors, then all factors are allowed. Ensure that the factors are spelled correctly.
Name: `DeviceRecoveryPINDuration` Type: `Real` Default: `60`	Valid time period for a device recovery PIN after activation. The value is in minutes. The maximum value is `7200` (five days). See Enable Desktop MFA recovery for macOS.
Name: `DeviceRecoveryValidityInDays` Type: `Real` Default: `90`	Duration of the device recovery window for Desktop MFA. To successfully authenticate with a recovery PIN, the user must sign in to the device with Desktop MFA while online at least once during the specified period. For example, this value is set at `120`. A user hasn't been online and hasn't signed in with Desktop MFA for over 120 days. This means that they can't use a recovery PIN even if the PIN is still valid. The user is locked out and you can't generate a recovery PIN. When the device comes back online, you can generate a recovery PIN that the user can sign in with. The value is in days.
Name: `LoginPeriodWithoutEnrolledFactor` Type: `Real` Default: `48`	Specifies a grace period when a user can sign in with only a password and without enrolling any factors. After this grace period expires, the user must link their account and enroll an offline authentication factor to access the computer. The value is in hours.
Name: `LoginPeriodWithOfflineFactor` Type: `Real` Default: `168`	If this is set to `0`, a user can't sign in with offline factors. If the value of `LoginPeriodWithoutEnrolledFactor` is greater than `0`, then users are required to sign in with an online factor every `X` hours. The value is in hours.
Name: `MFANotRequiredList` Type: `String array` Default: Empty	Users listed in this array aren't Desktop MFA enforced. This list takes priority over the `MFARequiredList` array. Accounts listed here are case-sensitive.
Name: `MFARequiredList` Type: `String array` Default: `*`	If a user is on this list and Desktop MFA is installed, the user is prompted to use MFA. However, some users with Desktop MFA installed may not be required to use MFA. If a user isn't on this list and Desktop MFA is installed, the user is only prompted for a password. The default value is `*`, meaning that MFA applies for all users. Accounts listed here are case-sensitive. For example, if the local user `john-smith` is named in the `MFARequiredList` array, they must use MFA.
Name: `OfflineLoginAllowed` Type: `Boolean` Default: `true`	When this is set to `true`, offline factors are shown to the user. This allows the user to enroll an offline authentication factor. When this is set to `false`, offline factors aren't shown and there's no enforcement of offline factors. If you change this policy to `true` and the `LoginPeriodWithoutEnrolledFactor` period has expired, then users are forced to enroll an offline factor.

Parameter

Description

Name: AccountLinkingMFAFactor

Type: String

Default: OV_Push

The verification method that you want to use when linking an Okta account to the local macOS account.

Possible values for this setting:

OV_Push: Okta Verify push notification.
OV_TOTP: Okta Verify Time-based one-time password.
FIDO2_USB_key: Use a FIDO2 authenticator.

Name:AdminEmail

Type: String

Default: Empty

Enter an email address for end users to get support.

This value is empty by default.

Name: AdminPhone

Type: String

Default: Empty

Enter a phone number for end users to get support.

This value is empty by default.

Name: AllowedFactors

Type: String array

List of factors that users can authenticate with.

The allowed factors appear in the order that they're listed in your configurations.

Possible values for this setting:

*: all factors are allowed.
OV_Push
OV_TOTP
Offline_TOTP
FIDO2_USB_key
If you don't specify any factors, then all factors are allowed.

Ensure that the factors are spelled correctly.

Name: DeviceRecoveryPINDuration

Type: Real

Default: 60

Valid time period for a device recovery PIN after activation.

The value is in minutes. The maximum value is 7200 (five days).

See Enable Desktop MFA recovery for macOS.

Name: DeviceRecoveryValidityInDays

Type: Real

Default: 90

Duration of the device recovery window for Desktop MFA.

To successfully authenticate with a recovery PIN, the user must sign in to the device with Desktop MFA while online at least once during the specified period.

For example, this value is set at 120. A user hasn't been online and hasn't signed in with Desktop MFA for over 120 days. This means that they can't use a recovery PIN even if the PIN is still valid. The user is locked out and you can't generate a recovery PIN. When the device comes back online, you can generate a recovery PIN that the user can sign in with.

The value is in days.

Name: LoginPeriodWithoutEnrolledFactor

Type: Real

Default: 48

Specifies a grace period when a user can sign in with only a password and without enrolling any factors.

After this grace period expires, the user must link their account and enroll an offline authentication factor to access the computer.

The value is in hours.

Name: LoginPeriodWithOfflineFactor

Type: Real

Default: 168

If this is set to 0, a user can't sign in with offline factors.

If the value of LoginPeriodWithoutEnrolledFactor is greater than 0, then users are required to sign in with an online factor every X hours.

The value is in hours.

Name: MFANotRequiredList

Type: String array

Default: Empty

Users listed in this array aren't Desktop MFA enforced.

This list takes priority over the MFARequiredList array. Accounts listed here are case-sensitive.

Name: MFARequiredList

Type: String array

Default: *

If a user is on this list and Desktop MFA is installed, the user is prompted to use MFA.

However, some users with Desktop MFA installed may not be required to use MFA. If a user isn't on this list and Desktop MFA is installed, the user is only prompted for a password.

The default value is *, meaning that MFA applies for all users.

Accounts listed here are case-sensitive.

For example, if the local user john-smith is named in the MFARequiredList array, they must use MFA.

Name: OfflineLoginAllowed

Type: Boolean

Default: true

When this is set to true, offline factors are shown to the user. This allows the user to enroll an offline authentication factor.

When this is set to false, offline factors aren't shown and there's no enforcement of offline factors.

If you change this policy to true and the LoginPeriodWithoutEnrolledFactor period has expired, then users are forced to enroll an offline factor.

Next steps

Enforce number challenge for Desktop MFA for macOS

Configure Desktop MFA for macOS to use FIDO2 keys

Enable Desktop MFA recovery for macOS

Support your macOS Desktop MFA users