Skip navigation
Documentation

Duo Single Sign-On

Last Updated: March 7th, 2024

Duo Single Sign-On is a cloud-hosted SAML 2.0 identity provider (IdP) and OIDC provider (OP) that adds two-factor authentication and access policy enforcement to popular cloud services like Microsoft 365 and Amazon Web Services using SSO protocols. Our SSO solution offers inline user enrollment, self-service device management, and support for a variety of authentication methods — such as passkeys and security keys, Duo Push, or Verified Duo Push — in the Duo Universal Prompt.

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.

Duo Single Sign-On Diagram

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

    Choosing a subdomain during setup
  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.

    Choosing an authentication source during setup

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.

Active Directory flow

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.

    Configure Authentication Proxy for Active Directory

    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.

    Authentication Proxy Enrollment Code
  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).
Authentication Proxy Server Detailed Information

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.
Unassigned Authentication Proxy Servers

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:

    1. User initiates log in to an application protected by Duo SSO.
    2. The application redirects the user to the Duo SSO login page for email address and password.
    3. Active Directory verifies the submitted password and informs Duo SSO the user's password has expired.
    4. Duo SSO informs the user that they must change their expired password after completing two-factor authentication.
    5. User completes Duo authentication and returns to Duo SSO for the password change.
    6. 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.
    7. 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.

    Active Directory Configuration

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:

  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.

Permitted Email Domain Configuration

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.

Active Directory Test Configuration

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.

Note: If you use Entra ID (Azure AD) as your SAML IdP for Duo Single Sign-On you cannot also protect Office 365 with Duo Single Sign-On.

Configure the Duo Single Sign-On app in Entra ID

  1. On the "Single Sign-On Configuration" page scroll down to 1. Configure your SAML Identity Provider. This is the Duo Single Sign-On metadata information you'll need to provide to your SAML identity provider to configure Duo Single Sign-On as a service provider.

    SAML Identity Provider Metadata
  2. Log into your Microsoft Entra admin center.

  3. Click on the menu icon in the upper left-hand side of the page. Click on Entra ID.

  4. On the left-hand navigation bar click ApplicationsEnterprise Applications. Click + New application at the top of the screen.

  5. Click + Create your own application at the top of the gallery page.

  6. On the "Create your own application" page type "Duo SSO" or any descriptive name you wish into the Input name field under "What's the name of your app?". Select the "non-gallery" option Integrate any other application you don't find in the gallery and then click Create.

  7. On the application "Overview" page under "Getting Started" click Assign users and groups.

  8. Click + Add user/group and select the users and groups that should have access to log in with Entra ID credentials to Duo Single Sign-On. After selecting the users and groups click Assign at the bottom of the page.

    You may not be able to see or select distribution groups created in the Microsoft 365 Admin Center from the Entra portal. If you do not see the group you want to choose and that group is a distribution-only group created in the M365 Admin Center, you will need to select a different group or recreate the group as either the "Microsoft 365" or "Security" group type with the same membership in Entra ID.

  9. On the left-hand navigation under "Manage" click Single sign-on. Select SAML on the "Select a single sign-on method" page.

  10. On the "Set up Single Sign-On with SAML" page under "Basic SAML Configuration" click the Edit icon (a pencil).

  11. While on the "Basic SAML Configuration" page copy the Entity ID from the Duo Admin Panel. In the Entra ID admin center click Add identifier under "Identifier (Entity ID)" and paste the URL you copied from Duo in the field that appears.

    Example: https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata

  12. Return to the Duo Admin Panel's "Basic SAML Configuration" page and copy the Assertion Consumer Service URL. In Entra ID click Add reply URL under "Reply URL (Assertion Consumer Service URL)" and paste the URL you copied from Duo in the field that appears.

    Example: https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/acs

  13. Leave all other fields empty.

  14. Click Save and close the "Basic SAML Configuration" editor.

    Entra ID Single Sign-On Configuration
  15. Click the pencil icon next to "Attributes & Claims".

  16. Under "Additional Claims" click ... then Delete and confirm the action next to each row and delete the four default claims.

  17. Click + Add new claim at the top of the page. Use the information in the table below to add a total of five additional claims.

    Name Namespace Source Source attribute
    Email Leave Empty Attribute user.mail
    Username Leave Empty Attribute user.userprincipalname
    FirstName Leave Empty Attribute user.givenname
    LastName Leave Empty Attribute user.surname
    DisplayName Leave Empty Attribute user.displayname
    Entra ID Single Sign-On Configure Claims
  18. After adding all five claims click the X icon at the top right-hand side to close the view.

  19. Duo Single Sign-On does not support an identity provider sending it a request. Do not click "Test" under step 5 to test your setup as it will fail.

