Skip navigation

Duo Security is now a part of Cisco

About Cisco

Documentation

Duo Access Gateway for Linux

Duo Access Gateway adds two-factor authentication, complete with inline self-service enrollment and Duo Prompt, to popular cloud services like Salesforce and Google Apps using SAML 2.0 federation. The Duo Access Gateway for Linux leverages Docker's container technology, making Duo Access Gateway deployment and maintenance quick and easy.

This guide takes you through Duo Access Gateway installation and configuration on Linux. Want to host the Duo Access Gateway on Windows? See our instructions for deploying the Duo Access Gateway on Windows.

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. Duo Access Gateway acts as a SAML identity provider (IdP), authenticating your users using your existing primary authentication source for credential verification, and then prompting for two-factor authentication before permitting access to the SAML application.

Duo Access Gateway is part of the Duo Beyond, Duo Access, and Duo MFA plans.

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

Duo Access Gateway SAML Login Workflow

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

Duo Access Gateway SAML Login Workflow

Define Duo 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.

Prerequisites

Before you deploy the Duo Access Gateway for Linux, make sure to complete these requirements.

Deploy a DMZ Server

  • Deploy a physical or virtual modern 64-bit Linux server in your perimeter network (or DMZ). The minimum system requirements for the Duo Access Gateway host are:

    • Form Factor: Physical or virtual machine
    • Processor: Two processors of 2 GHz or faster
    • Memory: 4 GB RAM or greater
    • Disk Storage: 20 GB or greater
    • Operating System: See the Install Docker section of this document for supported Linux flavors and versions
  • Open ports 80 and 443 in the perimeter firewall for HTTP and HTTPS external traffic to and from the server (HTTP automatically redirects to HTTPS).

  • Port 8443 will be used for administrative purposes. Restrict traffic to this port to only authorized networks.
  • Open a port for LDAP (default 389) or LDAPS (default 636) traffic 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.
  • Purchase an SSL certificate for your server from a commercial certificate authority (CA), using the fully qualified DNS name of your Duo Access Gateway server as the common name (e.g. yourserver.example.com). You may also use a wildcard SSL certificate.

Install Docker

Docker is a tool that allows Duo Access Gateway to run inside its own self-contained environment, called a “container”, on top of your host operating system.

Click one of the tabs below to view Docker installation instructions for your Linux platform.

CentOS 7

These directions will walk you through installing the free Docker Community Edition for CentOS.

  1. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  2. Docker requires a 64-bit operating system. Please verify your installation of CentOS is 64-bit by typing:
    uname -r
    The output should contain x86_64 if the operating system is 64-bit. The output would be similar to:
    3.10.0-327.el7.x86_64
  3. Install yum-utils on your server. Type:
    sudo yum install -y yum-utils
  4. Add the Docker repository to your yum repository by typing:
    sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
    The output should be similar to:
    Loaded plugins: fastestmirror
    adding repo from: https://download.docker.com/linux/centos/docker-ce.repo
    grabbing file https://download.docker.com/linux/centos/docker-ce.repo to /etc/yum.repos.d/docker-ce.repo
    repo saved to /etc/yum.repos.d/docker-ce.repo
  5. Make sure your existing packages are up to date. This may take a few minutes. Type:
    sudo yum makecache fast
    When packages are finished updating you should see output similar to:
    Metadata Cache Created!
  6. Install wget by typing:
    sudo yum install -y wget
    When wget is finished installing you should see output similar to:
    Running transaction
      Installing : wget-1.14-13.el7.x86_64                                                                                                           1/1
      Verifying  : wget-1.14-13.el7.x86_64                                                                                                           1/1
    Installed:
      wget.x86_64 0:1.14-13.el7                                                                                                                          
    Complete!
  7. Install Docker by typing:
    sudo yum install -y docker-ce
    When Docker is finished installing you should see output similar to:
    Complete!
  8. Enable the Docker service by typing:
    sudo systemctl enable docker.service
    You should see output similar to:
    Created symlink from /etc/systemd/system/multi-user.target.wants/docker.service to /usr/lib/systemd/system/docker.service.
  9. Start the Docker daemon by typing:
    sudo systemctl start docker
  10. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  11. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  12. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  13. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Fedora 25

