Duo Authentication for Microsoft AD FS on Windows 2016 and later

Overview

Duo's 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 Workspace and salesforce.com.

This module supports AD FS application group OIDC/OAuth client applications with version 2.2.0 and later.

The AD FS application is part of Duo Premier, Duo Advantage, and Duo Essentials plans.

The Duo AD FS MFA adapter supports AD FS on Windows Server 2016 and later.

Deployment Overview

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 redirected to Duo for two-factor authentication 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.

Prerequisites

Check your server versions before starting. These instructions are for AD FS running on Windows Server 2016 or newer. It also requires the .NET Framework Framework 4.7.1 or later runtime installed on your AD FS server.

The URL for accessing AD FS must be a valid HTTPS URL and port, using an RFC-1034-compliant hostname (not an IP address), with a maximum length of 1024 characters.

First Steps

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.

1. Sign up for a Duo account.

2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

3. Locate the entry for Microsoft ADFS with the "2FA" label in the catalog. Click the + Add button to create the application and get your Client ID, Client secret, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications with Duo and additional application options.
   
   

   Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".

4. No users can log in to new applications until you grant access. Update the User access setting to grant access to this application to users in selected Duo groups, or to all users. Learn more about user access to applications. If you do not change this setting now, be sure to update it so that your test user has access before you test your setup.

5. Download the Duo AD FS Installer Package for Windows 2016 and later. View checksums for Duo downloads here.

Duo Universal Prompt

The Duo Universal Prompt provides a simplified and accessible Duo login experience for web-based applications, offering a redesigned visual interface with security and usability enhancements.

Universal Prompt	Traditional Prompt

For Microsoft ADFS applications created before March 2024, migration to Universal Prompt is a three-step process:

1. Install an update for the Microsoft ADFS application, which implements a redirect to Duo during authentication to support the Universal Prompt.
2. Authenticate with Duo 2FA using the updated application so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating shows the traditional Duo prompt in a redirect instead of an iframe.
3. From the Duo Admin Panel, activate the Universal Prompt experience for users of that Duo Microsoft ADFS application if the traditional prompt is still selected. Once activated, all users of the application see the Duo Universal Prompt in a redirect.

If you created your Microsoft ADFS application before March 2024, it's a good idea to read the Universal Prompt Update Guide for more information, about the update process and the new login experience for users, before you activate the Universal Prompt for your application.

New Microsoft ADFS Applications

When you install the latest version of Duo for AD FS you're ready to use the Universal Prompt. Microsoft ADFS applications created after March 2024 have the Universal Prompt activated by default. If you're configuring Microsoft ADFS now, proceed with the installation instructions in this document.

The "Universal Prompt" area of the application details page shows that this application is "Activation complete", with these activation control options:

• Show traditional prompt: Your users experience Duo's traditional prompt via redirect when logging in to this application.
• Show new Universal Prompt: (Default) Your users experience the Universal Prompt via redirect when logging in to this application.

Existing Microsoft ADFS Applications

Duo for AD FS needs a software update installed to support the Universal Prompt. The "Universal Prompt" section of your existing Microsoft ADFS application reflects this status as "Update required". To update Duo for AD FS application to a newer version, follow the update directions below.

Once a user authenticates to Duo for AD FS via the updated Duo plugin, the "Universal Prompt" section of the Microsoft ADFS application page reflects this status as "Ready to activate", with these activation control options:

• Show traditional prompt: (Default) Your users experience Duo's traditional prompt via redirect when logging in to this application.
• Show new Universal Prompt: Your users experience the Universal Prompt via redirect when logging in to this application.

In addition, the "Integration key" and "Secret key" property labels for the application update to "Client ID" and "Client secret" respectively. The values for these properties remain the same.

Activate Universal Prompt

Activation of the Universal Prompt is a per-application change. Activating it for one application does not change the login experience for your other Duo applications.

Enable the Universal Prompt experience by selecting Show new Universal Prompt, and then scrolling to the bottom of the page to click Save.

Once you activate the Universal Prompt, the application's Universal Prompt status shows "Activation Complete" here and on the Universal Prompt Update Progress report.

Should you ever want to roll back to the traditional prompt, you can return to this setting and change it back to Show traditional prompt. However, this will still deliver the Duo prompt via redirect, not in an iframe. Keep in mind that support for the traditional Duo prompt ended for the majority of applications in March 2024.

Universal Update Progress

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. You can also activate the new prompt experience for multiple supported applications from the report page instead of visiting the individual details pages for each application.

Deployment Tip

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.

Run the Installer

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.

1. Launch the Duo AD FS MSI installer as a user with local administrator privileges.

