Duo Single Sign-On

Overview

Duo Single Sign-On is a cloud-hosted single sign-on solution (SSO) solution which can act as a Security Assertion Markup Language (SAML) 2.0 identity provider or OpenID Connect (OIDC) provider that secures access to cloud applications with your users’ existing directory credentials (like Microsoft Active Directory or Google Apps accounts). SAML and OIDC delegate authentication from the application to an identity provider, and is used for SSO.

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

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

Duo Single Sign-On is available in Duo Premier, Duo Advantage, and Duo Essentials commercial plans, and is not available in Duo Federal plans. Learn more about Duo's SSO solution.

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 to enable the feature.
• 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 or OIDC relying party 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, click Get Started.

3. On the Customize 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. Trial accounts are restricted from creating a subdomain.

   Click Save and continue to use the desired subdomain or click Skip for now to customize your subdomain later.

   

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.

   

   If you are configuring your first Active Directory, when you click Add Active Directory you will be prompted to review and accept a privacy statement. The privacy statement won't be shown again for additional Active Directory authentication sources or for SAML sources.

Configure Your Authentication Source

Role required: Owner, Administrator, or Application Manager

Duo Single Sign-On allows you to use either Active Directory domains and forests or a SAML Identity Provider as a first-factor authentication source.

While you can complete the configuration steps for both Active Directory and SAML authentication sources, only one type of authentication source may be enabled for use 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 domain controllers through the Authentication Proxy.

Plan for AD Authentication

When planning your Active Directory authentication configuration to support SSO, determine whether Duo Single Sign-on needs to authenticate users from a single AD domain, or from multiple AD domains organized in an Active Directory forest. You can create up to 10 separate Active Directory authentication sources which allows you to support additional domains and forests.

During SSO login, the authentication request gets sent from Duo's cloud service to the Duo Authentication Proxy servers you deployed on-premises. The Authentication Proxy, in turn, contacts one of the domain controllers using the IP/host name and port you enter in the configuration to look up users and groups and perform LDAP authentication.

Single Domain

If all the users who will sign in to applications via Duo SSO reside in a single domain, that is, all the user accounts are located in organizational units (OUs) and containers immediately under your domain's base distinguished name (DN) value, then when you configure the AD source for Duo SSO you will:

• Enter the IP addresses or host names for the domain's AD domain controller servers.
• Specify port 389 to communicate with the domain controllers using LDAP/STARTTLS or port 636 to use LDAPS.
• Enter the base DN value that is the root of the domain.

Example Information for a Single Domain:

Domain:               acme.corp
Domain DC:            dc1.acme.corp
Base DN:              DC=acme,DC=corp
DNs of Domain Users:  CN=narroway,OU=Users,DC=acme,DC=corp
                      CN=sogilby,OU=Users,DC=acme,DC=corp

Forest with Global Catalog

If the users who will sign into applications via Duo SSO reside in different domains within a single Active Directory forest, consider making use of Active Directory's global catalog, which replicates attributes between domain controllers throughout the forest so that a domain controller from any forest member domain can answer LDAP queries for any other domain in the forest.

The benefit of configuring a Duo SSO AD authentication source to use your forest's global catalog instead of adding domains in the forest as individual SSO authentication sources is that the AD authentication source backed by the forest's global catalog can look up user and group information in Active Directory and perform authentication for users faster than if Duo SSO had to repeat the same operations in separate authentication sources.

If the users who will sign in to applications via Duo SSO reside in domains within a single forest, then when you configure the AD source for Duo SSO you will:

• Enter the IP addresses or host names for the AD domain controller servers from any or all of the forest member domains. The domain controllers must have the "Global Catalog" option enabled from Active Directory Sites and Services or with the repadmin tool.
• Specify port 3268 to communicate with the domain controllers using LDAP/STARTTLS or port 3269 to use LDAPS.
• Enter the base DN value that is the root of the forest.

Example Information for a Forest with Multiple Domains:

Forest Root Domain:       acme.corp
Forest Member Domains:    amer.acme.corp
                          emea.acme.corp
DCs from Member Domains:  dc1.amer.acme.corp
                          dc1.emea.acme.corp
Forest Base DN:           DC=acme,DC=corp
Domain Base DNs:          DC=amer,DC=acme,DC=corp
                          DC=emea,DC=acme,DC=corp
DNs of Domain Users:      CN=narroway,OU=Users,DC=amer,DC=acme,DC=corp
                          CN=sogilby,OU=Users,DC=emea,DC=acme,DC=corp