These directions will walk you through installing the free Docker Community Edition for Fedora.

  1. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  2. Docker requires a 64-bit operating system. Please verify your installation of CentOS is 64-bit by typing:
    uname -r
    The output should contain x86_64 if the operating system is 64-bit. The output would be similar to:
    4.8.16-300.fc25.x86_64
  3. Install dnf-plugins-core on your server. Type:
    sudo dnf -y install dnf-plugins-core
  4. Add the Docker repository to your dnf repository by typing:
    sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
    The output should be similar to:
    Adding repo from: https://download.docker.com/linux/fedora/docker-ce.repo
  5. Make sure your existing packages are up to date. This may take a few minutes. Type:
    sudo dnf makecache fast
    When packages are finished updating you should see output similar to:
    Metadata Cache Created!
  6. Install wget by typing:
    sudo dnf install -y wget
    When wget is finished installing you should see output similar to:
    Running transaction
      Installing : wget-1.14-13.el7.x86_64                                                                                                           1/1
      Verifying  : wget-1.14-13.el7.x86_64                                                                                                           1/1
    Installed:
      wget.x86_64 0:1.14-13.el7                                                                                                                          
    Complete!
  7. Install Docker by typing:
    sudo dnf install -y docker-ce
    When Docker is finished installing you should see output similar to:
    Complete!
  8. Enable the Docker service by typing:
    sudo systemctl enable docker.service
    You should see output similar to:
    Created symlink from /etc/systemd/system/multi-user.target.wants/docker.service to /usr/lib/systemd/system/docker.service.
  9. Start the Docker daemon by typing:
    sudo systemctl start docker
  10. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  11. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  12. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  13. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Ubuntu 16.04

These directions will walk you through installing the free Docker Community Edition for Ubuntu.

  1. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  2. Add the official Docker repository GPG keys to your server by typing:
    wget -O- "https://download.docker.com/linux/ubuntu/gpg" | sudo apt-key add -
    You should see output similar to:
    --2017-05-18 21:49:26--  https://download.docker.com/linux/ubuntu/gpg
    Resolving download.docker.com (download.docker.com)... 54.192.192.40, 54.192.192.99, 54.192.192.116, ...
    Connecting to download.docker.com (download.docker.com)|54.192.192.40|:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 3817 (3.7K) [binary/octet-stream]
    Saving to: ‘STDOUT’
    
    -                                 100%[==========================================================>]   3.73K  --.-KB/s    in 0s      
    
    2017-05-18 21:49:26 (956 MB/s) - written to stdout [3817/3817]
    
    OK
  3. Add the Docker repository to to your APT sources by typing:
    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
  4. Update your package database by typing:
    sudo apt-get update
    You should see output similar to:
    Reading package lists... Done
  5. Install Docker by typing:
    sudo apt-get install -y docker-ce
    You should see ouput similar to:
    Setting up cgroupfs-mount (1.2) ...
    Setting up libltdl7:amd64 (2.4.6-0.1) ...
    Setting up docker-engine (1.12.3-0~xenial) ...
    Processing triggers for libc-bin (2.23-0ubuntu3) ...
    Processing triggers for systemd (229-4ubuntu11) ...
    Processing triggers for ureadahead (0.100.0-19) ...
  6. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  7. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  8. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  9. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Debian 8.0

