Duo integrates with Microsoft AD FS v3 and later to add two-factor authentication to services using browser-based federated logins, complete with inline self-service enrollment and Duo Prompt.
The Duo AD FS module supports relying parties that use Microsoft's WS-Federation protocol, like Office 365, as well as SAML 2.0 federated logons for cloud apps like Google G Suite and salesforce.com.
The AD FS application is part of Duo Beyond, Duo Access, and Duo MFA plans.
The Duo AD FS MFA adapter supports AD FS on Windows Server 2012 R2, 2016, and 2019. To protect AD FS on Windows Server 2012, use the AD FS 2.1 integration.
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.
Before moving on to the deployment steps, it's a good idea to familiarize yourself with Duo administration concepts and features like options for applications, available methods for enrolling Duo users, and Duo policy settings and how to apply them. See all Duo Administrator documentation.
Also verify that federated logins to your relying parties are working prior to installing Duo.
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!
Duo's next-generation authentication experience, the Universal Prompt, is coming to web-based applications that display the current Duo Prompt in browsers.
Migration to Universal Prompt for your Microsoft ADFS application is a two-step process:
You'll need to update Microsoft ADFS to support the Universal Prompt when it's ready, but the update isn't available yet. The "Universal Prompt" section reflects this status as "Waiting on App Provider". Please contact Duo Support to request Universal Prompt support for Microsoft ADFS.
In the meantime, you can use Duo with Microsoft ADFS and the current Duo prompt experience.
After Duo makes the necessary software update software update available and you've installed it, you'll later return to the settings on this page to activate the Universal Prompt for your Microsoft ADFS users once we've released it.
Click the See Update Progress link to view the Universal Prompt Update Progress report. This report shows the update availability and migration progress for all your Duo applications in-scope for Universal Prompt support.
Read the Universal Prompt Update Guide for more information about the update process to support the new prompt, and watch the Duo Blog for future updates about the Duo Universal Prompt.
This integration adds a pluggable multi-factor (MFA) authentication provider that provides a Duo two-factor authentication prompt to web-based logins through an AD FS Identity Provider and/or Web Application Proxy. After completing primary authentication to the AD FS server (by any standard means such as Windows Integrated or Forms-Based), your users will be required to complete a Duo authentication challenge before getting redirected back to the relying party.
Install the Duo integration on the internal AD FS identity provider server only. In an AD FS farm deployment install Duo on all identity provider AD FS servers in the farm.
When configuring the multi-factor authentication policies after the Duo installation on the internal AD FS server you select whether to require MFA on Internal or External access locations (or both). If you are planning to require two-factor authentication for External access locations, a Web Application Proxy server is required. You do not need to install the Duo AD FS integration on the Web Application Proxy server.
The Duo MFA adapter has been tested with basic ADFS web theme customizations, but more extensive advanced customization of the login pages may cause issues. We recommend verifying Duo MFA functionality at AD FS login with a basic theme first, then reapplying the custom theme.
Set your application's New User Policy to "Allow Access" while testing. Enrolled users must complete two-factor authentication, while all other users are transparently let through.
Then (when you're ready) change the "New user policy" to "Require Enrollment." This will prompt all users to authenticate (or enroll) after they type in their usernames and passwords.
If you have deployed AD FS as a WID farm, install Duo on the primary server first. If you have a SQL farm, you may begin with any node.
Launch the Duo AD FS MSI installer as a user with local administrator privileges.
Enter your integration key, secret key, and API hostname from the Duo Security AD FS application page when prompted.
If the Bypass Duo authentication when offline option is unchecked, then users will not be able to log in to protected federated resources when Duo Security cloud services are unreachable.
The Duo MFA adapter sends a user's Windows sAMAccountName to Duo's service by default. To send the userPrincipalName to Duo instead, check the Use UPN username format box.
If you enable this option, you must also change the properties of your AD FS application in the Duo Admin Panel to change the "Username normalization" setting to None. Otherwise, Duo drops the domain suffix from the username sent from AD FS to our service, which may cause user mismatches or duplicate enrollment.
If you only have one AD FS server running, select the option to automatically generate a new key. However, if you are running multiple AD FS servers in a farm, then you should manually generate a random string at least 40 characters long, and use the same string as the session key during installation on each of the servers.
For example, you could use the following PowerShell commands to generate a suitable session key:
$bytes = new-object "System.Byte[]" 30
(new-object System.Security.Cryptography.RNGCryptoServiceProvider).GetBytes($bytes)
[Convert]::ToBase64String($bytes)
Complete the Duo installation.
If you're installing Duo for AD FS on Server 2019, run the following PowerShell command to permit display of the Duo Prompt, replacing api-xxxxxxxx.duosecurity.com with your actual Duo API hostname:
Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' data:; frame-src api-XXXXXXX.duosecurity.com"
If you have an AD FS farm, repeat the Duo installation steps on all farm members.
Launch the AD FS Management console on your primary AD FS internal server. Navigate to AD FS → Authentication Policies and click the Edit Global Multi-factor Authentication... action, or click on the Edit link under Multi-factor Authentication → Global Settings.
On the "Multi-factor (MFA)"" tab of the "Edit Global Authentication Policy" you can choose to assign a domain group for MFA using the Add... button.
Alternatively, after determining what types of connections will be required to use MFA check the boxes for Extranet and/or Intranet. For example, if you want to always require two-factor authentication for all of your users, select both the Extranet and Intranet location when configuring the multi-factor authentication policy and don't specify a group assignment for MFA (as shown in the example).
If you only want to enforce two-factor authentication for external users (in any group), and you have configured your network such that external users communicate with an AD FS Web Application Proxy while internal users communicate with the Identity Provider, do not add any groups for MFA and only enable the Extranet location in the multi-factor authentication policy and leave the Intranet location unchecked.
Note that any MFA assignments made via the Global Authentication Policy editor are effectively "OR" rules, so each individual condition always applies. If you were to add a specific group (like ACME\Duo_Users) to the Users/Groups section, and then also check the box for the Extranet location, you may expect that the net effect is that members of the ACME\Duo_Users who access AD FS externally require MFA while members of that group accessing AD FS internally and any user who is not a member of that group do not require MFA. Since the GUI creates "OR" rules instead of "AND" rules the net effect is actually that members of ACME\Duo_Users always require MFA regardless of location, while users not in the ACME\Duo_Users group accessing AD FS externally also require MFA.
In an advanced multi-factor scenario, you can choose Intranet and/or Extranet location requirements on a per user or per relying party basis. Refer to the Microsoft article Overview: Manage Risk with Additional Multi-Factor Authentication for Sensitive Applications for more information.
Check the box next to the Duo Authentication for AD FS X.X.X.X authentication method (where X.X.X.X reflects the actual installed Duo version) to enable Duo protection.
If you need to enforce more complex MFA rules for an Office 365 relying party (bypass or require policies for certain clients, users, or subnets), please take a look at our Guide to advanced client configuration for Duo with AD FS 3 and later with Office 365 Modern Authentication
Launch the AD FS Management console on your primary AD FS internal server and navigate to AD FS → Service → Authentication Methods.
Click the Edit link under Multi-factor Authentication Methods or click Edit Multi-factor Authentication Methods... action on the far right.
Check the box next to the Duo Authentication for AD FS X.X.X.X authentication method (where X.X.X.X reflects the Duo version) to enable Duo protection. Click OK.
Go to AD FS → Access Control Policies and either edit one of the existing MFA policies to apply it to users or groups, or create a new MFA policy if no pre-defined one is sufficient for your organization's MFA requirements.
Go to AD FS → Relying Party Trusts , right-click the relying party trust where you want to add Duo, then select Edit Access Control Policy.
Pick a policy for the relying party that includes MFA and then click OK. The MFA policy immediately applies to the selected relying party.
In this example, all users have access to this relying party, but members of the "Duo Users" domain group also require multi-factor authentication before accessing the application.
In an advanced multi-factor scenario, you can choose Intranet and/or Extranet location requirements, along with other conditions for access. Refer to the Microsoft article Access Control Policies in Windows Server 2016 AD FS for more information.
If you need to enforce more complex MFA rules for an Office 365 relying party, please take a look at our Guide to advanced client configuration for Duo with AD FS 3 and later with Office 365 Modern Authentication.
To test your setup, use a web browser to log into a relying party for your AD FS deployment. As an example, you might log into https://portal.microsoftonline.com to access Office 365. Duo's enrollment or login prompt appears after you complete primary authentication to your AD FS server:
If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID), Duo recommends enabling hostname whitelisting for this application and any others that show the inline Duo Prompt before onboarding your end-users.
Visit our guides to protecting popular cloud applications like Google G Suite and Office 365 with Duo's powerful two-factor authentication for AD FS.
Office 2013 and 2016 desktop applications (including Outlook and Skype for Business) can connect to Office 365 after Duo AD FS adapter installation only if Modern Authentication is enabled for your Office 365 tenant (or you've constructed your MFA rules to exclude Office client applications). More information about Modern Authentication, including a list of Office applications that support Modern Authentication, is available at the Office Blog.
To upgrade the Duo AD FS plugin server, first disable the Duo Authentication for AD FS authentication method in the AD FS Management console.
Launch the AD FS Management console on your AD FS internal server.
Navigate to AD FS → Authentication Policies and click the Edit Global Multi-factor Authentication... action (AD FS 2012 R2) or AD FS → Service → Authentication Methods and click the Edit Multi-factor Authentication Methods... action (AD FS 2016+).
Uncheck the box next to the Duo Authentication for AD FS X.X.X.X authentication method to disable Duo protection. Note that in older releases of Duo for AD FS the authentication method is called Duo Security for AD FS 3.0.
Download the most recent Duo AD FS Installer Package for AD FS and run the MSI from an elevated command prompt. View checksums for Duo downloads here.
Follow the on-screen prompts to complete the upgrade installation.
When the installer is finished, repeat the steps you originally followed to enable the Duo method in AD FS. Users may log on to federated services without two-factor protection until you've re-enabled the Duo authentication method.
If you have deployed AD FS as farm, you'll need to upgrade Duo on each of your servers. For a WID farm, install Duo on the primary server first. If you have a SQL farm, you may begin with any node.
Need some help? Take a look at the AD FS Frequently Asked Questions (FAQ) page or try searching our AD FS Knowledge Base articles or Community discussions. For further assistance, contact Support.