Configure Duo Single Sign-On to use Entra ID

  1. In the "SAML Certificates" section of the properties page of your Entra SAML application, click Download next to Certificate (Base64). You will need this certificate file later.

  2. Under "Set up Duo SSO" (or whatever you named the new application) you will find metadata information to provide to Duo Single Sign-On.

  3. Return to the Duo Admin Panel and scroll down to 3. Configure Duo Single Sign-On. In the Display Name field type a name that will let you easily identify the provider.

  4. Copy the Login URL value from Entra ID and paste it into the Single Sign-On URL field in the Duo Admin Panel.

    Example: https://login.microsoftonline.com/a1b34567-890c-123d-456e-7890fg12h345/saml2

  5. Copy the Microsoft Entra Identifier value from Entra ID and paste it into the Entity ID field in the Duo Admin Panel.

    Example: https://sts.windows.net/a1b34567-890c-123d-456e-7890fg12h345/

  6. Leave Single Logout URL and Logout Redirect URL empty in the Duo Admin Panel.

  7. Upload the certificate to the Certificate section in the Duo Admin Panel.

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

  9. If you want to use encrypted assertions with Entra ID, enable Require encrypted assertion (Early Access). This is optional.

    Check the box next to Allow use of any algorithm that is supported by SAML Identity Provider configuration to allow all supported algorithms. Otherwise, uncheck the box and set the Assertion encryption algorithm to AES256-CBC and the Key transport encryption algorithm to RSA-OAEP (with fixed SHA mask). Click Download Certificate to obtain the SAML Identity Provider.crt certificate file. You will need to upload this certificate to Entra ID after saving your SAML identity provider in Duo.

  10. Click Save.

    Entra ID configuration in Duo Single Sign-On
  11. Return to the Duo SSO application in the Entra ID admin console. On the left-hand navigation bar under "Security" click Token encryption.

  12. Locate the SAML Identity Provider.crt certificate you downloaded from Duo on your computer. Change the file extension on that file from .crt to .cer, so the file is now named SAML Identity Provider.cer

    Then, click Import Certificate at the top of the Entra ID page and select the SAML Identity Provider.cer certificate file from your computer. The certificate imports with "Inactive" status.

  13. Click the three dots at the end of the row for your imported Duo certificate and select Activate token encryption certificate. Click Yes in the warning that pops up. The certificate's status changes to "Active".

  14. You are now ready to start protecting applications with Duo Single Sign-On.

Note: If you use Google Workspace (formerly known as G Suite) as your SAML IdP for Duo Single Sign-On you cannot also protect Google Workspace with Duo Single Sign-On. Additionally, Google Workspace does not support use of encrypted assertions.

Configure Duo Single Sign-On to use Google Workspace

  1. Log into your Google Workspace Admin page.

  2. While in the Admin Console click on Apps and then click on Web and mobile apps.

  3. At the top of the "Apps" table click the Add App drop-down and select Add custom SAML app. You'll be taken to a new page.

  4. On the "Apps details" page type a name that will let you easily identify the provider. Click CONTINUE.

  5. The "Google Identity Provider details" page contains the information needed to configure Duo Single Sign-On.

    Google Workspace Identity Provider Metadata
  6. In another tab return to the Duo Admin Panel and scroll down to 3. Configure Duo Single Sign-On.

  7. In the Name field type a name that will let you easily identify the provider.

  8. Copy the Entity ID value from Google and paste it into the Entity ID field in the Duo Admin Panel.

    Example: https://accounts.google.com/o/saml2?idpid=A01bcdefg

  9. Copy the SSO URL value from Google and paste it into the Single Sign-On URL field in the Duo Admin Panel.

    Example: https://accounts.google.com/o/saml2/idp?idpid=A01bcdefg

  10. Leave Single Logout URL and Logout Redirect URL empty in the Duo Admin Panel.

  11. Click the download icon button under the "Certificate" section on Google. Upload the certificate to the Certificate section in the Duo Admin Panel.

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

  13. Do not enable Assertion encryption as Google does not support it.

  14. Click Save.

    Google Workspace configuration in Duo Single Sign-On

