Skip navigation
Documentation

Duo Access Gateway

Duo Access Gateway (DAG) adds two-factor authentication, complete with inline self-service enrollment and authentication prompt to popular cloud services like Salesforce and Google Apps using SAML 2.0 federation.

Overview

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

Duo provides SAML connectors for enterprise cloud applications like Google Apps, Amazon Web Services, Box, Salesforce and Microsoft Office 365. Duo Access Gateway also ships with the ability for the customer to provide their own SAML “metadata” and connect to just about any app that supports the 2.0 standard.

Protected cloud applications redirect your users to the Duo Access Gateway server on your network. Your identity provider handles primary authentication, and Duo provides secondary authentication.

The Duo Access Gateway supports local Active Directory (AD) and OpenLDAP directories as identity sources, as well as on-premises or cloud SAML IdPs.

DAG SAML Login Workflow

You can also use the Duo Access Gateway with Azure and Google directories or third-party IdPs hosted in the cloud.

DAG SAML Login Workflow

Duo Access Gateway is part of the Platform Edition, so you can define policies that enforce unique controls for each individual SSO application. For example, you can require that Salesforce users complete two-factor authentication at every login, but only once every seven days when accessing Google Apps. Duo checks the user, device, and network against an application's policy before allowing access to the application.

Installation Overview Video

 

Prerequisites

Before you start installing Duo Access Gateway, make sure to complete all these requirements decribed below.

Deploy a DMZ Server

  • Deploy a Windows Server 2012, 2012 R2, or 2016 physical or virtual server in your perimeter network (or DMZ). The server should neither be in your internal network nor joined to an Active Directory domain. Review additional security recommendations for patch management, antivirus, and user management at Microsoft TechNet.
  • Disable SSL 3.0 in IIS as described in this Duo Knowledge Base article.
  • Restrict console and RDP access to as few administrators as possible. Require strong passwords and consider two-factor authentication for remote access.
  • Open port 443 in the perimeter firewall for HTTPS external traffic to and from the server.
  • Open a port for LDAP traffic (default 389) from the server to your internal Active Directory Domain Controller(s) or OpenLDAP directory server if you are using an on-premises directory.
  • Create an Internet resolvable fully qualified DNS entry for external access (e.g. yourserver.example.com). Your users need to access the Duo Access Gateway server using that fully qualified name when logging in to cloud hosted services.

Install Internet Information Server (IIS)

  1. Launch Windows PowerShell as an administrator.

  2. Enter the command import-module servermanager to load the Server Manager PowerShell cmdlets.

  3. Enter this command to install IIS and the additional components required by the Duo Access Gateway installer.

    add-windowsfeature Web-Server, Web-Mgmt-Tools, Web-CGI, NET-Framework-Core, Web-Asp-Net45, Web-Scripting-Tools

    If you receive an error about missing source for install you may need to mount your Windows Server ISO on your server VM or insert the Windows DVD and rerun the add-windowsfeature command, appending -source D:\sources\sxs (replacing D: with the actual drive letter) to the end. See your virtualization vendor's documentation for help mounting the Windows installer ISO on your virtual server.

    IIS Installation

  4. Reboot the server if prompted.

Additional Software Requirements

Windows 10 Universal C Runtime

The Duo Access Gateway installer will also install the Visual C++ Redistributable for Visual Studio 2015 package if not present on your server. The Visual C++ Redistributable for Visual Studio 2015 package is itself dependent on the Windows 10 Universal C Runtime (CRT). Ensure that the Universal C Runtime package is installed on your server before proceeding with DAG installation.

PHP

We've tested Duo Access Gateway with PHP x64 non thread safe distribution versions 7.0.12 and greater. Older PHP versions may not be used.

Download the PHP 7.0.15 VC14 x64 Non Thread Safe zip package. You do not need to unzip the file archive, just save the file in a location you can access later during the install.

Obtain and Install an SSL Certificate

Purchase an SSL certificate for your server from a commercial certificate authority (CA), using the fully qualified DNS name of your DAG server as the common name (e.g. yourserver.example.com). You may also use a wildcard SSL certificate.

