Duo Access Gateway will reach end of life in October 2023. Customers may not create new DAG applications after May 19, 2022. Please see the Guide to Duo Access Gateway end of life for more details.
Duo Access Gateway (DAG), our on-premises single sign-on product, layers Duo's strong authentication and flexible policy engine on top of Microsoft 365 logins using the Security Assertion Markup Language (SAML) 2.0 authentication standard. Duo Access Gateway acts as an identity provider (IdP), authenticating your users using existing on-premises Active Directory (AD) credentials and prompting for two-factor authentication before permitting access to Microsoft 365.
Once you federate a custom domain your Microsoft Online tenant with Duo Access Gateway, all Microsoft 365 applications will redirect those federated users to Duo Access Gateway when they sign in, while cloud-only (non-federated) users continue to log in using the Microsoft online sign-in form.
Be aware that Duo Access Gateway does not support WS-Trust. If you have clients that rely on WS-Trust, like Azure-joined workstations, deploy Duo Single Sign-On for Microsoft 365 instead. Duo Single Sign-On for Microsoft 365 supports WS-Trust.
Duo Access Gateway is part of the Duo Beyond, Duo Access, and Duo MFA plans, which also include the ability to define policies that enforce unique controls for each individual SSO application. For example, you can require that Salesforce users complete two-factor authentication at every login, but only once every seven days when accessing Microsoft 365. Duo checks the user, device, and network against an application's policy before allowing access to the application.
If you'd like to explore Duo solutions for Microsoft 365 that do not require deploying an on-premises SAML IdP, see our instructions for Duo for Azure Active Directory Conditional Access or Duo Single Sign-On for Microsoft 365.
Install Duo Access Gateway on a server in your DMZ. Follow our instructions for deploying the server and configuring DAG settings.
Include the AD attributes mail,sAMAccountName,userPrincipalName,objectGUID in the “Attributes” field when configuring the Active Directory authentication source in the DAG admin console. You must use Active Directory as your authentication source; other DAG authentication sources do not support Microsoft 365 logins.
If you've already configured the attributes list for another cloud service provider, append the additional attributes not already present to the list, separated by a comma.
After completing the initial DAG configuration steps, click Applications on the left side of the Duo Access Gateway admin console.
Scroll down the Applications page to the Metadata section. This is the information you need to provide to Microsoft 365 when configuring SSO. Click the Download Certificate link to obtain the token signing certificate (the downloaded file is named "dag.crt").
Log on to the Duo Admin Panel and navigate to Applications.
Click Protect an Application and locate the entry for Microsoft 365 with a protection type of "2FA with SSO self-hosted (Duo Access Gateway)" in the applications list. Click Protect to the far-right to start configuring Microsoft 365. See Protecting Applications for more information about protecting applications in Duo and additional application options.
You can optionally check the box next to Enable Basic Auth to allow legacy mail clients that do not support Modern Auth to still log in using only their AD username and password. When this option is configured users logging in with legacy mail clients will bypass Duo 2FA. If this option is not chosen any mail client that does not support Modern Auth will not be able to log in.
When Microsoft sends a basic authentication request to the Duo Access Gateway it will only send the username preceding the domain name. For example, if the email address is
email@example.com, only "alice" will be sent. This means that the Duo Access Gateway must be configured with a "Search attribute" on the Authentication Sources page which maps to an AD source attribute that is an exact match for the username segment of the user's email address preceding the
The user's status in Duo and the effective enrollment policy of the Microsoft 365 application will be checked against Duo before authentication completes. If the effective New User policy for the Microsoft 365 Duo application is one that enforces enrollment (like "Require enrollment" or "Deny Access"), then any user logging in with basic authentication must exist in Duo with a 2FA device even though 2FA approval isn't required during M365 basic authentication.
Ensure that users logging in with basic authentication through Duo are not also required to complete Azure MFA. If a policy applied to the basic auth users enforces Azure MFA, basic auth through the Duo Access Gateway fails, preventing mailbox access.
Important: If you are currently using Microsoft 365 with the Duo Access Gateway and federated your Microsoft tenant before August 2017 please follow the steps in this KB article to revert your tenant back to managed and then federate your Microsoft tenant with an updated configuration.
If you checked Enable Basic Auth you can optionally check the box next to Basic Auth groups which will let you specify Duo groups; this option will allow basic auth for only members of those groups.
Microsoft 365 uses the Mail attribute and Object-GUID attribute when authenticating. We've mapped Mail attribute and Object-GUID attribute to DAG supported authentication source attributes as follows:
|Duo Attribute||Active Directory|
If you are using non-standard Mail or Object-GUID attributes for your authentication source, check the Custom attributes box and enter the name of the AD attributes you wish to use instead.
Click Save Configuration to generate a downloadable configuration file.
You can adjust additional settings for your new SAML application at this time — like changing the application's name from the default value, enabling self-service, or assigning a group policy — or come back and change the application's policies and settings after you finish SSO setup. If you do update any settings, click the Save Changes button when done.
Click the Download your configuration file link to obtain the Microsoft 365 application settings (as a JSON file).
Important: This file contains information that uniquely identifies this application to Duo. Secure this file as you would any other sensitive or password information. Don't share it with unauthorized individuals or email it to anyone under any circumstances!
Before you do this, verify that you updated the "Attributes" list for your Duo Access Gateway AD authentication source as specified here.
Return to the Applications page of the DAG admin console session.
Click the Choose File button in the "Add Application" section of the page and locate the Microsoft 365 SAML application JSON file you downloaded from the Duo Admin Panel earlier. Click the Upload button after selecting the JSON configuration file.
The Microsoft 365 SAML application is added.
In order to federate your Microsoft 365 tenant with an external identity provider (like Duo Access Gateway) you must have added a custom domain to Microsoft 365. You cannot federate your "onmicrosoft.com" domain. Additionally, the custom domain you have added to Microsoft 365 cannot be set as the default domain.
We recommend that you have a tenant administrator account in your "onmicrosoft.com" so you don't lock yourself out of your tenant.
If you previously configured directory synchronization between your on-premises AD domain and Microsoft 365, skip these steps and proceed to Enable AD Federation to Microsoft 365 using DAG.
Log in to the Office Admin portal as the tenant administrator and open the Sync users from your Windows Server Active Directory setup action. Click Get Started to begin setup and step through the guided prompts.
On a computer joined to your AD domain open PowerShell and run
Install-Module MSOnline as described here under Step 1, substep 2. to install the Microsoft Azure Active Directory Module for Windows PowerShell.
When prompted to download and run Azure AD Connect, do not use the "Express Settings" and instead select Customize to perform a Custom installation of Azure Active Directory Connect.
When on the "User sign-in" page of the Microsoft Azure Active Directory Connect tool select Do not configure as the "Sign On method". When on the "Identifying Users" page select objectGUID from the "Source Anchor" drop-down.
Verify successful Active Directory Synchronization and activate Microsoft 365 licensing for unlicensed synchronized users.
The transition of your Microsoft 365 tenant from "managed" to "federated" can take two hours or more.
Log on to the domain-joined computer where you installed the Microsoft Online Services Sign-in Assistant, the Microsoft Azure Active Directory Module for Windows PowerShell, and the Azure AD Connect tool.
Launch the Windows Azure Active Directory Module for Windows PowerShell and enter the
Connect-MsolService command. Enter your Microsoft 365 administrator credentials for the domain you will be configuring for SSO using Duo Access Gateway.
Verify that your Microsoft 365 domain is not currently federated.
PS C:\> get-msoldomain -domain your365domain.com Name Status Authentication ---- ------ -------------- your365domain.com Verified Managed
If your Microsoft 365 domain is using Federated authentication, you need to convert it from Federated to Managed to modify the SSO settings.
Set-MsolDomainAuthentication –DomainName your365domain.com -Authentication Managed
get-msoldomain command again to verify that the Microsoft 365 domain is no longer federated.
Copy the dag.crt file downloaded from the Duo Access Gateway admin console to the domain-joined computer with the Windows Azure Active Directory Module for Windows PowerShell. Make note of the certificate file location.
Gather the federation parameter information.
|Parameter||Description or Value|
|DomainName||The fully qualified Microsoft 365 tenant domain name (FQDN) to update: your365domain.com|
|Authentication||The authentication type of the domain: Federated|
|PassiveLogOnUri||The DAG login URL where web clients are redirected when signing in to Microsoft 365. This is the SSO URL from the DAG Metadata shown in the DAG admin console: https://yourserver.example.com/dag/saml2/idp/SSOService.php|
|SigningCertificate||The DAG's token signing certificate, downloaded from the DAG Applications page: C:\Path\to\dag.crt|
|IssuerUri||The Entity ID URL from the DAG Metadata shown in the DAG admin console: https://yourserver.example.com/dag/saml2/idp/metadata.php|
|LogOffUri||The DAG logout URL where web clients are redirected when signing out of Microsoft 365. This is the Logout URL from the DAG Metadata shown in the DAG admin console: https://yourserver.example.com/dag/saml2/idp/SingleLogoutService.php|
|PreferredAuthenticationProtocol||SAML 2.0: SAMLP|
Set the federation parameters as PowerShell variables.
$dom = "your365domain.com" $url = "https://yourserver.example.com/dag/saml2/idp/SSOService.php" $uri = "https://yourserver.example.com/dag/saml2/idp/metadata.php" $logoutUrl = "https://yourserver.example.com/dag/saml2/idp/SingleLogoutService.php" $cert=New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Path\to\dag.crt") $certData = [system.convert]::tobase64string($cert.rawdata)
Verify the PowerShell variables set in step 5. Make sure there aren't any errors in the variable names or values.
get-variable dom,url,uri,logoutUrl,cert,certData | fl Name,Value
Convert the Microsoft 365 domain to Federated authentication with the
Set-MsolDomainAuthentication command, using the PowerShell variables for federation set in step 5.
Set-MsolDomainAuthentication –DomainName $dom -Authentication Federated -PassiveLogOnUri $url -ActiveLogOnUri $url -IssuerUri $uri -LogOffUri $logoutUrl -PreferredAuthenticationProtocol SAMLP -SigningCertificate $certData
Verify that your Microsoft 365 domain is now federated.
PS C:\> get-msoldomain -domain your365domain.com Name Status Authentication ---- ------ -------------- your365domain.com Verified Federated
Verify your federation settings.
PS C:\> Get-MsolDomainFederationSettings -domain your365domain.com | fl * ExtensionData : System.Runtime.Serialization.ExtensionDataObject ActiveLogOnUri : https://yourserver.example.com/dag/saml2/idp/SSOService.php DefaultInteractiveAuthenticationMethod : FederationBrandName : Your Tenant Org Name IssuerUri : https://yourserver.example.com/dag/saml2/idp/metadata.php LogOffUri : https://yourserver.example.com/dag/saml2/idp/SingleLogoutService.php MetadataExchangeUri : NextSigningCertificate : OpenIdConnectDiscoveryEndpoint : PassiveLogOnUri : https://yourserver.example.com/dag/saml2/idp/SSOService.php PreferredAuthenticationProtocol : Samlp PromptLoginBehavior : SigningCertificate : MIICX...*snip*... SigningCertificateUpdateStatus : SupportsMfa : False
See the Single Sign-On Roadmap at the Microsoft TechNet site for more information about configuring SSO for Microsoft 365 using SAML 2.0.
Navigate to https://login.microsoftonline.com and enter your Microsoft 365 username or email address (with no password). You will be automatically redirected to your Duo Access Gateway sign-in page to complete authentication. Enter your Active Directory username and password on the Duo Access Gateway login page, and approve the prompt for Duo two-factor authentication. You are logged into Microsoft 365.
Congratulations! Your Microsoft 365 users now authenticate using Duo Access Gateway.
If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID) in the traditional Duo Prompt, Duo recommends configuring allowed hostnames for this application and any others that show the inline Duo Prompt before onboarding your end-users.
The Duo Universal Prompt has built-in protection from unauthorized domains so this setting does not apply.
Office 2013 and later desktop applications (including Outlook and Skype for Business) can connect to Microsoft 365 after federation with the Duo Access Gateway, implementing the Duo custom control for Azure conditional access, or Duo AD FS adapter installation only if Modern Authentication is enabled for your Microsoft 365 tenant. 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 Microsoft 365 for the first time after federation using an Office application, you'll see the Duo Access Gateway primary login page within the Office application, followed by the Duo authentication prompt.
Important: If users had a preexisting Microsoft 365 Outlook profile before federating with the Duo Access Gateway they might not be able to log in with modern authentication after federation and may then need to delete the existing Microsoft 365 client credentials in order to log in with Modern Authentication. Learn how to delete Microsoft 365 client credentials and more about M365 mail client behavior with Duo.
Microsoft 365 rich clients that support Modern Authentication that are configured after federation will see the Duo Access Gateway login page within the mail client, followed by the Duo authentication prompt.
Clients that do not support Modern Authentication will not be able to log in unless the Enable Basic Auth setting is enabled in the Create the Microsoft 365 Application in Duo section. If the option is enabled users will continue to log into their mail clients using only their username and password.
If you use service accounts to send e-mails from devices that don't support Modern Authentication, such as copiers, printers, or scanners, you can use the Enable Basic Auth setting in the Create the Microsoft 365 Application in Duo section to allow those accounts to continue to send e-mail. You will need to create Duo user accounts for the service accounts.