These directions will walk you through installing the free Docker Community Edition for Debian.

  1. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  2. Update your package database by typing:
    sudo apt-get update
    You should see output similar to:
    Reading package lists... Done
  3. Ensure that APT works with HTTPS and that CA certificates are installed. Type:
    sudo apt-get install -y apt-transport-https ca-certificates gnupg2 software-properties-common
    You should see output similar to:
    Processing triggers for libc-bin (2.19-18+deb8u7) ...
    Processing triggers for systemd (215-17+deb8u6) ...
    Processing triggers for dbus (1.8.22-0+deb8u1) ...
  4. Add the official Docker repository GPG keys to your server by typing:
    wget -O- "https://download.docker.com/linux/ubuntu/gpg" | sudo apt-key add -
    You should see output similar to:
    Resolving download.docker.com (download.docker.com)... 54.192.192.196, 54.192.192.15, 54.192.192.26, ...
    Connecting to download.docker.com (download.docker.com)|54.192.192.196|:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 3817 (3.7K) [binary/octet-stream]
    Saving to: ‘STDOUT’
    
    -                                                           100%[===========================================================================================================================================>]   3.73K  --.-KB/s   in 0s     
    
    2017-05-19 12:07:50 (374 MB/s) - written to stdout [3817/3817]
    
    OK
  5. Add the Docker repository to to your APT sources by typing:
    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
  6. Update your package database again by typing:
    sudo apt-get update
    You should see output similar to:
    Reading package lists... Done
  7. Install Docker by typing:
    sudo apt-get install docker-ce
    When the install is finished, you should see output similar to:
    Processing triggers for systemd (215-17+deb8u6) ...
    Processing triggers for initramfs-tools (0.120+deb8u2) ...
    update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
    Processing triggers for dbus (1.8.22-0+deb8u1) ...
  8. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  9. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  10. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  11. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Red Hat Enterprise Linux 7

Using Red Hat Enterprise Linux requires a paid subscription of Docker Enterprise Edition for Red Hat Enterprise Linux.
  1. Log into your Docker subscriptions page.
  2. Click the Setup button for Docker Enterprise Edition for Red Hat Enterprise Linux.
  3. On the "Setup" page make note of the URL for your subscription located under Copy and paste this URL to download your Edition. We will reference this URL later as <DOCKERURL>.

    Example: https://storebits.docker.com/ee/rhel/sub-12345-abcd-4a33-bd73-1b123c45a6b7
  4. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  5. Docker requires a 64-bit operating system. Please verify your installation of Red Hat Enterprise Linux is 64-bit by typing:
    uname -r
    The output should contain x86_64 if the operating system is 64-bit. The output would be similar to:
    3.10.0-327.el7.x86_64
  6. Store Docker URL in yum repository by typing:
    sudo sh -c 'echo "<DOCKERURL>" > /etc/yum/vars/dockerurl'
  7. Store Red Hat version in yum repository by typing:
    sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
  8. Install yum-utils on your server. Type:
    sudo yum install -y yum-utils
  9. Add the Docker repository to your yum repository by typing:
    sudo yum-config-manager --add-repo <DOCKERURL>/docker-ee.repo
    The output should be similar to:
    repo saved to /etc/yum.repos.d/docker-ee.repo
  10. Make sure your existing packages are up to date. This may take a few minutes. Type:
    sudo yum makecache fast
    When packages are finished updating you should see output similar to:
    Metadata Cache Created!
  11. Install wget by typing:
    sudo yum install -y wget
    When wget is finished installing you should see output similar to:
    Running transaction
      Installing : wget-1.14-13.el7.x86_64                                                                                                           1/1
      Verifying  : wget-1.14-13.el7.x86_64                                                                                                           1/1
    Installed:
      wget.x86_64 0:1.14-13.el7                                                                                                                          
    Complete!
  12. Install Docker by typing:
    sudo yum install -y docker-ee
    When Docker is finished installing you should see output similar to:
    Complete!
  13. Enable the Docker service by typing:
    sudo systemctl enable docker.service
    You should see output similar to:
    Created symlink from /etc/systemd/system/multi-user.target.wants/docker.service to /usr/lib/systemd/system/docker.service.
  14. Start the Docker daemon by typing:
    sudo systemctl start docker
  15. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  16. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  17. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  18. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

SUSE Enterprise Linux 12