Configure Google Workspace app for Duo Single Sign-On

  1. On the Duo Admin Panel scroll up to 1. Configure your SAML Identity Provider. This is the Duo Single Sign-On metadata information you'll need to provide to your SAML identity provider to configure Duo Single Sign-On as a service provider.

    SAML Identity Provider Metadata
  2. Return to Google and on the "Google Identity Provider details" page click CONTINUE.

  3. On the "Service Provider Details" page copy the Assertion Consumer Service URL from the Duo Admin Panel and paste it into the ACS URL field.

    Example: https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/acs.

  4. Copy the Entity ID from the Duo Admin Panel and paste it into the Entity ID field.

    Example: https://sso-abc1def2.sso.duosecurity.com/saml2/idp/RI6WF1LHX9N8GBOEPGZR/metadata.

  5. Leave Start URL empty.

  6. Check the box next to Signed response

  7. Set Name ID Format to UNSPECIFIED and click CONTINUE.

  8. Set Name ID to an attribute in Google that matches your Duo usernames.

    Google Workspace configuration
  9. On the "Attribute Mapping" click ADD MAPPING five times. New rows will appear on the page.

  10. Use the table below to add mappings onto the Google page from left to right for each row.

    Google Directory attributes App attributes
    Primary email Email
    Primary email Username
    First Name FirstName
    Last Name LastName
    First Name DisplayName
  11. Click FINISH. You'll be taken to the application's page in "Web and mobile apps".

    Google Workspace attribute mapping
  12. On the application page click the down arrow in the upper-right corner of "User access". You'll be taken to a new page.

  13. Under "Service status" click ON for everyone and click SAVE.

    Google Workspace enable app
  14. You are now ready to start protecting applications with Duo Single Sign-On.

Configure your SAML Identity Provider

  1. On the "Single Sign-On Configuration" page scroll down to 1. Configure your SAML Identity Provider. This is the Duo Single Sign-On metadata information you'll need to provide to your SAML identity provider to configure Duo Single Sign-On as a service provider.

    SAML Identity Provider Metadata
  2. Configure your SAML identity provider to:

    • Send a NameIDFormat of urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

    • Send a NameID attribute that matches your users' Duo usernames.

  3. On the "Single Sign-On Configuration" page scroll down to 2. Configure SAML Identity Provider's Attributes. Configure your SAML identity provider to send the following required attribute values. Attribute names must be sent to Duo Single Sign-On corresponding to the "Attribute Name Sent" column below:

    SAML IdP Attribute Attribute Name Sent
    Email Address Email
    Username Username
    First Name FirstName
    Last Name LastName
    Full Name DisplayName

    You may configure additional attributes to send in addition to the required attributes

  4. Continue to the next section once you've configured Duo Single Sign-On as a service provider within your SAML identity provider.

Configure Duo Single Sign-On Authentication Source

  1. On the Duo Admin Panel "Single Sign-On Configuration" page scroll down to 3. Configure Duo Single Sign-on.

  2. Fill out the fields listed below using information from your SAML identity provider:

    Name Description
    Display Name A name so that you can easily identify the provider.
    Entity ID The global, unique name for your SAML identity provider. This is provided by your SAML identity provider and is sometimes referred to as "Issuer".
    Single Sign-On URL The authentication URL for your identity provider. This is sometimes referred to as "SSO URL" or "Login URL".
    Single Logout URL This field is optional and currently unused by Duo Single Sign-On. This field my be used in the future. The logout URL for your identity provider. This is sometimes referred to as "SLO URL" or "Logout Endpoint".
    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.
    Certificate Download the signing certificate for your identity provider, and then click the Browse button to select the downloaded certificate.
    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.
    Assertion encryption (Early Access) Enable Require encrypted assertion if your SAML IdP supports it and you want to encrypt your assertions. Select the Assertion encryption algorithm and Key transport encryption algorithm compatible with your SAML identity provider using the drop-down, and then click Download Certificate to obtain the Duo encryption certificate. Upload the Duo certificate to your SAML IdP where you configured Duo SSO. Consult your identity provider's documentation for encrypted assertion support details and certificate requirements.
  3. Once all the required information is filled out click Save. You are now ready to start protecting applications with Duo Single Sign-On.

    Configuring SAML Identity Provider for Duo Single Sign-On

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.

    Default SSO Subdomain
  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.

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

Configured subdomain

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.

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

Changing an authentication 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. 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".

    Creating a Custom Bridge Attribute
  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.

Bridge Attribute Page

Create a Cloud Application in Duo

Role required: Owner, Administrator, or Application Manager

Duo has pre-configured SSO apps for many popular cloud applications. Refer to the instructions for your named application:

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:

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.

Duo Central Example

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

SAML authentication Active Directory Network Diagram
  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

SAML authentication SAML Identity Provider Network Diagram
  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

OIDC authentication Active Directory Network Diagram
  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

OIDC authentication SAML Identity Provider Network Diagram
  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

OAuth 2.0 Client Credential flow
  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.