Duo Protection for Microsoft 365 with Duo Access Gateway

Overview

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 Premier, Duo Advantage, and Duo Essentials 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.

Video Overview

Deploy or Update Duo Access Gateway

1. Install Duo Access Gateway on a server in your DMZ. Follow our instructions for deploying the server and configuring DAG settings.

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

3. After completing the initial DAG configuration steps, click Applications on the left side of the Duo Access Gateway admin console.

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

   

Create the Microsoft 365 Application in Duo

1. Log on to the Duo Admin Panel and navigate to Applications.

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

3. 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 alice@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.

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

5. 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
   Mail attribute	mail
   Object-GUID attribute	objectGUID

   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.

6. Click Save Configuration to generate a downloadable configuration file.

   

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

8. 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!

Add the Microsoft 365 Application to Duo Access Gateway

Before you do this, verify that you updated the "Attributes" list for your Duo Access Gateway AD authentication source as specified here.

1. Return to the Applications page of the DAG admin console session.

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

3. The Microsoft 365 SAML application is added.

Enable Microsoft 365 SSO

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.

Enable Directory Synchronization in Microsoft 365

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.

However, if you have already configured AD to Microsoft 365 synchronization and did not select the objectGUID attribute as the Source Anchor note that you cannot modify the selected Source Anchor attribute and must uninstall and reinstall Azure AD Connect in order to change it.

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

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

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

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

   

5. Verify successful Active Directory Synchronization and activate Microsoft 365 licensing for unlicensed synchronized users.

Enable AD Federation to Microsoft 365 using DAG

The transition of your Microsoft 365 tenant from "managed" to "federated" is typically quick but Microsoft states that it can take two hours or more. Please plan accordingly when enabling federation (or restoring your existing federation configuration back to managed to switch from a previous solution to Duo Access Gateway), as the transition may temporarily impact your users' login access.

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

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

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

   Rerun the get-msoldomain command again to verify that the Microsoft 365 domain is no longer federated.

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

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

6. 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)
   

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

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

9. Verify that your Microsoft 365 domain is now federated.

   PS C:\> get-msoldomain -domain your365domain.com
   
   Name                                            Status          Authentication
   ----                                            ------          --------------
   your365domain.com                               Verified        Federated
   

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

Verify SSO

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.

Office Client Access

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.

1. Modern Authentication may already be enabled on your Microsoft 365 tenant. Follow these instructions to verify or enable Modern Authentication on your Exchange Online tenant and these instructions to do the same for your Skype for Business Online tenant.
2. Apply registry updates for Office 2013 (Office 2016 and later applications and Skype for Business natively support Modern Authentication).

Please see the DAG FAQ or ADFS FAQ for additional details.

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.

Outlook and Duo Access Gateway

Office Apps and Mail Clients

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.

Service Accounts

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.

Troubleshooting

Need some help? Take a look at our Microsoft 365 Knowledge Base articles or Community discussions. For further assistance, contact Support.