Using SUSE Enterprise Linux requires a paid subscription of Docker Enterprise Edition for SUSE Enterprise Linux Server.
  1. Log into your Docker subscriptions page.
  2. Click the Setup button for Docker Enterprise Edition for SUSE Enterprise Linux Server.
  3. On the "Setup" page make note of the URL for your subscription located under Copy and paste this URL to download your Edition. We will reference this URL later as <DOCKERURL>.

    Example: https://storebits.docker.com/ee/sles/sub-12345-abcd-4a33-bd73-1b123c45a6b7
  4. Log into your Duo Access Gateway server locally or through SSH with a user that has sudo permissions. Any time you use the sudo command you may be prompted to enter your password.
  5. Docker requires a 64-bit operating system. Please verify your installation of SUSE Enterprise Linux is 64-bit by typing:
    uname -a
    The output should contain x86_64 if the operating system is 64-bit. The output would be similar to:
    (42e0a66) x86_64 x86_64 x86_64 GNU/Linux
  6. Add the required repository to your server by typing:
    sudo zypper addrepo <DOCKERURL>/12.3/x86_64/stable-17.03 docker-ee-stable
    The output should be similar to:
    6_64/stable-17.03 docker-ee-stable
    Adding repository 'docker-ee-stable' ..........................................................................................[done]
    Repository 'docker-ee-stable' successfully added
  7. Import the repository GPG key by typing::
    sudo rpm --import <DOCKERURL>/gpg
  8. Refresh the zypper package index by typing:
    sudo zypper refresh
  9. Install Docker by typing:
    sudo zypper -y install docker-ee
    The output should be similar to:
    (5/5) Installing: docker-ee-17.03.1.ee.3-1.x86_64 .............................................................................[done]
  10. Enable the Docker service by typing:
    sudo systemctl enable docker.service
    You should see output similar to:
    Created symlink from /etc/systemd/system/multi-user.target.wants/docker.service to /usr/lib/systemd/system/docker.service.
  11. Start the Docker daemon by typing:
    sudo service docker start
  12. Check that Docker has installed properly by typing:
    sudo docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  13. Add your user to the Docker group so Docker commands don't require sudo. Type:
    sudo usermod -aG docker $(whoami)
  14. Log out of your Duo Access Gateway box and back in for the group changes to take effect.
  15. Check that Docker is functioning without using sudo by typing:
    docker ps
    You should see output similar to:
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Install Docker Compose

  1. Download Docker Compose by typing:
    wget -O- "https://github.com/docker/compose/releases/download/1.23.1/docker-compose-$(uname -s)-$(uname -m)" > ./docker-compose
    You should see output similar to:
    Saving to: ‘STDOUT’
    100%[===========================================================================================================>] 7,986,086   43.9MB/s   in 0.2s   
    2016-12-22 13:32:15 (43.9 MB/s) - written to stdout [7986086/7986086]
  2. Change the permissions on Docker Compose to allow you to execute the file by typing:
    chmod +x ./docker-compose
  3. Move Docker Compose to your local bin folder by typing:
    sudo mv ./docker-compose  /usr/local/bin/
  4. Verify Docker Compose is working by typing:
    docker-compose --version
    You should see text similar to:
    docker-compose version 1.23.1, build b02f1306

