Looking for a cloud-hosted SSO solution? Learn more about Duo Single Sign-On.
Microsoft customers with subscription plans that include Azure AD Premium P1 or P2 can secure Office 365 and Azure logons with the Duo custom control for Azure Active Directory, without any additional on-premises deployment. Learn more about Duo for Azure Conditional Access.
Duo Single Sign-on is a cloud-hosted Security Assertion Markup Language (SAML) 2.0 SSO solution that adds two-factor authentication to Office 365 and Azure logins. Duo Single Sign-On 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 Office 365.
Duo Single Sign-On is included in 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 Office 365. Duo checks the user, device, and network against an application's policy before allowing access to the application.
Duo Access Gateway (DAG), our on-premises SSO product, layers Duo's strong authentication and flexible policy engine on top of Office 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 Office 365.
Duo Access Gateway is included in 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 Office 365. Duo checks the user, device, and network against an application's policy before allowing access to the application.
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 Office 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 Office 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 Office 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 Office 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
firstname.lastname@example.org, 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 Office 365 application will be checked against Duo before authentication completes. If the effective New User policy for the Office 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 O365 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 Office 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.
Office 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 Office 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 Office 365 SAML application JSON file you downloaded from the Duo Admin Panel earlier. Click the Upload button after selecting the JSON configuration file.
The Office 365 SAML application is added.
In order to federate your Office 365 tenant with an external identity provider (like Duo Access Gateway) you must have added a custom domain to Office 365. You cannot federate your "onmicrosoft.com" domain. Additionally, the custom domain you have added to Office 365 cannot be set as the default domain.
If you previously configured directory synchronization between your on-premises AD domain and Office 365, skip these steps and proceed to Enable AD Federation to Office 365 using DAG.
Log in to the Microsoft Office 365 Portal Identity Federation Setup page as the tenant administrator. You'll need to complete most of the ten steps for single sign-on.
Review the Prepare for single sign-on documentation in step 1. You do not need to install AD FS or Shibboleth. The Duo Access Gateway will be your STS for single sign-on. Make note of the UPN requirements for SSO.
Skip step 2: "Plan for and deploy Active Directory Federation Services 2.0". You do not need to deploy AD FS. Duo Access Gateway replaces AD FS in this SSO scenario.
Do not click the "Install the Windows Azure Active Directory Module for Windows PowerShell" in step 3 to obtain the PowerShell module. Instead, install the Microsoft Online Services Sign-in Assistant on a computer joined to your AD domain (so, not the DAG server) and then open PowerShell and run
Install-Module MSOnline as described here to install the Microsoft Azure Active Directory Module for Windows PowerShell.
Review the prerequisites for Active Directory Synchronization in step 5 as well as the Azure AD Connect prerequisites.
Activate Active Directory synchronization for your domain in step 6.
Deploy the Azure AD Connect synchronization tool as described in step 7 "Install and configure the Directory Sync tool" on the same server where you installed the Microsoft Azure Active Directory Module for Windows PowerShell. Launch AAD Connect and select the "Custom Settings" option. 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 (step 8) and activate Office 365 licensing for unlicensed synchronized users (step 9).
The transition of your Office 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 Office 365 administrator credentials for the domain you will be configuring for SSO using Duo Access Gateway.
Verify that your Office 365 domain is not currently federated.
PS C:\> get-msoldomain -domain your365domain.com Name Status Authentication ---- ------ -------------- your365domain.com Verified Managed
If your Office 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 Office 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 Office 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 Office 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 Office 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 Office 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 Office 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 Office 365 using SAML 2.0.
Navigate to https://login.microsoftonline.com and enter your Office 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 Office 365.
Congratulations! Your Office 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), Duo recommends enabling hostname whitelisting for this application and any others that show the inline Duo Prompt before onboarding your end-users.
Microsoft's Active Directory Federation Services (AD FS) is a popular choice for SSO because it easily integrates with the AD identity store many organizations already have deployed. Duo's support for cloud applications and SSO drops in to an existing AD FS installation to provide secondary authentication after a user passes primary authentication (successful Active Directory logon).
If you don't already have AD federation running the first step is to install and configure Microsoft AD FS in your organization. Deployment Guides for AD FS versions 2.1, and 3.0/4.0 are available from Microsoft.
Once your AD FS services are up and running, the second step is to configure the SSO partnership between your AD FS service and the external cloud resource, in this case Office 365. Learn more about configuring Office 365 SSO with AD FS at the AD FS SSO Checklist at TechNet.
After you have successfully configured and tested AD FS SSO login to Office 365 using your AD domain credentials, you can then install the Duo AD FS integration. AD FS protection is included with Duo's paid plans.
With the Duo integration for AD FS installed, users pass primary authentication to the AD FS service as usual. Once primary authentication succeeds, users are forwarded to the Duo service for secondary authentication. After approving logon using one of Duo's authentication methods, the user is fully logged in to Office 365.
Office 2013 and later desktop applications (including Outlook and Skype for Business) can connect to Office 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 Office 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 Office 365 for the first time after federation using an Office application, you'll see the Duo Access Gateway, Azure AD, or AD FS primary login page within the Office application, followed by the Duo authentication prompt.
Important: If users had a preexisting Office 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 Office 365 client credentials in order to log in with Modern Authentication. Learn how to delete Office 365 client credentials and more about O365 mail client behavior with Duo.
Office 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 Office 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 Office 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.