Configure Cisco Duo Security for MFA

Before you start

• Configure your Duo account. For more information, read Getting Started on Duo Docs.
• Create a Duo Security Web SDK integration and record the Integration Key, Secret Key, and API hostname credentials.

Cisco Duo is a multi-faceted authentication provider and can only be used on your Auth0 tenant if all other factors are disabled. Your Duo account can support push notifications, SMS, OTP, phone callback, and more based on your configuration.

You cannot also enable Duo if other factors are enabled. Duo is only available to users when it is the sole factor enabled.

The application will prompt the user for the second factor with Duo, listing the options you have enabled in your Duo account.

Your users can download Duo from Google Play or the App Store for use as a second factor.

Configure Duo

To configure Duo Security, you must pass your Duo credentials to your application in the Auth0 Dashboard.

1. Go to Dashboard > Security > Multi-factor Auth > Duo Security and enable it.
2. Enter the information in the fields to link your Duo account to Auth0.
3. Select Save.

Use Actions to enable Duo

To enable Duo within an Action, pass duo as the provider parameter when you enable multi-factor authentication.

exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('duo', { allowRememberBrowser: false });
};

Duo does not provide an option for “Remember Me” behavior. The 30-day MFA session is hard-coded to remember the user after the initial login.

To force your users to log in with Duo every time, create a rule with allowRememberBrowser: false.

Actions template for Duo

This template provides an example and starting point to trigger multi-factor authentication with Duo Security when a condition is met.

Upon first login, the user can enroll the device.

You need to create two integrations in Duo Security: one of type Web SDK and one of type Admin SDK.

exports.onExecutePostLogin = async (event, api) => {

	const CLIENTS_WITH_MFA = ['{yourClientId}'];
	// run only for the specified clients
	if (CLIENTS_WITH_MFA.includes(event.client.client_id)) {

		// uncomment the following if clause in case you want to request a second factor only from user's that have user_metadata.use_mfa === true
		//if (event.user.user_metadata && event.user.user_metadata.use_mfa){

		// optional, defaults to true. Set to false to force DuoSecurity every time.
		// See https://auth0.com/docs/multifactor-authentication/custom#change-the-frequency-of-authentication-requests for details
		api.multifactor.enable('duo', {
			providerOptions.ikey: configuration.DUO_IKEY,
			providerOptions.skey: configuration.DUO_SKEY,
			providerOptions.host: configuration.DUO_HOST,
			allowRememberBrowser: false
		})

		// optional. Use some attribute of the profile as the username in DuoSecurity. This is also useful if you already have your users enrolled in Duo.
		// username: event.user.nickname
	};
	// }

};

Current limitations

• You cannot use Auth0 MFA Enrollment Tickets to enroll users with Duo. Onboard those users from Duo itself.
• If you use Universal Login, you must enable Duo in an Action with provider set to duo as described previously. You can conditionally use Duo or the built-in Auth0 provider for specific applications.

Learn more

• Troubleshoot Multi-Factor Authentication Issues