Install Duo Access Gateway

  1. Download the Duo Access Gateway YML file and save it to your Duo Access Gateway server. Download the YML file by typing:

    wget --content-disposition https://dl.duosecurity.com/access-gateway-latest.yml

    You should see output similar to:

    --2018-03-01 14:15:16--  https://dl.duosecurity.com/access-gateway-latest.yml
    Resolving dl.duosecurity.com (dl.duosecurity.com)... 52.84.66.79, 52.84.66.236, 52.84.66.146, ...
    Connecting to dl.duosecurity.com (dl.duosecurity.com)|52.84.66.79|:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 1194 (1.2K) [application/octet-stream]
    Saving to: ‘access-gateway-1.5.6.yml’
    access-gateway-1.5.6.yml                   100%[======================================================================>]   1.17K  --.-KB/s    in 0s      
    2018-03-01 14:15:16 (124 MB/s) - ‘access-gateway-1.5.6.yml’ saved [1194/1194]
    

    Note the actual file name that was saved, you'll need this in future steps. View checksums for Duo downloads here.

    Save this YML file in a persistent directory location for future use; it will be required for later use when deploying, updating, or interacting with your Duo Access Gateway server.

  2. The following command instructs Docker Compose to download Duo Access Gateway and install it. Specify the YML file downloaded in the last step in the command. Note that your YML file name may reflect a different version than the example command shown. Replace the file name in the example with your downloaded YML file's actual name.

    Type:

    docker-compose -p access-gateway -f access-gateway-1.5.6.yml up -d

    This may take a few minutes. Once completed the text output will be similar to:

    Creating access-gateway
  3. You can verify that your Duo Access Gateway container is running by typing:

    docker ps

    You should see output showing the container with a status of "up" similar to:

    CONTAINER ID        IMAGE                                                                                                 COMMAND                  CREATED             STATUS              PORTS                                      NAMES
    3aea70b8e1a8        duosecurity/dag@sha256:36b1e3a4198c9a386830599e64c99b181095f70cdb6e42e216031377a1c83155   "bash -c /bin/run-con"   4 minutes ago       Up 4 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp   0.0.0.0:8443->8443/tcp   access-gateway

Configure Duo Access Gateway

Initial Duo Access Gateway Configuration

  1. In a browser navigate to https://URL-OF-ACCESS-GATEWAY:8443 from an internal network to log into the Duo Access Gateway admin console. Your browser warns you about an untrusted certificate the first time you access the page. Dismiss the warning and continue onto the page.

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

    Duo Access Gateway Initial Password

  3. On the "Duo Access Gateway: Internet setup" page fill in the following fields and then click Submit.

    Option Description
    Hostname Enter the fully-qualified external domain name (FQDN) of the server. This should be FQDN addressable to the Internet (eg. portal.yourcompany.com).
    Certificate Upload the certificate file you purchased earlier for the Duo Access Gateway server. The certificate should be Base64-encoded X.509 (pem, cer, or crt) and include the entire certificate bundle. The certificates should be ordered from top to bottom: certificate, issuing certificates, and root certificate.
    Private Key Upload the private key file related to the certificate you purchased earlier for the Duo Access Gateway server. Private keys should formatted as Base64-encoded X.509 (pem, cer, or crt).

    Duo Access Gateway Initial set hostname page

  4. Saving your configuration redirects you to the Duo Access Gateway admin console.

The Duo Access Gateway 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.

Duo Access Gateway Admin Console