By using the global catalog this AD authentication source can lookup and authenticate users from either the AMER or EMEA forest member domains against the domain controller from either domain.

The expired password reset and proactive password change options in Duo SSO will not work with this setup because the Global Catalog is unable to change user passwords.

Learn more about Microsoft's Active Directory global catalog.

Multiple Domains as Separate Authentication Sources

Your organization will require multiple Active Directory authentication sources if you have users in different forests. You can configure Duo Single Sign-On to have up to 10 enabled Active Directory authentication sources at a time.

When a user attempts to log-in and you have multiple enabled Active Directory authentication sources:

• Duo Single Sign-On will reach out to all your Active Directories simultaneously and get results back from each Active Directory.
• If Duo Single Sign-On gets results for multiple users matching the email address, it will show an error to the user. All email addresses that users log-in with should be unique across all the directories.

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. Each Authentication Proxy must be able to connect to every domain controller you plan to use for authentication.

1. Install Duo Authentication Proxy 5.5.1 or higher on a Windows or Linux server following the installation instructions. If you already have a Duo Authentication Proxy that you'd like to use, you can upgrade the proxy to a supported version.

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

If you do not complete connecting an Authentication Proxy to Duo Single Sign-On you will see unassigned proxies appear on your Active Directory pages.

1. On the "Active Directory Configuration" under "1. Install the Authentication Proxy" click Add Authentication Proxy. This redirects you to a new page.

2. You can rename your Authentication Proxy by editing the Name field to give it an easily identifiable name. You can add a description of the proxy in the Description field.

3. Select the "Windows" or "Linux" tab based on your Authentication Proxy install to view platform-specific instructions.

4. On your Authentication Proxy server locate and open the authproxy.cfg file in a text editor or the Proxy Manager application (available for Windows servers starting with Authentication Proxy version 5.6.0) 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 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. If using the Proxy Manager for Windows, click Validate to check your configuration, and then click Save before closing the application.

8. Follow the "2. Connect the Authentication Proxy to Duo" instructions shown in the Admin Panel to generate and then copy the command to run on your proxy server to connect your Authentication Proxy to Duo Single Sign-On. Note that the specific command syntax differs depending on whether you installed the Duo Authentication Proxy on a Windows or Linux server.

   

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

Viewing Information about Connected Authentication Proxy Servers

You can view information about your Authentication Proxy in the Authentication Proxy Dashboard.

You can also view information from the Active Directory Authentication Source page, by clicking on the "Proxy name" value for any of your connected Authentication Proxy servers.

The "Details" Section shows the following information:

Name	Description
Name	The name you set for this proxy in the Admin Panel.
Description	The description for this proxy in the Admin Panel.
Hostname	The host name of the server as reported by the running Duo Authentication Proxy service on that server.
Status	Whether the Authentication Proxy service is currently connected to Duo or not. Click the icon to refresh status.
Version	The installed Duo Authentication Proxy software version.
Operating System	The operating system on which the Duo Authentication Proxy is running (Windows, Linux or Unknown).

Unassigned Authentication Proxies

On the "Active Directory Configuration" under "1. Install the Authentication Proxy" you may see a second section appear called "Unassigned Authentication Proxies"; these are proxy servers that were never configured or connected to an Active Directory.

You can remove Authentication Proxy server(s) from this list by doing one of the following:

• Connect the Authentication Proxy to an Active Directory

  1. Click on the name of the Authentication Proxy to be taken to its configuration page.
  2. Follow the steps starting with Step 2 in Connect Authentication Proxy to Duo Single Sign-On.

