Duo Single Sign-On

Overview

Duo Single Sign-On is a cloud-hosted Security Assertion Markup Language (SAML) 2.0 identity provider that secures access to cloud applications with your users’ existing directory credentials (like Microsoft Active Directory or Google Apps accounts). SAML delegates authentication from a service provider to an identity provider, and is used for single sign-on solutions (SSO).

Duo provides SAML connectors for enterprise cloud applications like Amazon Web Services, Salesforce and Workday. Duo Single Sign-On also offers a generic connector with the ability to provide your own SAML “metadata” and connect to just about any app that supports the SAML 2.0 standard.

Protected cloud applications redirect your users to Duo Single Sign-On, authenticating your users using your existing primary authentication source for credential verification, and then prompting for two-factor authentication before permitting access to the SAML application.

Duo Single Sign-On is available in Duo Beyond, Duo Access, and Duo MFA plans.

Duo Single Sign-On supports on-premises Active Directory (AD) and cloud or on-premises SAML IdPs as identity sources.

Video Overview

Prerequisites

Before you start using Duo Single Sign-on, make sure to meet all the requirements described below:

• A Duo Admin with the Owner role.
• Active Directory or a SAML identity provider that can be used as your primary authentication source for Duo Single Sign-On.
• If you're using Active Directory you'll need:
  • At least one standalone Windows or Linux server that can communicate with your Active Directory domain controller(s).
  • Service account credentials for Active Directory.
  • Access to DNS for the user email domains you'll use with SSO to add TXT records.
• A SAML 2.0 Service Provider web application to protect with Duo Single Sign-on.

Enable Duo Single Sign-On

Role required: Owner

1. Log in to the Duo Admin Panel and click Single Sign-On in the navigation bar on the left.

2. Review the information on the "Single Sign-On" page. If you agree to the terms, check the box and then click Activate and Start Setup.

3. On the Customize your SSO subdomain page you can specify a subdomain you'd like your users to see when they are logging in with Duo Single Sign-On. For example, you can enter acme and users would see acme.login.duosecurity.com in the URL when logging into Duo Single Sign-On.

   Click Save and continue to use the desired subdomain or click Complete later to skip this step for now.

   

4. On the Add Authentication Source page choose between using Active Directory or a SAML Identity Provider as your authentication source. Click the button at the bottom of the option you'd like to use to add that source type, and follow the instructions in the next section.

   

Configure Your Authentication Source

Duo Single Sign-On allows you to use Active Directory or a SAML Identity Provider as a first factor authentication source. You may configure one of each authentication source type, but only a single source may be active at a time.

Active Directory

Follow the steps below to first configure an on-premises Authentication Proxy to connect to Duo Single Sign-On. You'll then configure Duo Single Sign-On to talk to your Active Directory through the Authentication Proxy.

Install Duo Authentication Proxy

Duo Single Sign-On communicates with your Active Directory by having an Authentication Proxy installed and configured on-premises to connect Duo Single Sign-On and Active Directory together.

We recommend three authentication proxy servers for high availability. During authentication the order of which authentication proxy to use will be chosen at random.

1. Install Duo Authentication Proxy 5.0.0 or higher on a Windows or Linux server following the installation instructions.

2. Confirm that your Authentication Proxy can communicate with your Active Directory domain controllers over LDAP/LDAPS (commonly ports 389/636).

3. Confirm that your Authentication Proxy has outbound Internet access over port 443.

Connect Authentication Proxy to Duo Single Sign-On

1. On the "Active Directory Configuration" under "1. Install the Authentication Proxy" click Add Authentication Proxy. You'll be redirected to a new page.

2. You can rename your Authentication Proxy by clicking Rename at the top of the screen to give it an easily identifiable name.

3. Select the "Windows" or "Linux" tab based on your Authentication Proxy install to be given specific instructions.

4. On your Authentication Proxy server locate and open the authproxy.cfg file with elevated permissions.

   OS	Path
   Windows	C:\Program Files\Duo Security Authentication Proxy\conf
   Linux	/opt/duoauthproxy/conf

5. Click Copy under "Add service account credentials to authproxy.cfg" and append this to your authproxy.cfg file. A first time Authentication Proxy install may include an existing authproxy.cfg with some example content. For the purposes of these instructions, however, you should overwrite the existing sample content and paste in the copied data.