Additionally, you'll find a link to the Duo Access Gateway 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.

Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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.
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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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.
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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway console.

Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway server). You can find this in the "Metadata" section at the bottom of the Google (OpenID Connect) authentication source configuration page in the Duo Access Gateway console.

    Duo Access Gateway 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 Duo Access Gateway admin console.

    Google OAuth Info

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

  8. Save your Google (OpenID Connect) settings. If this is your first configured authentication source, the Duo Access Gateway 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 Duo Access Gateway configuration page.

  1. Enter your Azure organization's email domain on the Duo Access Gateway Azure (OpenID Connect) authentication source configuration page as the Domain.

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

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

  4. Click on Properties in the "MANAGE" section of your Azure domain's blade.

  5. Locate the Directory ID for your Azure AD domain, copy it, and paste it into the Duo Access Gateway admin portal as the Azure Tenant ID.

    Azure AD Directory ID

  6. Click on App registrations in the "MANAGE" section of your Azure domain's blade.

  7. Click New application registration.

  8. Enter a descriptive name for the application and set the "Type" to Web app / API.

  9. Locate the Sign-On URL in the "Metadata" section at the bottom of the Microsoft Azure (OpenID Connect) authentication source configuration page in the Duo Access Gateway console. This will look like https://yourserver.example.com/dag/module.php/oidc/linkback.php, where "yourserver.example.com" is the FQDN of your Duo Access Gateway server.

    Duo Access Gateway Azure Sign-On URL

    Copy the url and paste it into Azure as the app's Sign-on URL.

    Azure App Registration

    After entering all information click Create to complete new app registration.

  10. Locate the Application ID for your newly registered app. Copy this and paste it into the Duo Access Gateway admin portal as the Azure Client ID.

    Azure Application ID

  11. Click Settings on the registered app's blade, and then click Properties in the "GENERAL" section.

  12. Copy the Sign-On URL from the Duo Access Gateway's "Metadata" section again, and paste it into Azure as the App ID URI. Click Save.

    Azure App ID URI

  13. Click Keys in the app's Settings blade's "API ACCESS" section.

  14. In the "Passwords" section of the Keys blade, enter a descriptive name for a new key to use with Duo. Then click the Duration drop-down in the "EXPIRES" column and choose your desired key lifetime. This creates a new key, but the key value is hidden until you save your changes. Click Save.

  15. The new key's value is shown after you save. Copy the VALUE and paste it into the Duo Access Gateway admin portal as the Azure Key.

    Azure Application Keys

    This is your only chance to view the key value! If you leave this blade before entering the key value into the Duo Access Gateway, then you can't view the same key's value again and you'll have to create a new one.

  16. Return to the Duo Access Gateway admin console and verify that you've entered the following information for the Azure (OpenID Connect) authentication source.

    Domain Your Azure organization's email domain.
    Tenant ID The Directory ID of your Azure Active Directory domain.
    Client ID The Application ID for the Azure registered app you created for the Duo Access Gateway.
    Key The key value from the Azure registered app you created for the Duo Access Gateway.

    Configure Azure OIDC Connection

  17. Save your Microsoft Azure (OpenID Connect) settings. If this is your first configured authentication source, the Duo Access Gateway 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 Integrating applications with Azure Active Directory.

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 Duo Access Gateway issues.

Organization Name

Internet

Change the fully-qualified hostname of the Duo Access Server, or update the SSL certificate used for HTTPS connections.

Change Internet Settings

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!

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. Duo Access Gateway 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 the SAML application's JSON file.

    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.

    Enter the following information about your cloud app vendor in the Service Provider section:

    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.
    Service Provider Login URL Enter the URL for IdP-initiated logins if your service provider specifies one.
    Default Relay State If your service provider requires a specific RelayState parameter, enter it here.

    Use your service provider's SSO instructions to complete the SAML Response section:

    Name Description
    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, Duo Access Gateway 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. Mapping or creating any additional attributes will also cause Duo Access Gateway to send all attributes.
    Signature Algorithm Select the encryption strength supported by your service provider. Defaults to SHA-256.
    Sign response Leave this option enabled if Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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 Duo Access Gateway 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. Navigate to https://URL-OF-ACCESS-GATEWAY:8443 from an internal network to log into the Duo Access Gateway admin console. 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

  4. You may want to customize the logo shown for a generic SAML application, as this logo is shown to users in the Duo Access Gateway Launcher. Duo's pre-defined SAML applications show the service provider's logo, while generic SAML apps show a Duo logo by default.

    To change the logo shown, click the Edit Logo button to the right of the SAML SP-initiated logon URL and default logo.

    Edit Generic SAML App Logo

  5. Select a PNG image to use for the generic SAML application's logo and then click Save

    Select Custom SAML App Logo

  6. Your generic SAML application now has a custom logo.

    Custom Generic SAML App Logo

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 Duo Access Gateway console's "Applications" page.

Duo Access Gateway Metadata Information

Enable the Duo Access Gateway launcher

Streamline user access to your apps by enabling the Duo Access Gateway Launcher. The Launcher provides a portal from which users can access Duo Access Gateway protected service provider applications or other non-SAML applications configured in Duo with just a click. You can even add bookmarks for organization web sites that don't use Duo authentication.

Duo Access Gateway Launcher

