Duo for AD FS - Frequently Asked Questions
If you installed version 1.1.x.x of Duo's MFA adapter for AD FS, make sure that you installed Duo from an administrator command prompt (right-click “Command Prompt” and select “Run as Administrator”). Simply double-clicking the 1.1.x.x MSI installer may not use the correct privilege elevation, even if you are logged in with administrator rights.
This issue was first corrected in version 1.2.0.17. Please install the most recent release of Duo's AD FS adapter.
For AD FS 2.1, simply open the Programs and Features Control Panel applet, select the Duo Security AD FS integration, and uninstall.
To upgrade Duo on an AD FS 3.0+ server, it is necessary to disable the Duo Security for AD FS authentication method in the AD FS Management console first.
Navigate to AD FS → Authentication Policies and click the Edit Global Multi-factor Authentication... action (AD FS 3) or AD FS → Service → Authentication Methods and click the Edit Multi-factor Authentication Methods... action (AD FS 4).
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.
If you configured multi-factor authentication at the individual Relying Party level, remove the MFA requirements for those Relying Parties as well.
Apply the multi-factor authentication policy change, and then proceed to the Programs and Features Control Panel applet, select the Duo Security AD FS integration, and uninstall.
If the "Bypass Duo authentication when offline" box is selected during installation, authentication attempts will fail open after primary authentication is successful if the Duo service cannot be contacted. This setting is controlled by a Registry DWORD value FailOpen
set to 1.
AD FS Version | Registry Path |
---|---|
AD FS 2.1 | HKLM\SOFTWARE\Duo Security\DuoIis\FailOpen |
AD FS 3.0+ | HKLM\Software\Duo Security\DuoAdfs\FailOpen |
You can set the fail mode during installation to "fail closed" by deselecting the "Bypass Duo authentication when offline" box in the Duo installer, or modify the setting after installation by changing the Duo registry DWORD FailOpen
value from 1 to 0 to "fail closed." This will deny all login attempts to federated resources if there is a problem contacting the Duo service.
The Duo event log for the AD FS integration is under the "Applications and Services Logs" node in the Windows Event Viewer.
To turn on debug logging, create a registry REG_DWORD value Debug
set to 1.
AD FS Version | Registry Path |
---|---|
AD FS 2.1 | HKLM\Software\Duo Security\DuoIis\Debug |
AD FS 3 & 4 | HKLM\Software\Duo Security\DuoAdfs\Debug |
After creating the debug DWORD value, cycle the appropriate service:
Duo's AD FS adapter sends a user's sAMAccountName to Duo as the Duo username by default. You can change the username format sent to Duo to userPrincipalName (UPN) starting with version 1.2.0.17.
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, or Duo will drop the domain suffix from the username sent from AD FS to our service, which may cause user mismatches or duplicate enrollment.
Choose to send userPrincipalName usernames to Duo during installation by selecting the "Use UPN username format" box in the Duo installer.
Changing this setting after Duo adapter installation requires creating a new registry value and re-registering the Duo adapter using PowerShell.
1.2.0.17
).Unregister-AdfsAuthenticationProvider DuoAdfsAdapter
at the PowerShell prompt. If asked to confirm the action type Y
for "Yes".Restart-Service adfssrv
at the PowerShell prompt.Launch the Registry Editor (regedit.exe) from the elevated PowerShell prompt and navigate to HKLM\Software\Duo Security\DuoAdfs
.
Create or update the REG_DWORD value UseUpnUsername
to set it to 1 to enable UPN username format.
Alternatively, you can enter the command reg add "HKLM\Software\Duo Security\DuoAdfs" /v UseUpnUsername /t REG_DWORD /d 1 /f
in PowerShell to create or update the registry value.
Register-AdfsAuthenticationProvider -TypeName "Duo.DuoAdfsAdapter, DuoAdfsAdapter, Version=X.X.X.X, Culture=neutral, PublicKeyToken=cac53dcfadb30b87" -Name "DuoAdfsAdapter" -Verbose
, where X.X.X.X
is the Duo MFA adapter version you noted in step 1 (e.g. 1.2.0.17
).Restart-Service adfssrv
.Example showing all PowerShell steps:
PS C:\Users\administrator> Unregister-AdfsAuthenticationProvider DuoAdfsAdapter
Confirm
Are you sure you want to perform this action?
Performing the operation "PS0061: Remove external authentication provider: 'DuoAdfsAdapter'." on target
"DuoAdfsAdapter".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y
WARNING: PS0103: The authentication provider was successfully unregistered from the policy store. Restart the AD FS
Windows Service on each server in the farm.
PS C:\Users\administrator> Restart-Service adfssrv
WARNING: Waiting for service 'Active Directory Federation Services (adfssrv)' to start...
WARNING: Waiting for service 'Active Directory Federation Services (adfssrv)' to start...
PS C:\Users\administrator> reg add "HKLM\Software\Duo Security\DuoAdfs" /v UseUpnUsername /t REG_DWORD /d 1 /f
The operation completed successfully.
PS C:\Users\administrator> Register-AdfsAuthenticationProvider -TypeName "Duo.DuoAdfsAdapter, DuoAdfsAdapter,
Version=1.2.0.17, Culture=neutral, PublicKeyToken=cac53dcfadb30b87" -Name "DuoAdfsAdapter" -Verbose
WARNING: PS0114: The authentication provider was successfully registered with the policy store. To enable this
provider, you must restart the AD FS Windows Service on each server in the farm.
PS C:\Users\administrator> Restart-Service adfssrv
WARNING: Waiting for service 'Active Directory Federation Services (adfssrv)' to start...
WARNING: Waiting for service 'Active Directory Federation Services (adfssrv)' to start...
PS C:\Users\administrator>
The inline Duo Prompt is blocked by the AD FS 2019 default Content Security Policy. 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'; frame-src api-xxxxxxxx.duosecurity.com"
Office 2013 and 2016 desktop applications (including Outlook and Skype for Business) by default can no longer connect to Office 365 after installing the Duo ADFS integration. Office 365 customers must enable Microsoft's Modern Authentication to bring two-factor authentication to Office 2013 and 2016 client applications (or construct MFA rules that exclude Office applications). More information about Modern Authentication, including a list of Office applications that support Modern Authentication, is available at the Office Blog.
When you log in to Office 365 using an Office 2016 or 2013 application with Modern Authentication, you'll see the AD FS primary login page within the Office application, followed by the Duo authentication prompt.
For additional information please see the "Road map for multi-factor authentication in Office desktop applications" section in this blog post from Microsoft: Multi-Factor Authentication for Office 365 and the previous blog entries Office 2013 updated authentication enabling Multi-Factor Authentication and SAML identity providers and Office 2013 modern authentication public preview announced.
Duo does not natively support the creation of application specific passwords for bypassing multi-factor authentication for Office 365 tenants.
If you need to enforce more complex MFA rules for an Office 365 relying party to include or exclude certain clients, groups, or networks, please take a look at our Guide to advanced client configuration for Duo with AD FS 3 and later with Office 365 Modern Authentication.
When using Duo with AD FS 2.1, the assertion must contain a SAML 2.0 NameId or a WS-Federation (AD FS 1.1 compatible) UserPrincipalName, WindowsAccountName, or EmailAddress. Additionally, the SAML assertion must not be encrypted.
You may receive the error "An authentication provider with identifier 'DuoAdfsAdapter' is already present in the policy store. Identifiers must be unique." when attempting to install Duo Authentication for AD FS 3 version 1.1.0 or later on additional SQL farm members.
This issue was corrected in version 1.2.0.17. Please install the most recent release of Duo's AD FS adapter.
The AD FS server does not need to be externally accessible from the Internet if you are using a AD FS Proxy, but the Duo AD FS integration installed on the server does require access to the Duo cloud service over the Internet. Without Internet access users may experience delays, timeouts, or failures to authenticate Duo after submitting their primary login credentials.
No additional actions are required to enable the Duo Security integration. Do not click the “Enable Duo Security Authentication Module” button.
Need more help? Try searching our AD FS Knowledge Base articles or Community discussions. For further assistance, contact Support.