• Deleting the Authentication Proxy

  1. Click on the name of the Authentication Proxy to be taken to its configuration page.
  2. Click Disconnect Authentication Proxy in the upper right-hand corner of the page.
  3. Reading the information on the pop-up and then clicking Yes, disconnect this proxy.

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. Every host you add here must be reachable for LDAP connections by every Authentication Proxy server added. The default port for LDAP lookups against a single domain using unsecured LDAP or STARTTLS is 389, and the default LDAPS port is 636. The default port for LDAP lookups against all domains in a forest using global catalog with unsecured LDAP or STARTTLS is 3268, and the default LDAPS port is 3269. 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=amer,dc=acme,dc=corp searches a single domain in a multi-domain forest, and dc=acme,dc=corp searches the entire forest.
   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. 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. Starting with Authentication Proxy version 6.0.0, the certificate issued to the domain controller(s) must use SHA256 or greater. 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 controller'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. If you do use a self-signed certificate to secure LDAPS communications to your domain controller, the certificate's key usage must include "Certificate Signing". 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.
   Expired password reset	Controls whether users can reset their expired Active Directory passwords during login after successfully completing MFA. When set to Don't allow users to reset their expired password, users with expired passwords will fail Active Directory authentication. When set to Allow users to reset their expired password, users will be required to reset their expired Active Directory passwords during login after successfully completing MFA before continuing on to their application. When this setting is enabled the Password requirements text box will appear requiring you to type in your Active Directory password requirements. Each requirement should be on a separate line which will be shown to users as a bulleted list. Duo SSO is unable to check the Active Directory password policy so it is important this information is accurate so users will understand the requirements. Enabling password resets has the following requirements: Transport type must be set to LDAPS or STARTTLS All Duo Authentication Proxy server(s) must be version 5.5.0 or higher Must not be using the Global Catalog port to communicate with the domain controllers The user experience is as follows: User initiates log in to an application protected by Duo SSO. The application redirects the user to the Duo SSO login page for email address and password. Active Directory verifies the submitted password and informs Duo SSO the user's password has expired. Duo SSO informs the user that they must change their expired password after completing two-factor authentication. User completes Duo authentication and returns to Duo SSO for the password change. The Duo SSO password reset page shows the user the password requirements you entered during AD authentication source configuration. The user enters their current, expired password, and then can enter and confirm their new password. If the password change succeeds, the user gets prompted to continue to the application without needing to reauthenticate. If the password change fails, the user may try to reset their password again until they succeed or leave the Duo SSO page without accessing the application. Note: If you have users with bypass status or have applied policies that allow unenrolled users to login without MFA, they'll be able to reset their Active Directory passwords from Duo SSO without performing two-factor authentication. See the expired password reset experience for users in the Duo End User Guide. Default: Don't allow users to reset their expired password.
   Password expiration warning	If expired password resets have been enabled then you can also enable a prompt shown to users at login a configurable number of days before their passwords expire. After providing their current password in the login process, Duo SSO warns them of their upcoming password expiration and how many days left until it expires. A user can opt to reset their password ahead of the expiration date, which sends then to Duo MFA before the password change screen, or skip the password change and proceed to the application. If the user declines to reset their password they continue seeing the warning the next time they log in to Duo SSO with their expiring password until they either reset it or the password expires. The user experience is similar to the experience described for expired password reset except that the user can decline to change their password from the warning message. This setting does not appear if expired password reset isn't enabled. See the password warning and reset experience for users in the Duo End User Guide. Default: Show a warning message before password expiration date and show the warning 14 days before expiration.
   Proactive password change	If expired password resets have been enabled then you can also allow users to change their passwords from Duo SSO at any time. Before entering their username on the Duo SSO login page they can click a help link that will let them access password reset. After providing their current password and completing Duo two-factor authentication to verify their identity, they can enter a new password and then continue to the application. If a user has an existing SSO session (as defined in the Session Duration setting) they won't encounter the proactive warning again untl their next log in with a password after the session expires. This setting does not appear if expired password reset isn't enabled. See the proactive password reset experience for users in the Duo End User Guide. Default: Don't allow users to proactively change their password.
   Session Duration	Controls the number of hours a user will stay logged into Duo SSO before having to authenticate with their primary credential again. You can set the duration between 1 hour to 24 hours. Changing this value will affect existing Duo SSO sessions by forcing any logged-in users to authenticate again if they were logged in longer than the new set duration. Duo SSO session expiration does not affect the session established independent of Duo between the end-user's client and the application. Default: 8 hours.
   Logout Redirect URL	This field is optional. When this field is populated, after logging a user out of Duo Single Sign-On they will be redirected to the URL in this field.

   

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 email domain's public (external) 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. If you are using multiple Active Directory authentication sources there will be a Permitted Domains tab on the main "Single Sign-On" page. If you are only using one Active Directory you'll find it under "3. Permitted Email Domains" on the Active Directory authentication source page.

2. Under 1. Add Email Domain 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.

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

4. 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 registrars allow you to signify this by using the @ symbol.

   See below about adding DNS records for popular domain registrars:

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

5. Once your DNS record has been created, return to the Duo Admin Panel and click the Verify button under the "Status" column. Duo's service queries your public DNS for the expected new TXT record.

   It can take some time for DNS changes to propagate so if the verification attempt fails, you may need to wait and try again later. If email domain verification continues to fail, double-check that the DNS TXT record was created correctly.

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

7. Repeat steps 1 through 6 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 "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.