Import that certificate into the machine's Web Server or Personal certificate store and create a binding for HTTPS/443 in IIS using that certificate on the "Default Web Site".

IIS SSL Binding

Here are instructions for importing a purchased certificate into IIS from Microsoft as well as some popular commercial CAs:

Using an SSL certificate from your internal enterprise CA is not recommended, as external clients do not trust your CA by default. Your users will receive certificate errors unless they can obtain and install the full certificate chain for certificates issued by your internal CA.

Browser Settings

Verify that the browser settings on the Duo Access Gateway server allow JavaScript. For Internet Explorer users we recommend adding the HTTPS URL of your server to the "Trusted Sites" security zone, as well as https://*.duosecurity.com. Then, ensure that the security level for the Trusted Sites zone enables scripting.

Verify Web Server Functionality

Browse to https://yourserver.example.com. You should see the IIS welcome page, and not receive any certificate warnings.

Install Duo Access Gateway

The DAG installer verifies the prerequisites and exits if any are missing. If your installation fails to complete please review the prerequisites, install any missing items flagged by the DAG installer, and try again.

  1. Download the DAG installer executable from Duo and launch.

  2. If the Microsoft Visual C++ 2015 Redistibutable Package (x64) is not present on your server then the DAG setup wizard prompts you to install it.

    Duo Access Gateway Installation - Visual Studio C++ Redistributable

  3. You must specify the location of PHP. Use the Browse utility to locate and select the PHP zip file you downloaded earlier and continue with the installation.

    Duo Access Gateway Installation - PHP

    If you receive an error stating that the PHP version can not be verified, ensure that you have installed the Windows 10 Universal C Runtime prerequisite package.

    If the installer prompts you to change impersonation mode, click Yes.

    Duo Access Gateway Installation - PHP Impersonation Mode Warning

    Should you receive an additional security warning prompt asking if you want to run the unsigned php.exe file, uncheck the Always ask before opening this file option and click Run.

    Duo Access Gateway Installation - PHP Digital Signature Warning

  4. Select the fully-qualified host name from the list. Choose the one that matches the external DNS entry for your DAG server.

    Duo Access Gateway Installation - Host

    If your IIS site binding uses a wildcard certificate then the installer can't determine the hostname. Type in the fully qualified hostname (i.e. yourserver.example.com) in the space provided.

  5. By default the Duo Access Gateway administrative interface can only be accessed from the DAG server's assigned IP addresses. If you need to access the Duo Access Gateway admin console from an IP address not assigned to the DAG server's network interface(s) — such as an external IP address assigned to your DAG server by your public DNS service or a management server on your internal network — enter the additional IP addresses when prompted.

    Duo Access Gateway Installation - Host

  6. Click Install to complete Duo Access Gateway installation.

Access the Admin Console

Important: Unless you specified additional access IP addresses during installation you can only access the Duo Access Gateway admin portal from the DAG server itself after install completes. Learn how to add additional allowed IPs after installation in our FAQ.

  1. From the DAG server's console, click the Configure icon in the "Duo Access Gateway" application group to log on to https://yourserver.example.com/dag.

  2. You must choose a new admin password at initial log on.

    DAG Initial Password

The DAG admin site lists all configuration options along the left.

  • Applications: Add and remove cloud applications.
  • Authentication Source: Configure primary authentication.
  • Launcher: Enable the optional application launcher portal.
  • Settings: Change global configuration options.

DAG Admin Console

Additionally, you'll find a link to the DAG documentation page, as well as a System Information link. Click System Information to view details about your Duo Access Gateway server, such as operating system build, fully qualified hostname, and PHP version.

DAG System Information

Configure Your Authentication Source

Duo Access Gateway supports the following authentication sources:

  • Active Directory
  • OpenLDAP
  • SAML IdP
  • Google (OpenID Connect)
  • Microsoft Azure (OpenID Connect)
  1. In the DAG Admin Console, click Authentication Source. You'll notice that the Source type drop-down under Set Active Source has no options. You'll need to configure and save an authentication source before you can set one as active. Your first configured authentication source is automatically set as your active source.

  2. In the Configure Sources section, select your desired Source type from the drop-down and enter your configuration settings.