6. If you plan to use NTLMv1, NTLMv2, or Plain authentication then uncomment and populate the service_account_username and service_account_password lines with the credentials for a service account in your Active Directory. You do not need these lines in your authproxy.cfg if you plan to use Integrated authentication.

   

   Any service account credentials specified in the config will be ignored during user authentication if you select Integrated authentication when completing Active Directory configuration.

7. Save and close the authproxy.cfg file.

8. Follow the instructions in "2. Connect the Authentication Proxy to Duo" and run the command to connect your Authentication Proxy to Duo Single Sign-On.

   

9. Click Run test under "3. Verify the proxy is connected" to confirm your Authentication Proxy is connected to Duo. If you encounter any issues check the logs on the Authentication Proxy.

10. Once the Authentication Proxy is connected to Duo click Return to Configuration to return to the "Active Directory Configuration" page.

11. You can add additional Authentication Proxy servers by repeating steps 1 through 10.

Configure Active Directory

1. On the "Active Directory Configuration" page scroll down to "2. Configure Active Directory" and fill out the form using the information below. Note that all information is required unless otherwise noted.

   Name	Description
   Display Name	Enter a name to help you easily identify your Active Directory authentication source.
   Domain Controller(s)	Enter the IP address or hostname of your AD domain controller (DC), followed by the port the Authentication Proxy server should use to contact the domain controller. The typical port for unsecured LDAP or STARTTLS is 389, and LDAPS is usually 636. Click Add Domain Controller to add additional hosts. We recommend at least three domain controllers for high availability. When performing authentication, the order of the domain controllers will be randomized. If the first server in the list doesn't respond the next server is used as a fallback. If you decommission any of your domain controllers be sure to return to Duo and remove it from the list.
   Base DN(s)	Enter a DN that corresponds to a container or OU in your directory structure containing the user accounts for SSO. You can add additional DNs by clicking Add Base DN. Example DNs: ou=Employees,ou=US,dc=acme,dc=corp searches within an organizational unit hierarchy; dc=acme,dc=corp searches the entire domain.
   Authentication type	Select the type of authentication the Authentication Proxy will use to connect to your AD domain controller. One of: Integrated - Performs SSPI authentication. This option requires no additional configuration here, but the Duo Authentication Proxy server must be a Windows machine joined to the domain that contains your users. NTLMv1 - Performs Windows NTLMv1 authentication. If you select this option you'll need to enter the NTLM domain and NTLM workstation names, and also ensure you have specified the username and password used to connect to your AD domain in the authproxy.cfg when you configured your Duo Authentication Proxy server. NTLMv2 - Performs Windows NTLMv2 authentication. If you select this option you'll need to enter the NTLM domain and NTLM workstation names, and also ensure you have specified the username and password used to connect to your AD domain in the authproxy.cfg when you configured your Duo Authentication Proxy server. Plain - Performs basic authentication. This option provides the widest compatibility. Ensure you have specified the username and password used to connect to your AD domain in the authproxy.cfg when you configured your Duo Authentication Proxy server. We recommend using secure LDAPS or STARTTLS transport to protect sensitive credentials if you select this option. Default: Integrated.
   Transport type	The transport type selected determines how the connection between the Duo Authentication Proxy software and the AD domain server is encrypted, if at all. Connectivity between the Duo Authentication Proxy software and the Duo Security cloud services is always HTTPS secured with SSL and is not affected by this setting. One of: Clear - Unencrypted - LDAP communication between your DC and the Authentication Proxy will not be encrypted. If you selected **Plain** authentication for this directory, please avoid CLEAR and switch to a secure transport type to protect your AD domain lookup credentials. LDAPS - Encrypts LDAP communication using SSL over a dedicated secure port distinct from the port used for unsecured transport. STARTTLS - Opens an unencrypted connection on the unsecured LDAP port then secures the connection with TLS. Selecting LDAPS or STARTTLS exposes additional settings: SSL verify hostname - Requires that the AD domain's SSL certificate subject "common name" or "issued to" and the server hostname you entered when setting up your directory need to match. SSL CA certificate - In order to secure LDAP connections to your AD domain server using LDAPS or STARTTLS protocols, you'll need the PEM formatted certificate from the certificate authority (CA) that issued your AD domain controller's SSL certificate. To obtain the PEM formatted version of the AD domain controller certificate's issuing CA certificate, view the "Certification Path" tab of the DC's certificate properties and double-click the issuing certificate to view it. Export the issuing CA certificate as a Base-64 encoded X.509 (CER) format and upload it here You may need to export all the certs (such as root CA and intermediate CA) in the certification path, open each in a text editor, copy the file contents (including the BEGIN and END wrapper), and paste them all into one certificate bundle file to upload here. Default: Clear - Unencrypted.
   Email attributes	All AD attributes that could contain a user's email address. The values for the attribute(s) you specify here must be in SMTP address format (user@example.com. You can add additional attributes by clicking Add attribute. This email will also be the username sent to Duo for 2FA unless you specify an alternate Duo username attribute. Default: mail.
   Duo username attribute	Optional The email address that users type in during SSO login will be matched to the user in Duo. If your Duo usernames do not match the email address value(s) for your specified Email attributes, you enable the Specify Duo username attribute option and type in the name of an Active Directory attribute that does contain the values that match your Duo usernames. Example: Your users have email addresses in AD with the format norben.arroway@example.com, but your Duo usernames are the sAMAccountName values with the format narroway. Add sAMAccountName as a Duo username attribute. Default: No alternate username attribute; send email address as Duo username.
   Username normalization	Controls whether or not usernames entered for primary authentication should be altered before trying to match them to a Duo user account. When set to None, the usernames narroway, EXAMPLE\narroway, and narroway@example.com would be three separate users in Duo. When set to Simple, any domain information is stripped from the username sent to Duo, so narroway, EXAMPLE\narroway, and narroway@example.com would all resolve to a single "narroway" Duo user. Default: Simple.

   