To use the Duo Access Gateway 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 Duo Access Gateway 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. Log in to the Duo Access Gateway console at https://URL-OF-ACCESS-GATEWAY:8443 with the administrator password and click Launcher on the left.

  4. Enter the integration key, secret key, and API hostname from the Duo Access Gateway Launcher application you created earlier and click Save Setting. This enables the launcher page URL for access.

    Add Launcher Application

  5. If you have other Duo-protected web applications that you'd like to link directly from the Duo Access Gateway launcher you can add them in the "Duo Web Applications" configuration section. These can be Duo Network Gateway pubished internal applications or any other externally accessible browser-based Duo application that shows the inline Duo prompt (like OWA, Confluence, etc.).

    Click the Add a Duo Web Application link and in the pop-up enter this information for the Duo web application you'd like to add:

    • Name: A descriptive name for the application shown to end users in the launcher. Example: "Acme Wiki"
    • URL: The URL used to access the application. Example: "https://wiki.acme.corp"
    • Logo: Choose a PNG file less than 200 KB. This logo is shown to end users in the launcher. (Optional)
    • Application: Start typing in this field to retrieve a list of the Duo applications you've already created in Duo. Click to select the Duo application you're adding to the launcher. If any group restrictions exist on the Duo application they'll affect whether a given user sees the web application tile in the launcher. Example: "Confluence"

    Add Duo Web Application

    Click the Save button when done. The web application link is added.

    Duo Web Application Added

    Repeat these steps for all Duo web applications you want to show end-users in the launcher.

  6. Provide your users with one-click shortcuts to any web application not protected by Duo by adding it as a bookmark.

    For each bookmark you'd like to add, enter this information:

    • Name: A descriptive name for the application shown to end users in the launcher. Example: "Conference Room Calendar"
    • URL: The URL used to access the application. Example: "https://rooms.acme.corp"
    • Logo: Choose a PNG file less than 200 KB. This logo is shown to end users in the launcher. (Optional)
    • Group Access: New bookmarks display to all users by default. You can use Duo groups to control which users see a bookmark. Check the Only allow access from users in certain groups box and start typing in the group selection field to retrieve a list of Duo groups. Click each group that contains the users you want to see the new bookmark in the launcher. Example: "CorpHQ_Users".

      Add Bookmark

    Click the Add button when done. The web application link is added.

    Bookmark Added

    Repeat these steps for all web application bookmarks you want to show end users in the launcher.

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

    Launcher Help Link

  8. Give your users the launcher link mentioned at the top of the page, e.g. https://yourserver.example.com/dag/launcher.php. The three different types of launcher links all display as tiles to the user.

    Based on the example information from steps 2 and 3, and knowing that the SAML applications Slack, Expensify, and G Suite were all uploaded to the Duo Access Gateway earlier, the different types of application links are shown thusly:

    Duo Access Gateway Launcher Explained

When your users access the Duo Access Gateway 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 the SAML applications you've configured for use with the Duo Access Gateway, as well as the non-SAML web applications using Duo that you added to the launcher configuration and any other web app bookmarks created.

By default, users perform Duo authentication when logging into the Duo Access Gateway launcher, and again when launching any SAML or Duo Web applications using the shortcuts in the Duo Access Gateway launcher. You can eliminate the second prompt for Duo authentication by assigning a Remembered Devices policy to the Duo Access Gateway Launcher application, to your SAML applications which has the trust-application option enabled, and to the Duo web applications you added to the launcher. With this policy, your users will not need to authenticate to Duo again when accessing an app that shares the same policy. See the Remembered 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. You can do the same thing for any Duo Web applications added to the launcher. 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 SAML Setup

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

Duo Access Gateway Login

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

Duo Access Gateway Authentication Prompt

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

Upgrading Duo Access Gateway