2. Enter your Client ID (formerly called the Integration key), Client secret (formerly called the 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 Duo for AD FS will "fail closed" when Duo Security cloud services are unreachable and users will not be able to access protected federated resources. Check the box if you want users to be able to access protected applications without Duo authentication if Duo's cloud service is unreachable. This setting can be changed post-install from the registry.

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

3. Complete the Duo installation.

If you have an AD FS farm, repeat the Duo installation steps on all farm members. All servers that share the same Duo AD FS application integration key/client ID should have the same version of the Duo AS FS adapter installed.

Configure AD FS Multi-factor Authentication

1. Launch the AD FS Management console on your primary AD FS internal server and navigate to AD FS → Service → Authentication Methods.

2. Click the Edit link under Multi-factor Authentication Methods or click Edit Multi-factor Authentication Methods... action on the far right.

   

   In AD FS 2019 and later, first make sure the Allow additional authentication providers as primary option on the "Primary" tab is not selected. If it is then your users will need to click on the ADFS page to begin primary authentication instead of being sent to primary AD FS login automatically.

3. On the "Additional" authentication methods tab, check the box next to the Duo Authentication for AD FS X.X.X authentication method (where X.X.X.X reflects the Duo version) to enable Duo protection. Click OK.

   

   In AD FS 2016 this tab is called "Multi-factor".

4. 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.

   

5. Go to AD FS → Application Groups or Relying Party Trusts.

   To apply MFA to an Application Group application, double-click the Application Group to view the applications in it. Double-click the application where you want to add Duo and go to the Access control policy tab.

   To apply MFA to a relying party, right-click the relying party trust where you want to add Duo, then select Edit Access Control Policy. Relying party example is shown in image.

   

6. Pick a policy for the application or relying party that includes MFA and then click OK until you return to the main AD FS management console window. The MFA policy immediately applies to the selected application or relying party.

   In this example, all users have access to this application or relying party, but members of the "Duo Users" domain group also require multi-factor authentication before accessing the application. In this example, all users have access to this relying party.

   

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 and Microsoft 365 Modern Authentication.

Pass an MFA Claim to Microsoft

If you federate Microsoft online services with AD FS you may want your AD FS server to pass an "Authentication Methods Reference" (AMR) claim back to Microsoft Online to show use of multifactor authentication by including the multipleauthn value after installing Duo for AD FS. This will satisfy Azure AD conditional access policies that require multifactor authentication.

To do this, you need to update your federation configuration for that domain to indicate support for multifactor authentication, and then create a custom claims rule in AD FS to send the AMR information.

1. Launch PowerShell on the server where you installed the Microsoft Graph PowerShell module, and run the following commands (the module prompts you to enter your Microsoft 365 or Azure admin credentials):

   Connect-MGGraph -Scopes "Domain.ReadWrite.All","Directory.AccessAsUser.All"
   Get-MgDomainFederationConfiguration -DomainId yourDomainName

2. Examine the command output and look for FederatedIdpMfaBehavior : enforceMfaByFederatedIdp. If you do not see this, then run this command to set it:

   Update-MgDomainFederationConfiguration -DomainId yourDomainName -InternalDomainFederationId InternalDomainFederationId -FederatedIdpMfaBehavior enforceMfaByFederatedIdp

3. In the AD FS Management console, navigate to Relying Party Trusts and locate the "Microsoft Office 365 Identity Platform" or "Microsoft Office 365 Identity Platform Worldwide" relying party.

4. Right click the "Microsoft Office 365 Identity Platform" or "Microsoft Office 365 Identity Platform Worldwide" relying party and click Edit Claim Issuance Policy.

5. On the "Issuance Transform Rules" tab, click Add Rule....

6. Select the Pass Through or Filter an Incoming Claim claim rule template and click Next.

7. Give your new claim rule a name, and then in the "Incoming claim type" field type in Authentication Methods References. Do not try to select this using the drop-down list, because the required value is not present. You must type it in exactly as shown.

   

   Leave the "Pass through all claim values" option selected and then click Finish to save your new claim rule and return to the list of issuance transform rules

8. Click OK to apply your new claim rule for Authentication Methods References to the 365 relying party.

When a user authenticates to Microsoft Online services through this AD FS server or farm with Duo installed, and completes Duo 2FA, this rule includes the multipleauthn claim for multifactor authentication in the response from AD FS.

Test Your Setup

To test your setup, use a web browser to log into a relying party for your AD FS deployment using the hostname or fully-qualified domain name URL. As an example, you might log into https://portal.microsoftonline.com to access Office 365.

1. Enter the primary username and password as usual.

   

2. The AD FS page briefly indicates that it's necessary to redirect you to Duo for authentication then performs the redirect.

   

3. Complete Duo two-factor authentication when prompted and then you'll return to AD FS to complete the login process to your relying party.

   

   *Universal Prompt experience shown.

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 365 Client Access

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.

Grant Access to Users

If you did not already grant user access to the Duo users you want to use this application be sure to do that before inviting or requiring them to log in with Duo.

Update Duo for AD FS

To upgrade the Duo AD FS plugin server, first disable the Duo Authentication for AD FS authentication method in the AD FS Management console.

1. Launch the AD FS Management console on your AD FS internal server.

2. Navigate to AD FS → Service → Authentication Methods and click the Edit Multi-factor Authentication Methods... action.

3. Uncheck the box next to the Duo Authentication for AD FS X.X.X authentication method on the "Additional" tab ("Multi-factor" in AD FS 2016) 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.

4. 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.

5. Follow the on-screen prompts to complete the upgrade installation.

6. 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 a farm or if you have used the same Duo AD FS application integration key/client ID across multiple servers, 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. Your users may experience issues completing Duo authentication if you do not update all Duo AD FS installations that use the same Duo AD FS application integration key/client ID at the same time.

If you are updating an existing Duo AD FS deployment to use the Universal Prompt, you will need to authenticate once with the traditional Duo Prompt using the updated Duo AD FS v2.x plugin first before you can enable the Universal Prompt for this AD FS application in Duo.

Duo Secret Rotation

If you need to reset the client secret for Duo for AD FS after installation try the Duo Secret Rotation tool.

Troubleshooting

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.

Walkthrough Video

Video shows Duo for AD FS v1.x installation experience. Please read this page in its entirety for the current v2.x installation instructions.

Network Diagram

1. AD FS connection initiated
2. Primary authentication to AD
3. AD FS connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. AD FS receives authentication response
6. AD FS session logged in