Configure Permitted Email Domains

Duo Single Sign-On requires that you verify control of the email domains users will be logging in with by adding a DNS TXT record to the domain's DNS.

When a user attempts to log in with an email address that has not been verified by their organization, the authentication will be rejected and the user's credentials will not be sent to the authentication proxy for verification. This prevents your users from accidentally exposing their credentials to a Duo Single Sign-On not owned by your organization.

1. Under "3. Permitted Email Domains" find 1. Add Email Domain and type in the domain name of an email address that users from your organization will use to log in. Example: If your email address is username@example.com type example.com under step 1 and click Add.

2. A table appears showing the domain name you just added, along with additional information about the DNS TXT record that needs to be created.

3. Log into your DNS provider and create a DNS TXT record for the domain you just added in Record Name (eg. example.com) with the value in the corresponding DNS Text Record Value column.

   You will be creating a DNS TXT record for your domain. Many domain registrators allow you to signify this by using the @ symbol.

   See below about adding DNS records for popular domain registrars:

   • Akamai FastDNS
   • AWS Route53
   • Azure
   • CloudFlare
   • Google Cloud
   • Google Domains
   • GoDaddy

4. Once your DNS record has been created, return to the Duo Admin Panel and click the Verify button under the "Status" column. It can take time for DNS changes to propagate so if the verification fails, you may need to wait and try again later.

   Once the record has been verified the "Status" column will change to "Verified". Users using the verified domain will now be able to log into Duo Single Sign-On.

5. Repeat steps 3.1 through 3.4 for all email domains that need to be verified. Subdomains must be individually verified.

   

You may delete the DNS TXT record after Duo verifies the domain. Don't remove it before your domain shows "Verified" status.

Test Your Setup

1. Under "4. Test Active Directory Configuration" click Run tests. This will test connections between Duo Single Sign-On, your Authentication Proxy server(s), and your Active Directory. It will only report the status of an individual connection if there is an error. If you encounter an error, make the appropriate changes and click Run tests again.

2. Click Save. You are now ready to start protecting applications with Duo Single Sign-On.

   

SAML

Follow the steps below to configure Duo Single Sign-On as a service provider inside of your SAML identity provider and configure Duo Single Sign-On to use your SAML identity provider for authentication. Keep the Duo Admin Panel open in your browser while you access your SAML IdP's administrative console in a new window or tab. You'll need to return to the Duo Single Sign-On page to complete the configuration steps.