Active Directory

Server The hostname or IP address of your domain controller. If entering more than one domain controller prefix the DC hostname or IP address with ldap:// and separate the entries with commas, for example ldap://dc1.acme.corp,ldap://dc2.acme.corp.
Port Enter the port used to communicate with Active Directory. The default port for LDAP and STARTTLS is 389, while the default port for LDAPS is 636. To search the Global Catalog the default port is 3268.
Transport type This determines how the connection between the Duo Access Gateway and the Active Directory server is encrypted. The default, CLEAR, is unencrypted. Select STARTTLS or LDAPS to encrypt LDAP authentication traffic.
AD Certificate To use STARTTLS or LDAPS encryption you’ll need the certificate from your domain controller certificate’s issuing CA. To obtain the PEM formatted version of the AD domain controller certificate’s issuing CA, 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. If you have an intermediate CA export all the certs (such as root CA and intermediate CA) in the certification path and combine them into one file using a text editor. Copy the certificate file to the DAG server; then click the Browse button to select the exported certificate.
Attributes Enter the AD user attributes required for SSO login. Many cloud service providers use the mail or sAMAccountname attributes. Check your service provider's SSO documentation for the specific attributes required. If you do not enter any attributes in this field, then Duo retrieves all user attributes. This is not recommended as it may negatively impact performance.
Search base Enter the DN that corresponds to a container or OU in your directory structure containing the user accounts for SSO. You can enter multiple DNs in this field, one per line. Example DNs: CN=Users,dc=acme,dc=corp (searches the built-in Users container), OU=Employees,OU=US,DC=acme,DC=corp (searches within an organizational unit hierarchy), OU=Users,DC=EMEA,DC=acme,DC=corp (searches an OU in a child domain)
Search attributes Enter the AD attributes that match the cloud application SSO username. These attributes must be included in the Attributes list above.
Search username Enter the NTLM formatted username (e.g. DOMAIN\User) of an AD domain account that has permission to bind to Active Directory and perform LDAP queries.
Search password Enter the password for the search username account.

Configure AD Connection

Save your Active Directory settings. If this is your first configured authentication source, the DAG sets this as your active source and contacts the domain controller using the provided information. If this is not your first configured authentication source you'll need to set this one as the active source using the dropdown under Set Active Source to test connectivity.

If you do not see a "Bind Succeeded" message please double-check your configuration information and verify the DAG server has the necessary connectivity to your domain controllers.

AD Bind Success

OpenLDAP

Server The comma-separated hostname(s) of your LDAP directory server(s).
Port Enter the port used to communicate with OpenLDAP. The default port for LDAP and STARTTLS is 389, while the default port for LDAPS is 636.
Transport type This determines how the connection between the Duo Access Gateway and the OpenLDAP server is encrypted. The default, CLEAR, is unencrypted. Select STARTTLS or LDAPS to encrypt LDAP authentication traffic.
Certificate To use STARTTLS or LDAPS encryption you’ll need the certificate from your OpenLDAP directory server certificate’s issuing CA. If you have an intermediate CA export all the certs (such as root CA and intermediate CA) in the certification path and combine them into one file using a text editor. Copy the certificate file to the DAG server; then click the Browse button to select the exported certificate.
Attributes Enter the OpenLDAP user attributes required for SSO login. Many cloud service providers use the mail or uid attributes. Check your service provider's SSO documentation for the specific attributes required. If you do not enter any attributes in this field, then Duo retrieves all user attributes. This is not recommended as it may negatively impact performance.
Search base Enter the DN that corresponds to a container or OU in your directory structure containing the user accounts for SSO. You can enter multiple DNs in this field, one per line. Example DNs: ou=Employees,ou=US,dc=acme,dc=corp (searches within an organizational unit hierarchy), dc=acme,dc=corp (searches the entire domain)
Search attributes Enter the LDAP attributes that match the cloud application SSO username. These attributes must be included in the Attributes list above.
Search username Enter the dn of an OpenLDAP service account that has permission to bind to the directory and perform LDAP queries. Example service account DN: uid=ldapuser,ou=SvcAccts,dc=acme,dc=corp
Search password Enter the password for the search username account.