Upgrading Duo Access Gateway preserves all your server settings and application configurations. To perform an upgrade:

  1. Before upgrading back up your configuration.

  2. Clean up older unused Duo Access Gateway Docker images by typing:

    docker rmi $(docker images --format "{{.Repository}} {{.ID}}" | grep duosecurity | cut -f 2 -d ' ')

    Ignore any error response messages you see. You should see output similar to:

    Untagged: duosecurity/access-gateway@sha256:16d5e71a3280c11766996de561b48b283b866ec93613f1bb65490def6ff29c64
    Deleted: sha256:6893259e27b3311895279cde328012879f4e92c9823245d05adf9926fed3c0b4
    Error response from daemon: conflict: unable to delete 3627aad0d196 (cannot be forced) - image is being used by running container 2acb91f391a7
  3. Download the latest version of the Duo Access Gateway YML file by typing:

    wget --content-disposition https://dl.duosecurity.com/access-gateway-latest.yml

    You should see output similar to:

    --2018-03-01 14:15:16--  https://dl.duosecurity.com/access-gateway-latest.yml
    Resolving dl.duosecurity.com (dl.duosecurity.com)... 52.84.66.79, 52.84.66.236, 52.84.66.146, ...
    Connecting to dl.duosecurity.com (dl.duosecurity.com)|52.84.66.79|:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 1194 (1.2K) [application/octet-stream]
    Saving to: ‘access-gateway-1.5.6.yml’
    access-gateway-1.5.6.yml                   100%[======================================================================>]   1.17K  --.-KB/s    in 0s      
    2018-03-01 14:15:16 (124 MB/s) - ‘access-gateway-1.5.6.yml’ saved [1194/1194]
    

    Note the saved file name; you'll need this in future steps. View checksums for Duo downloads here.

  4. Pull down the new Duo Access Gateway image file using the YML file downloaded in the previous step. Note that your YML file name may reflect a different version than the example command shown. Replace the file name in the example with your downloaded YML file's actual name.

    Type:

    docker-compose -f access-gateway-1.5.6.yml pull
  5. Type the following command to upgrade your existing Duo Access Gateway to the new version from the YML file you downloaded:

    docker-compose -p access-gateway -f access-gateway-1.5.6.yml up -d

    Note that the new YML file names may reflect different versions than the example command shown. Replace the file name in the example with your newly downloaded YML file's actual name.

  6. The Duo Access Gateway server shuts down and starts up with the newer version; preserving your existing settings. The upgrade process is complete with no further action required. The output will look similar to:

    Recreating access-gateway

Logging

Duo Access Gateway records the following events:

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

To view the log output, log into the Duo Access Gateway server and run the following command, replacing the example Duo Access Gateway YML name with your current file's actual name:

docker-compose -p access-gateway -f access-gateway-1.5.6.yml logs -f

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

Backup and Restore

Export the container configuration from the command line to back up your Duo Access Gateway configuration.

  1. SSH into your Duo Access Gateway Docker host. Ensure your Duo Access Gateway containers are running with the docker ps command. You can't export information from stopped containers.

  2. Run the following command to export your Duo Access Gateway configuration as files into the newly-created directory data in your current location.

    docker cp access-gateway:/data data

    These files contain all your Duo Access Gateway secrets and SSL keys. Be sure to secure this data.

You'll need the full contents of the data directory restore your Duo Access Gateway configuration.

  1. SSH into the server hosting the Duo Access Gateway Docker containers. If this is a disaster recovery scenario you should run through all the initial Duo Access Gateway container installation steps, stopping when you get to the "Configure Duo Access Gateway".

  2. From the same directory that contains the exported data folder, issue this command to restore the previously exported configuration:

    docker cp data/. access-gateway:data

  3. After restoring the data contents run this command to set the proper file permissions on the restored configuration folder and files:

    docker exec -ti --user=0 access-gateway chown -R www-data:www-data /data

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 Duo Access Gateway server. You can use the Backup and Restore commands to export the Duo Access Gateway configuration from the first Linux host and then import the config into the second Linux host.

Known Issues

  • AD username format for Duo Access Gateway 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 Duo Access Gateway Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

On-premises Authentication

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

Cloud Authentication

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

Ready to Get Started?

Sign Up Free