Additional Settings

Configure Custom Subdomain

If the custom subdomain was not configured during initial setup, you can configure it from the main Single Sign-On page.

1. While on the Single Sign-On page, under "Custom Subdomain" click the Create a custom subdomain button.

2. The page will redirect to the Customize your SSO subdomain page. You can specify a subdomain you'd like your users to see when they are logging in with Duo Single Sign-On. For example, you can enter acme and users would see acme.login.duosecurity.com in the URL when logging into Duo Single Sign-On. Click Save and continue.

   

3. You'll be redirected back to the "Single Sign-On" page which will now display your custom subdomain.

   

Add a new authentication source

You can create an additional authentication source but can only have one of each type.

1. While on the Single Sign-On page, under "Configured Authentication Sources" click Add source.

2. The page will redirect to the Add Authentication Source page. You can choose between using Active Directory or a SAML Identity Provider as your authentication source but can only have one of each type. Click the Add button at the bottom of the option to be taken to the configuration page for the new authentication source.

   

Modify Authentication Sources

1. While on the Single Sign-On page, click on the name of authentication source you'd like to modify.

2. You'll be redirected to the authentication source page where changes can be made. At the top of each page, it will show the status of the authentication source. You can only have one active authentication source at a time. If it is inactive you can click the Edit button next to "Status" to switch it to the active authentication source. This immediately inactivates your other authentication source. Delete an inactive authentication source by clicking Delete Source.

   

Create a Cloud Application in Duo

When configuring an application to be protected with Duo Single Sign-On you'll need to send attributes from Duo Single Sign-On to the application. Active Directory will work with no additional setup, but if you used a SAML identity provider as your authentication source please verify that you configured it to send the correct SAML attributes.

Below you can see the Bridge Attribute name used that automatically maps certain attributes from your authentication source.

Bridge Attribute	Active Directory	SAML IdP
<Username>	sAMAccountName	Username
<Email Address>	mail	Email
<Display Name>	displayName	DisplayName
<First Name>	givenName	FirstName
<Last Name>	sn	LastName

Duo has pre-configured SAML configurations for many popular cloud applications. Refer to the instructions for your named service provider:

• Amazon Web Services (AWS)
• Atlassian Cloud
• Box
• Cisco ASA
• Cisco Umbrella
• Cisco Webex
• Dropbox
• G Suite
• Meraki Dashboard
• PagerDuty
• Palo Alto GlobalProtect
• Salesforce
• ShareFile
• Slack
• Smartsheet
• Workday
• Workplace by Facebook
• Zendesk
• Zoom

You can also use Duo Single Sign-On with any SAML 2.0 service provider by configuring it as a generic service provider application in Duo.

Duo Central

Once you've configured Duo Single Sign-On, you're ready to enable Duo Central, a single location for your users to get access to all of their organization's applications and helpful links. Get started with Duo Central.

Network Diagram

Active Directory

1. User goes to a SAML service provider they'd like to log into.

2. SAML Service Provider redirects user's browser to Duo Single Sign-On with a SAML request message.

3. User logs in with primary credentials.

4. Duo Single Sign-On sends the credentials to the Duo Authentication Proxy in the customer's network. The Authentication Proxy forwards this to Active Directory which returns a response back to Duo Single Sign-On.

5. Duo Single Sign-On requires the user to complete two-factor authentication.

6. User completes Duo two-factor authentication.

7. Duo Single Sign-On redirects user's browser to the SAML Service Provider with response message.

SAML Identity Provider

1. User goes to a SAML service provider they'd like to log into.

2. SAML Service Provider redirects user's browser to Duo Single Sign-On with a SAML request message.

3. Duo Single Sign-On redirects user's browser to the SAML identity provider with a SAML request message.

4. User logs in with primary credentials.

5. SAML identity provider redirects user's browser to Duo Single Sign-On with response message.

6. Duo Single Sign-On requires the user to complete two-factor authentication. User completes Duo two-factor authentication.

7. Duo Single Sign-On redirects user's browser to the SAML Service Provider with response message.