Add another Active Directory Authentication Source

Once you've completed setting up an Active Directory authentication source you can add additional Active Directory authentication sources and Authentication Proxy server(s) by:

1. Adding a new authentication source.
2. Following the steps to add new Authentication Proxy servers and configure the additional Active Directory.

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. Trial accounts are restricted from creating a subdomain.

1. While on the Single Sign-On page, click the Subdomain tab. You'll see your current, default SSO login URL. Click Customize subdomain to start creating a custom SSO login URL.

   

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

   

3. You'll see a success message and the "Subdomain" tab now displays your custom subdomain in the URL.

Add a new authentication source

You can create additional authentication sources. You can have up to 10 Active Directory authentication sources and one SAML Identity Provider.

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. Click the Add button at the bottom of the option to be taken to the configuration page for the new authentication source.

   Additional authentication sources added will start out disabled. See how to modify an authentication source to enable it.

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 type of authentication source enabled at a time: Active Directory or SAML IdP. If the authentication source is disabled you can click the Edit button next to "Status" to switch it to a enabled authentication source. This immediately disables all your other authentication source of the other type. Delete a disabled authentication source by clicking Delete Source.

Bridge Attributes

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 five (5) default bridge attributes that automatically map certain attributes from your authentication source. These bridge attributes are required and cannot be edited.

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

Create a Custom Bridge Attribute

You can create custom bridge attributes if you have multiple identity providers with different names for the same attribute.

1. While on the Single Sign-On page, click on the "Bridge Attributes" tab.

2. Click on + Add Custom Bridge Attribute button at the top of the page.

3. Fill in the Bridge Attribute Name field with the name you would like to give this bridge attribute. This name is permanent and cannot be modified later. The following fields will be the attribute name for each identity provider you have.

   The example below shows the custom bridge attribute "Company" being mapped to the SAML Identity Provider Attribute, "company" and the aws acme Attribute, "companyName".

   

4. Click Save. A banner will appear at the top of the page with your successfully added custom bridge attribute. Click Back to Single Sign-On to see your new custom bridge attribute.

Create a Cloud Application in Duo

Role required: Owner, Administrator, or Application Manager

You can use Duo Single Sign-On with any SAML 2.0 service provider or OIDC relying party by configuring them with one of our generic connectors:

• Generic SAML Service Provider
• Generic OIDC Relying Party

We also provide pre-configured SSO apps for many popular cloud applications. Refer to the instructions for your named application:

Duo Single Sign-On can also act as an OAuth 2.0 authorization server supporting the client credentials grant type allowing secure machine to machine interactions by generating an access token with scoped permissions for one machine which can be sent and then validated by another machine. You can setup that connection using the OAuth 2.0 Client Credentials application.

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 your organization's applications and helpful links and manage their authentication devices. Get started with Duo Central.

Troubleshooting

Need some help? Try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.

All Duo customers have access to Level Up, our online learning platform offering courses on a variety of Duo administration topics. To access Level Up content, sign in with the same email address you use to sign in to the Duo Admin Panel.

Level Up course: Getting Started with Duo Single Sign-On

Network Diagram

SAML 2.0

Active Directory

1. User initiates SAML service provider login.

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 initiates SAML service provider login.

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.

OIDC

Active Directory

1. User initiates OIDC relying party login.

2. OIDC relying party redirects user's browser to Duo Single Sign-On with an OIDC 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 OIDC relying party with response message.

8. OIDC relying party makes a direct call to Duo Single Sign-On using its client secret and information from response message and receives back ID and access tokens.

9. OIDC relying party lets user in based off information in tokens.

SAML Identity Provider

1. User initiates OIDC relying party login.

2. OIDC relying party redirects user's browser to Duo Single Sign-On with an OIDC 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 OIDC relying party with response message.

8. OIDC relying party makes a direct call to Duo Single Sign-On using its client secret and information from response message and recieves back ID and access tokens.

9. OIDC relying party lets user in based off information in tokens.

OAuth 2.0 Client Credentials

1. OAuth relying party makes a call to Duo Single Sign-On with its client secret requesting access with specific scopes.

2. Duo Single Sign-On validates the OAuth relying party is allowed to use requested scopes and then generates an access token and returns it to OAuth relying party.

3. OAuth relying party makes a request to Resource Server and includes the access token.

4. Resource Server makes a call to Duo Single Sign-On with its client secret and the access token to validate the token.

5. Once the access token has been validated the Resource Server responds letting the OAuth relying party do actions based off the scopes specified in the access token.