Configure OpenLDAP Connection

Save your OpenLDAP settings. If this is your first configured authentication source, the DAG sets this as your active source and contacts the directory server using the provided information. If this is not your first configured authentication source you'll need to set this one as the active source using the dropdown under Set Active Source to test connectivity.

If you do not see a "Bind Succeeded" message please double-check your configuration information and verify the DAG server has the necessary connectivity to your directory.

LDAP Bind Success

SAML IdP

Entity ID The global, unique name for your SAML entity. This is provided by your primary authentication identity provider.
Single sign-on URL The authentication URL for your identity provider.
Single logout URL The logout URL for your identity provider.
Certificate Download the token signing certificate for your identity provider, and then click the Browse button to select the exported certificate.
Username Attribute The DAG uses the NameID SAML attribute as the username default. If you need to use a different username attribute, check the box next to the "Specify an alternate SAML username attribute instead of NameID" option, and type in your username attribute in the space provided.

Configure SAML IdP Connection

Save your SAML IdP settings.

SAML Configuration Success

If this is your first configured authentication source, the DAG sets this as your active source. If this is not your first configured authentication source you'll need to set this one as the active source using the dropdown under Set Active Source.

You'll need to ensure that your SAML IdP passes these attributes in its responses to the Duo Access Gateway:

IdP Attribute DAG Attribute
Email Address mail
Username sAMAccountName
First Name givenName
Last Name sn

You will also need to provide some information about your Duo Access Gateway server to your SAML IdP provider. You can find this information in the "Metadata" section at the bottom of the SAML IdP authentication source configuration page in the DAG console.

DAG SAML IdP Metadata

Google (OpenID Connect)

Before you can configure Google OpenID Connect as an authentication source you'll need to create an OAuth project in Google and collect some information to input into the DAG configuration page.

  1. Log in to the Google Developers Console as an administrator for your Google Apps account.

  2. If you do not already have an active project, click the Create Project button to create a new one. Give the new project a name and click Create. The page refreshes after creating your new project. You can also use an existing project.

  3. Click the Enable and manage APIs link on the Dashboard. Once in the API Manager, click Credentials on the left, then click the Create credentials button and select OAuth client ID from the list.

    Add Google OAuth

  4. If you created a new project you may need to first click Configure consent screen and enter a Product Name on the "OAuth consent screen" properties page. Click Save to return to the "Create client ID" page.

    Google OAuth Consent

  5. On the "Create client ID" page select Web application. Enter a descriptive Name for the new web client ID, and then enter the redirect URI for your Duo Access Gateway server (for example, https://yourserver.example.com/dag/module.php/oidc/linkback.php, replacing "yourserver.example.com" with the FQDN of your DAG server). You can find this in the "Metadata" section at the bottom of the Google (OpenID Connect) authentication source configuration page in the DAG console.

    DAG Google Redirect URI

    After pasting in the information click Create.

    Create Google Client ID

  6. Make note of your client ID and client secret values. You'll need to enter these in the DAG admin console.

    Google OAuth Info

Return to the Duo Access Gateway admin console and enter the following information for the Google (OpenID Connect) authentication source.

Domain|Enter your organization's Google Apps domain.
Client ID|Enter the Google OAuth web application client ID from the Google Developers Console.
Client Secret|Enter the Google OAuth web application client secret from the Google Developers Console.

Configure Google OIDC Connection

Save your Google (OpenID Connect) settings. If this is your first configured authentication source, the DAG sets this as your active source. If this is not your first configured authentication source you'll need to set this one as the active source using the dropdown under Set Active Source.

Google OIDC Configuration Success

For more information about Google OpenID Connect and Google's OAuth 2.0 APIs please see Google's OpenID Connect guide.

Microsoft Azure (OpenID Connect)

In order to use the Duo Access Gateway with Azure Active Directory the Azure domain must be synced with an on-premises Active Directory domain so that the "mail" attribute is populated, or the Azure domain users must be provisioned with an Office 365 email address.

Before you can configure Azure OpenID Connect as an authentication source you'll need to create an Azure Active Directory web application in Azure and collect some information to input into the DAG configuration page.

  1. Log in to the Microsoft Azure Administrator console as an Azure AD administrator.

  2. Click Active Directory on the left and then click on the Azure Active Directory domain you want to use with the Duo Access Gateway.

  3. Click APPLICATIONS under the name of your Azure AD domain near the top of the page, and then click the ADD button near the bottom center of the page.

  4. When asked, "What do you want to do?" click Add an application my organization is developing to go to the next page.

  5. Enter a descriptive name for the application and set the "Type" to WEB APPLICATION AND/OR WEB API. Click the arrow in the lower right to continue.

    Azure App Properties

  6. Enter the redirect URI for your Duo Access Gateway server (for example, https://yourserver.example.com/dag/module.php/oidc/linkback.php, replacing "yourserver.example.com" with the FQDN of your DAG server) as both the SIGN-ON URL and APP ID URI. You can find this in the "Metadata" section at the bottom of the Microsoft Azure (OpenID Connect) authentication source configuration page in the DAG console.

    DAG Azure Sign-On URL

    After pasting in the information click the check icon to complete new app creation.

    Azure App Properties

  7. Click on your newly created Azure AD application (the new application's information may be displayed to you automatically after creation). Click CONFIGURE under the name of your new application near the top of the page.

  8. Scroll down the application configuration page to the keys section. Under "keys" click the Select duration drop-down and choose your desired duration. This creates a new key, but the key value is hidden until you save your changes. Click SAVE near the bottom center of the page.

    Azure Application Info

  9. The new key value is shown after you save. This is your only chance to view the key value! Be sure to copy it now; you'll need to enter it into the DAG admin console.

    Scroll up slightly to view your CLIENT ID. You'll need to enter that into the DAG admin console as well.

    Azure Application Keys

  10. The final piece of information you'll need is your Azure tenant ID. While the tenant ID isn't directly viewable in the Azure AD console, you can extract it from the URL of your Azure AD directory management console.

    For example, if the URL shown in your browser when you are viewing your Azure AD directory in the portal is:

    https://manage.windowsazure.com/@acmecorp.onmicrosoft.com#Workspaces/ActiveDirectoryExtension/Directory/01ab012c-0ab1-1ba0-a012-123456abcd01/directoryQuickStart

    Your tenant ID would be the portion of the URL between "Directory/" and "/directoryQuickStart" — 01ab012c-0ab1-1ba0-a012-123456abcd01

Return to the Duo Access Gateway admin console and enter the following information for the Azure (OpenID Connect) authentication source.

Domain Enter your Azure organization's email domain.
Tenant ID Enter the tenant ID of your Azure Active Directory (extracted from the Azure AD management console URL).
Client ID Enter the CLIENT ID for the Azure application you created for the Duo Access Gateway.
Key Enter the key value from the Azure application you created for the Duo Access Gateway.

Configure Azure OIDC Connection

Save your Microsoft Azure (OpenID Connect) settings. If this is your first configured authentication source, the DAG sets this as your active source. If this is not your first configured authentication source you'll need to set this one as the active source using the dropdown under Set Active Source.

Azure OIDC Configuration Success

For more information about Microsoft Azure apps please see the MSDN Developer Network.

Additional Settings

Fail Mode

The fail mode determines whether to permit or deny user logons if the Duo Access Gateway is unable to contact Duo’s service. If the fail mode is safe, users who successfully pass primary authentication may access the cloud application without completing two-factor authentication. If the fail mode is secure then all user authentication attempts are rejected.

Fail Mode

Session Management

Session binding has two options, IP address binding and User agent binding.

Enabling the IP address binding option associates an authenticated Duo Access Gateway session to the client's IP address. Once users authenticate to a Duo protected cloud service they are not prompted again for primary authentication until the session lifetime is reached or the client's IP address changes. Users do not need to reauthenticate when their client IP changes if this setting remains disabled.

The User agent binding option associates an authenticated Duo Access Gateway session to the client browser's reported user agent (the information that identifies the browser type and version to web servers). By default, users need to reauthenticate if their reported browser information changes. Disable this option if you do not want users to reauthenticate to the Duo Access Gateway if their browser User-Agent changes after initial authentication.

The Session duration setting defines the maximum lifetime of a user's SSO session.

Session Management

General

The Duo Access Gateway end-user logon page displays the Organization Name you enter here within the text of the primary authentication prompt.

Enable the Verbose logging option when troubleshooting DAG issues.

Organization Name

Change Admin Password

Set a new administrator password. We require a strong password that uses a mix of uppercase and lowercase letters, numbers, and special characters.

Change Admin Password

Create a Cloud Application in Duo

Important: When you create your cloud application in Duo you download a configuration file. This file contains information that uniquely identifies this application to Duo. Secure this file as you would any other sensitive or password information. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

Limit unauthorized access to the cloud application configuration file by using a console browser session to download the file directly to the Access Gateway Server.

Duo has pre-configured SAML configurations for many popular cloud applications, like Salesforce, Google Apps, and Amazon Web Services.

We've mapped the most common authentication source attributes as follows:

Duo Attribute Active Directory OpenLDAP SAML IdP Google Azure
Mail attribute mail mail mail email mail
First name attribute givenName gn givenName given_name givenName
Last name attribute sn sn sn family_name surname
Username attribute sAMAccountName uid sAMAccountName email mail

If your configured authentication source uses a different attribute than these mapped defaults, you'll have the opportunity to change it when creating the service provider application in Duo.

To provision one of the Duo supported service providers:

  1. Log in to the Duo Admin Panel and click Applications on the left navigation tab. Then click Protect an Application.

  2. Choose your cloud service from the list of applications. DAG supported cloud apps prefix the name with "SAML - ", such as "SAML - Salesforce" or "SAML - Zendesk". Click the Protect this Application link underneath your cloud service application's name.

    Add a SAML Application

  3. Some Duo SAML applications require you to input additional information from your service provider to complete the application's configuration. Refer to the instructions for your cloud service for more information about the specific information required. Additionally, if your authentication source isn't using the Duo default attributes you can customize the attribute mapping.

    Example SP Configuration

    When all required information for the service provider is entered (or if you made no changes), click the Save Configuration button.

  4. Saving the service provider configuration creates a configuration file that you will import to the Duo Access Gateway. Click the Download your configuration file link to download JSON file to the DAG server.

    Download JSON File

You can also create a generic SAML Service Provider application in Duo, which requires you to input information about your cloud application. You will need to enter the following information supplied by the service provider.

Name Description
Service Provider Name The name of the service provider.
Entity ID The service provider identifier.
Assertion Consumer Service The URL where your service provider receives SAML assertions.
NameID format Format of NameID when sent to the service provider.
NameID attribute The authentication source attribute used to identify the user to the service provider. This attribute is sent as the NameID. This is often a user's e-mail address ("mail" or "email").
Send attributes By default the DAG sends only the NameID IdP attribute to a service provider. Change this option to "All" if your service provider requires additional attributes included in the SAML response.
Sign response Leave this option enabled if the DAG needs to sign the SAML response to the service provider. Uncheck the box if the response should not be signed.
Sign assertion Leave this option enabled if the DAG needs to sign the SAML assertion to the service provider. Uncheck the box if the assertion should not be signed.
Map attributes If your service provider requires specific names for the attributes sent by the DAG identity provider, you can map the authentication source attributes to the required names here. Enter the attribute name from your authentication source on the left, and the new attribute name on the right. Consult your service provider's documentation for the required attribute names.
Create attributes If your service provider requires that the DAG identity provider sends an attribute with a specific value, you can define that here. Enter the new attribute name on the left, and the static attribute value on the right. Consult your service provider's documentation for the required attribute names.

Here's an example generic SAML Service Provider configuration

Generic SAML Provider

After entering the service provider information click the Save Configuration button and download the configuration file.

Generic SAML Provider Download

If your service provider requires IdP-initiated logins using SSO, the login URL is composed of the URL to your DAG logon page plus the entity id of the service to which you are authenticating, e.g. https://yourserver.example.com/dag/saml2/idp/SSOService.php?spentityid=Your_SP_Entity_ID.

Add a Cloud Application to Duo Access Gateway

  1. From the DAG server's console, click the Configure icon in the "Duo Access Gateway" application group to log on to https://yourserver.example.com/dag. Log in with the administrator password and click Applications.

  2. Click the Choose File button in the "Add Application" section of the page and locate the SAML application JSON file you downloaded from the Duo Admin Panel earlier. Click the Upload button after selecting the JSON configuration file.

    Upload Service Provider JSON

  3. The new SAML application is added.

    Upload Service Provider JSON

Configure your Service Provider

You'll need to make some changes in your cloud application to add Duo Access Gateway authentication. Refer to our service provider configuration guides.

If you're adding Duo protection to another cloud application using the our generic SAML Service Provider application, check with the service provider for SSO instructions. You'll need to provide some information about Duo Access Gateway to that service provider, like URL information, a metadata file, a certificate file, or a certificate thumbprint. You can find this information in the "Metadata" section at the bottom of the DAG console's "Applications" page.

DAG Metadata Information

Enable the DAG launcher

Streamline user access to your apps by enabling the DAG Launcher. The Launcher provides a portal from which users can access your Duo Access Gateway protected service provider applications with just a click.

DAG Launcher

To use the DAG Launcher, you'll need to create a specific application in the Admin Panel, just like you do for a service provider, and then use that information to configure the Launcher application in the DAG console.

  1. Log in to the Duo Admin Panel and click Applications on the left navigation tab. Then click Protect an Application.

  2. Choose Duo Access Gateway Launcher from the list of applications. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)

  3. From the DAG server's console, click the Configure icon in the "Duo Access Gateway" application group to log on to https://yourserver.example.com/dag. Log in with the administrator password and click Launcher.

  4. Enter the integration key, secret key, and API hostname from the Duo Access Gateway Launcher application you created earlier and click Save Setting.

  5. You can optionally change Text of the the "Need help?" or the URL destination so that it points to a web page of your choosing instead of the Duo end user documentation. If you customize the help link, be sure to click Save Settings.

  6. Give your users the launcher link mentioned at the top of the page.

    DAG Metadata Information

When your users access the DAG launcher they'll first log in with their primary credentials, and then complete Duo two-factor authentication. After that users see a list of all SAML applications you've configured for use with the DAG.

By default, users perform Duo authentication when logging into the DAG launcher, and again when launching any SAML applications using the shortcuts in the DAG launcher. You can eliminate the second prompt for Duo authentication by assigning a Trusted Devices policy to the Duo Access Gateway Launcher application and to your SAML applications which has the trust-application option enabled. With this policy, your users will not need to authenticate to Duo again when accessing an app that shares the same policy. See the Trusted Devices policy documentation for details.

You can also restrict which application links display for a given user in the launcher. When creating your SAML service provider application in the Duo Admin Panel, populate the Permitted groups field with the Duo groups that contain the users you want to access that application. When a user who is not a member of the specified group(s) logs in to the launcher, the applications which have group restrictions are not shown. See the Using Groups documentation for more information and detailed instructions.

Test Your Setup

To verify your setup, log on to your configured cloud service provider. You'll be redirected to the Duo Access Gateway login page.

DAG Login

Enter your primary username and password. The Duo authentication prompt appears after successful primary authentication.

DAG Authentication Prompt

Approving the Duo authentication request completes login to the cloud application.

Upgrading the Duo Access Gateway

To upgrade the Duo Access Gateway, simply download the new version installer and run it on your deployed DAG server. The upgrade install automatically preserves your current DAG configuration.

If you are upgrading the Duo Access Gateway to version 1.3.1 from an earlier version you'll also need to update PHP to 7.0.12 or later. Download PHP as instructed for DAG installation, and when running the DAG 1.3.1 installer browse to the downloaded ZIP file. The DAG installer will take care of upgrading the PHP version you were using with the previous DAG version, and then continue upgrading Duo Access Gateway to 1.3.1.

If you are upgrading from DAG 1.1 and you plan on changing your authentication source from Active Directory to something different, you'll need to re-download the JSON configuration files for all your existing service provider applications from the Duo Admin Panel and upload the new JSON files into the Duo Access Gateway after the upgrade.

You won't be able to switch the authentication source to anything other than Active Directory until you import the new JSON files. You'll also receive an error if you do switch authentication sources and then try to upload a legacy JSON file that does not support your new authentication source.

If you will continue using Active Directory as your authentication source there is no need to update the service provider JSON files.

Upgrading PHP

After deploying Duo Access Gateway in your environment you may later wish to upgrade the PHP version used by DAG. You can accomplish this with our standalone PHP updater tool. See the DAG FAQ for details.

Logging

Duo Access Gateway records the following events at C:\inetpub\wwwroot\dag\log\dag.log:

  • Administrator console logons
  • Primary user authentication success and failure
  • Secondary user authentication success
  • Errors

To enable debug output to the existing dag.log file, navigate to Settings in the DAG admin console. Scroll down to the "General" section and check the box next to Debugging. Click Save Changes when done.

High Availability

We recommend deploying a second Duo Access Gateway server with the same configured SAML applications to serve as a standby replacement for the primary DAG server.

  1. Deploy your standby DAG server, making sure to give it the same host name or CNAME alias as your primary DAG server, as the hostname entered during the DAG install cannot be changed later. Use the same IIS SSL certificate on both the primary and standby servers.

  2. Copy the configured settings file C:\inetpub\wwwroot\dag\config\config.json from the primary DAG server to the DAG standby.

  3. Copy the authentication source configuration .json file(s) in C:\inetpub\wwwroot\dag\config\authsources from the primary DAG server to the DAG standby.

  4. Copy all .pem and .crt certificate files in C:\inetpub\wwwroot\dag\cert from the primary DAG server to the standby. There may be an ldap subfolder; copy this as well.

  5. Copy the saml20-idp-hosted.json and saml20-idp-remote.json files in C:\inetpub\wwwroot\dag\metadata (if they exist) from the primary DAG server to the DAG standby.

  6. Copy the imported service provider application JSON files in C:\inetpub\wwwroot\dag\metadata\saml20-sp-remote from the primary DAG server to the DAG standby.

If your primary DAG server is unavailable, you can activate your standby server to process user authentications.

You can also configure a load balancer in front of two identically configured DAG servers for active/active or active/passive high availability. In this scenario we recommend 8 hour persistence to match the lifetime of the Duo session cookie. Consult your load balancer solution documentation for guidance.

Known Issues

  • AD username format for DAG primary logon must be entered as sAMAccountName ("username") or email/userPrincipalName ("username@example.com"). NTLM logon ("DOMAIN\username") is not supported at this time.

  • SP user provisioning is not supported at this time.

  • Authentication sources other than Active Directory do not provide group membership information to the Duo Access Gateway. Therefore, these authentication sources cannot be used with service providers that verify group membership to provide access, such as Amazon Web Services or Meraki.

Troubleshooting

Need some help? Take a look at the Duo Access Gateway Frequently Asked Questions (FAQ) page or try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

On-premises Authentication

  1. Service Provider to DAG connection initiated
  2. Primary authentication to on-premises directory or IdP
  3. DAG connection established to Duo Security over TCP port 443
  4. Secondary authentication via Duo Security’s service
  5. DAG receives authentication response
  6. Service Provider session authenticated

Cloud Authentication

  1. Service Provider to DAG connection initiated
  2. Primary authentication to cloud directory or IdP
  3. DAG connection established to Duo Security over TCP port 443
  4. Secondary authentication via Duo Security’s service
  5. DAG receives authentication response
  6. Service Provider session authenticated

Ready to Get Started?

Sign Up Free