Skip navigation
Documentation

Duo Authentication Proxy - Reference

Last Updated: July 25th, 2024

Many of Duo's application integrations do not require any local components. However, certain services do require a local Authentication Proxy service. This document contains a comprehensive reference of configuration options available for the proxy.

Note

Quick-start guides for installing and configuring the proxy can be found in each of the specific application documentation pages (e.g. Cisco ASA, NetScaler, or F5) and the generic instructions for RADIUS or LDAP. We recommend starting with the instructions for your device or use case, and then using this page if you need advanced configuration options to support your device or service.

Overview

The Duo Authentication Proxy is an on-premises software service that receives authentication requests from your local devices and applications via RADIUS or LDAP, optionally performs primary authentication against your existing LDAP directory or RADIUS authentication server, and then contacts Duo to perform secondary authentication. Once the user approves the two-factor request (received as a push notification from Duo Mobile, or as a phone call, etc.), the Duo proxy returns access approval to the requesting device or application.

Connectivity Requirements

The Authentication Proxy communicates with Duo's service on TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review this Duo KB article.

In addition to providing two-factor authentication, the Duo Authentication Proxy is a required component for importing Active Directory or OpenLDAP users into Duo via sync, Active Directory authentication for Duo Single Sign-On, and can also act as an HTTP proxy itself for other systems that also need to contact Duo's cloud service.

Installation

Authentication Proxy Performance Recommendations

Use this guidance as you design your Authentication Proxy server deployment.

Operating System Authentication Rate
Linux deployment (maximum performance) 2000 authentications per minute
Windows deployment 1000 authentications per minute

Note that use of LDAP or TLS on Linux decreases the authentication rate by 250 auths/minute on each side. For example, the effective authentication rates for various combinations on a Linux server will be:

Linux Proxy Configuration Effective Authentication Rate
RADIUS primary + RADIUS secondary 2000 authentications per minute
LDAP primary + RADIUS secondary 1750 authentications per minute
LDAP primary + LDAPS secondary 1250 authentications per minute
LDAPS primary + LDAPS secondary 1000 authentications per minute

The Authentication Proxy performance testing used Amazon Web Services (AWS) m4(Intel(R) Xeon(R) CPU E5-2686 v4) instances.

We encourage you to balance security with performance and not opt for less-secure authentication configurations (such as plain LDAP without TLS) to gain a performance boost.

The Authentication Proxy processes are mostly CPU-bound. If you suspect performance issues then check your single-core CPU usage and consider horizontal scaling if this core usage is high.

Newer CPUs generally improve the authentication, but adding more CPU cores does not improve performance due to the single-threaded nature of Python.

Consider using load balancers when your expected authentication rates exceed the maximum stated for your Authentication Proxy operating system and your intended authentication configuration. The Authentication Proxy does not natively support load balancing and treats each load balancer node as a standard client/server, so the authentication rate does not change for an individual Duo proxy server.

New Proxy Install

We recommend the following operating systems for the system hosting the Duo Authentication Proxy:

  • Windows Server 2016 or later
  • CentOS 7
  • CentOS Stream 8 or later
  • Fedora 37 or later
  • Red Hat Enterprise Linux 7 or later
  • Ubuntu 20.04 LTS or later
  • Debian 11 or later

The Duo End of Sale, Last Date of Support, and End of Life Policy states that Duo does not offer support for integrations running on operating system versions beyond the vendor’s stated Last Date of Support date.

If you will reuse an existing Duo Authentication Proxy server for this new application, you can skip the install steps and go to Configure the Proxy.

The Duo Authentication Proxy can be installed on a physical or virtual host. We recommend a system with at least 1 CPU, 200 MB disk space, and 4 GB RAM (although 1 GB RAM is usually sufficient). See additional Authentication Proxy performance recommendations in the Duo Authentication Proxy Reference.

We do not recommend installing the Duo Authentication Proxy on the same Windows server that acts as your Active Directory domain controller or one with the Network Policy Server (NPS) role. If you must co-locate the Duo Authentication Proxy with these services, be prepared to resolve potential LDAP or RADIUS port conflicts between the Duo service and your pre-existing services.

  1. Download the most recent Authentication Proxy for Windows from https://dl.duosecurity.com/duoauthproxy-latest.exe. Note that the actual filename will reflect the version e.g. duoauthproxy-6.4.1.exe. View checksums for Duo downloads here.
  2. Launch the Authentication Proxy installer on the target Windows server as a user with administrator rights and follow the on-screen prompts.

    When installing, you can choose whether or not you want to install the Proxy Manager. The Proxy Manager is a Windows utility that helps you edit the Duo Authentication Proxy configuration, determine the proxy's status, and start or stop the proxy service. Learn more about using the Proxy Manager. Installing the Proxy Manager adds about 100 MB to the installed size.

    If you do not want to install the Proxy Manager, you may deselect it on the "Choose Components" installer screen before clicking Install.

Silent Install

To perform a silent install on Windows, issue the following from an elevated command prompt after downloading the installer (replacing version with the actual version you downloaded):

duoauthproxy-version.exe /S

Append /exclude-auth-proxy-manager to install silently without the Proxy Manager:

duoauthproxy-version.exe /S /exclude-auth-proxy-manager
  1. Ensure that Perl and a compiler toolchain are installed. On most recent RPM-based distributions — like Fedora, Red Hat Enterprise, and CentOS — you can install these by running (as root):

    $ yum install gcc make libffi-devel perl zlib-devel diffutils

    On Debian-derived systems, install these dependencies by running (as root):

    $ apt-get install build-essential libffi-dev perl zlib1g-dev

    If SELinux is present on your system and you want the Authentication Proxy installer to build and install its SELinux module, include selinux-policy-devel and chkconfig in the dependencies:

    $ yum install gcc make libffi-devel perl zlib-devel diffutils selinux-policy-devel chkconfig
    $ apt-get install build-essential libffi-dev perl zlib1g-dev selinux-policy-devel chkconfig
  2. Download the most recent Authentication Proxy for Unix from https://dl.duosecurity.com/duoauthproxy-latest-src.tgz. From the command line you can use curl or wget to download the file, like $ wget --content-disposition https://dl.duosecurity.com/duoauthproxy-latest-src.tgz. Depending on your download method, the actual filename may reflect the version e.g. duoauthproxy-6.4.1-src.tgz. View checksums for Duo downloads here.

  3. Extract the Authentication Proxy files and build it as follows:

    $ tar xzf duoauthproxy-6.4.1-src.tgz
    $ cd duoauthproxy-version-src
    $ make
  4. Install the authentication proxy (as root):

    $ cd duoauthproxy-build
    $ ./install

    Follow the prompts to complete the installation. The installer creates a user to run the proxy service and a group to own the log directory and files. You can accept the default user and group names or enter your own.

    If SELinux is present on the target server, the Duo installer will ask you if you want to install the Authentication Proxy SELinux module. Your selection affects whether systemd can start the Authentication Proxy after installation.

    If you choose to install the Authentication Proxy SELinux module and the dependencies selinux-policy-devel and chkconfig are not present, then the installer fails to build the module.

    SELinux Mode Default Response Result
    Enforcing Yes Choose 'yes' to install the Authentication Proxy's SELinux module. This permits start of the Authentication Proxy service by systemd. If you choose 'no' then the SELinux module is not installed, and systemd cannot start the Authentication Proxy service.
    Permissive No Choose 'no' to decline install of the Authentication Proxy's SELinux module. The Authentication Proxy service can be started by systemd. However, if you change SELinux from permissive to enforcing mode after installing the Duo proxy, systemd can no longer start the Authentication Proxy service. If you plan to enable SELinux enforcing mode later, you should choose 'yes' to install the Authentication Proxy SELinux module now.
Silent Install

To install the Duo proxy silently with the default options, use the following command:

sudo ./duoauthproxy-build/install --install-dir /opt/duoauthproxy --service-user duo_authproxy_svc --log-group duo_authproxy_grp --create-init-script yes

Append --enable-selinux=yes|no to the install command to choose whether to install the Authentication Proxy SELinux module.

You need to add your authentication and application information to the default configuration file before you can start the Duo Authentication Proxy service.

Upgrading the Proxy

To upgrade the Duo Authentication Proxy, simply download the most recent version and install over your current running version. The installer preserves your current configuration (including password and secret encryption on Windows) and log files when upgrading to the latest release. Consider making a backup copy before running the upgrade, securing it as you would your running config file (as the backup file will also contain your passwords and secrets). The relevant directories are:

Operating System Authentication
Proxy Version
Path
Windows v5.0.0 and later C:\Program Files\Duo Security Authentication Proxy\conf and C:\Program Files\Duo Security Authentication Proxy\log
Windows v4.0.2 and earlier C:\Program Files (x86)\Duo Security Authentication Proxy\conf and C:\Program Files (x86)\Duo Security Authentication Proxy\log
Linux All /opt/duoauthproxy/conf and /opt/duoauthproxy/log

Duo Authentication Proxy 5.0.0 is the first 64-bit release for Windows. When upgrading from older 32-bit releases to 5.0.0 or later, the installer migrates the contents of your existing conf and log directories to the 64-bit installation destination at C:\Program Files\Duo Security Authentication Proxy\ and removes the C:\Program Files (x86)\Duo Security Authentication Proxy directory.

  1. Download the most recent Authentication Proxy for Windows from https://dl.duosecurity.com/duoauthproxy-latest.exe. Note that the actual filename will reflect the version e.g. duoauthproxy-6.4.1.exe. View checksums for Duo downloads here.

  2. Launch the Authentication Proxy installer as a user with administrator rights (close the Event Viewer first if you have it open) and follow the prompts to update your existing Authentication Proxy software. The upgrade retains the conf and log folders and contents from your current installation.

    Before upgrading, you can choose whether or not you want to install the Proxy Manager. The Proxy Manager is a Windows utility that helps you edit the Duo Authentication Proxy configuration, determine the proxy's status, and start or stop the proxy service. Learn more about using the Proxy Manager. Installing the Proxy Manager adds about 100 MB to the installed size.

    If you do not want to install the Proxy Manager, you may deselect it on the "Choose Components" installer screen before clicking Install.

    Note: If you previously changed the properties of the "Duo Security Authentication Proxy Service" to run as a named domain account, be aware that the service will revert to running as "Local System" after the upgrade. Repeat the process to change the service back to using a named domain service account before starting the service.

  3. If the Duo Authentication Proxy service was running when you started the upgrade, the installer attempts to restart the proxy service after the upgrade completes. If the service was not running when you started the upgrade (or if service startup encountered an error requiring correction before starting), you'll need to start the Authentication Proxy service. From an administrator command prompt run:

    net start duoauthproxy
    

    Or, open the "Services" console (services.msc), locate the "Duo Security Authentication Proxy Service" in the list of services and click on it to select, and then click the start button.

    Authentication Proxy v5.1.0 and later includes the authproxyctl executable, which shows the connectivity tool output when starting the service. The installer adds the Authentication Proxy C:\Program Files\Duo Security Authentication Proxy\bin to your system path automatically, so you should not need to specify the full path to authproxyctl to run it.

    From an administrator command prompt run:

    authproxyctl start
    

Silent Upgrade

To perform a silent upgrade on Windows, issue the following from an elevated command prompt after downloading the installer (replacing version with the actual version you downloaded):

duoauthproxy-version.exe /S

Append /exclude-auth-proxy-manager to install silently without the Proxy Manager:

duoauthproxy-version.exe /S /exclude-auth-proxy-manager
  1. Download the most recent Authentication Proxy for Unix from https://dl.duosecurity.com/duoauthproxy-latest-src.tgz. From the command line you can use curl or wget to download the file, like $ wget --content-disposition https://dl.duosecurity.com/duoauthproxy-latest-src.tgz. Depending on your download method, the actual filename may reflect the version e.g. duoauthproxy-6.4.1-src.tgz. View checksums for Duo downloads here.

  2. The most recent Authentication Proxy version may have additional prerequisites beyond those installed for your current running version. On most recent RPM-based distributions — like Fedora, Red Hat Enterprise, and CentOS — you can install (or verify the presence of) these by running (as root):

    $ yum install gcc make libffi-devel perl zlib-devel diffutils
    

    On Debian-derived systems, install these dependencies by running (as root):

    $ apt-get install build-essential libssl-dev libffi-dev
    

    If SELinux is present on your system and you want the Authentication Proxy installer to build and install its SELinux module, include selinux-policy-devel and chkconfig in the dependencies:

    $ yum install gcc make libffi-devel perl zlib-devel diffutils selinux-policy-devel chkconfig
    
    $ apt-get install build-essential libssl-dev libffi-dev selinux-policy-devel chkconfig
    
  3. Extract the Authentication Proxy files

    tar xzf duoauthproxy-latest-src.tgz
    

    and change directory to the extracted source

    cd duoauthproxy-6.4.1-src
    
  4. Run make to build the Authentication Proxy installer.

  5. Change directory to the newly built installer

    cd duoauthproxy-build
    

    and run the installer

    ./install
    
  6. Follow the installation prompts to update your existing Authentication Proxy software. The upgrade retains the conf and log folders and contents from your current installation.

    The installer creates a user to run the proxy service and a group to own the log directory and files. You can accept the default user and group names or enter your own.

    If SELinux is present on the target server, the Duo installer will ask you if you want to install the Authentication Proxy SELinux module. Your selection affects whether systemd can start the Authentication Proxy after installation.

    If you choose to install the Authentication Proxy SELinux module and the dependencies selinux-policy-devel and chkconfig are not present, then the installer fails to build the module.

    SELinux Mode Duo SELinux Module Detected Default Response Result
    Enforcing Yes No Choose "yes" to install the Authentication Proxy's SELinux module. This permits start of the Authentication Proxy service by systemd. If you choose "no" then the SELinux module is not installed, and systemd cannot start the Authentication Proxy service.
    Enforcing Yes Yes Choose "yes" to continue using the Authentication Proxy's SELinux module. This permits start of the Authentication Proxy service by systemd. If you choose "no" then the SELinux module is not installed, and systemd cannot start the Authentication Proxy service.
    Permissive No No Choose "no" to decline install of the Authentication Proxy's SELinux module. The Authentication Proxy service can be started by systemd. However, if you change SELinux from permissive to enforcing mode after installing the Duo proxy, systemd can no longer start the Authentication Proxy service. If you plan to enable SELinux enforcing mode later, you should choose "yes" to install the Authentication Proxy SELinux module now.
    Permissive Yes Yes Choose "yes" to install the Authentication Proxy's SELinux module. This permits start of the Authentication Proxy service by systemd in the future if you change SELinux to enforcing mode. If you choose "no" and enable enforcing mode later, systemd can no longer start the Authentication Proxy service. If you plan to enable SELinux enforcing mode later, you should choose "yes" to install the Authentication Proxy SELinux module now.
  7. Start the new Authentication Proxy service

    /opt/duoauthproxy/bin/authproxyctl start
    

Silent Upgrade

To upgrade the Duo proxy silently with the default options, use the following command:

sudo ./duoauthproxy-build/install --install-dir /opt/duoauthproxy --service-user duo_authproxy_svc --log-group duo_authproxy_grp --create-init-script yes

Append --enable-selinux=yes|no to the install command to choose whether to install the Authentication Proxy SELinux module.

Uninstall the Proxy

Uninstalling the Duo Authentication Proxy deletes all config files and logs. Be sure to back these file up if you want to save them for future reference.

  1. Open the Programs and Features Control Panel applet. Locate and click on the "Duo Security Authentication Proxy" item in the program list.

  2. Click the Uninstall action at the top of the application list.

  3. The installer stops the Duo Authentication Proxy service and removes the application and supporting files.

Run the command /opt/duoauthproxy/uninstall. If you did not install the Authentication Proxy to /opt/duoauthproxy, substitute the actual installation directory.

If you opted to include the Authentication proxy SELinux module during installation then it is also removed by Authentication Proxy uninstall. To remove the Duo SELinux module without uninstalling the Duo Authentication Proxy, run the following commands:

$ semanage fcontext -d '/opt/duoauthproxy/usr/local/bin(/.*)?'
$ semodule -r duoauthproxy_systemd

Duo Authentication Proxy Manager

The Duo Authentication Proxy Manager is a Windows utility for managing the Authentication Proxy installation on the Windows server where you install the Authentication Proxy. The Proxy Manager comes with Duo Authentication Proxy for Windows version 5.6.0 and later.

The Proxy Manager cannot manage remote Duo Authentication Proxy servers, nor can you install the Proxy Manager as a stand-alone application. There is no Proxy Manager available for Linux. The Proxy Manager only functions as part of a local Duo Authentication Proxy installation on Windows servers.

Use of the Proxy Manager requires Windows administrative rights. The local or remote Windows console resolution should be 1024 x 600 or better to display the entire Proxy Manager window.

If you do not use the Proxy Manager to edit your configuration then we recommend using WordPad or another text editor instead of Notepad when editing the config file on Windows.

We want to hear about your experience using the Proxy Manager! Please fill out this Google Form to send us feedback.

Open the Proxy Manager

To launch the Proxy Manager utility:

  1. Open the Start Menu and go to Duo Security.

  2. Click the Duo Authentication Proxy Manager icon to launch the application. You must have administrative privileges on the Windows server and accept the prompt for elevation.

    If you have disabled UserAccountControl (UAC) on your Windows server, your Windows account must not only have Administrator privileges on that server, it also needs file access rights to read the contents of %ProgramFiles%\Duo Security Authentication Proxy\bin and to read and modify the contents of %ProgramFiles%\Duo Security Authentication Proxy\conf.

  3. The Proxy Manager launches and automatically opens the %ProgramFiles%\Duo Security Authentication Proxy\conf\authproxy.cfg file for editing.

To launch Proxy Manager from the command line, enter the following:

C:\Program File\Duo Security Authentication Proxy\bin\local_proxy_manager-win32-x64\Duo_Authentication_Proxy_Manager.exe

Only one instance of the Proxy Manager application may run at a time. While open, the Proxy Manager continually polls for the Authentication proxy service status. Closing the Proxy Manager ends the status check; no Proxy Manager process continue to run in the background after you close it.

Use the Proxy Manager

The Proxy Manager shows the following status information:

  • The current state of the proxy service; one of: running, stopped, start pending, pending, stop pending, error, or unknown.
  • The installed version. An alert icon and update link appear when the Proxy Manager detects availability of a newer Authentication Proxy release.
  • Current uptime of the Duo Security Authentication proxy service, if the service is running. If up for less than 24 hours, the uptime is shown as hours and minutes since start. After a day, the uptime shows the date and time when the proxy service was last started.
Duo Authentication Proxy Manager User Interface

Use the Proxy Manager text editor in the "Configure" pane to make the authproxy.cfg changes as instructed by the relevant Duo application documentation. As you type into the editor, the Proxy Manager will automatically suggest configuration options. Accepting these suggestions helps make sure you use the correct option syntax.

The Proxy Manager will not encrypt password and secret values for you. Continue using the authproxy_passwd.exe utility to produce encrypted password and secret values, and you can copy those values and paste them into the Proxy Manager editor.

While you edit the authproxy.cfg contents, your changes get saved to a temporary swap file (%ProgramFiles%\Duo Security Authentication Proxy\conf.authproxy.cfg.tmp). No changes are made to the actual authproxy.cfg file until you click Save.

Click Validate to verify your changes. This runs the connectivity tool against your proposed config changes. The "Output" pane shows the validation results. If the connectivity tool detects any issues with your configuration, the Proxy Manager shows an alert. Scroll through the validation output to locate the problematic options or settings, and correct them in the editor if necessary. Run validation again to confirm that you have fixed any issues preventing start of the Authentication Proxy service.

Click Save when you have finished making changes. This creates a backup of your existing authproxy.cfg file as authproxy-backup-yyyy-mm-dd_hh-mm-ss-mmm.cfg, writes your changes from the temporary swap file to authproxy.cfg, and then deletes the swap file. We recommend that you always validate your changes before saving them.

Changes to the Authentication Proxy config require a restart of the service to take effect. If the service is not currently running, click Start Service at the top of the Proxy Manager. If the service is already running, click Restart Service to stop and start the Authentication Proxy service immediately, or you could click Stop Service before making changes, and then start the service when you're done.

Warning!

Stopping or restarting the Duo Authentication Proxy will interrupt any running Active Directory or LDAP directory sync processes and will cause RADIUS, LDAP, and Duo Single Sign-On user logins to fail until the proxy service reaches the running state. Avoid disruption by restarting the Authentication Proxy service during off-hours or planned downtime.

Configuration

The Duo Authentication Proxy configuration file is named authproxy.cfg, and located in the conf subdirectory of the proxy installation.

Operating System Authentication
Proxy Version
Path
Windows v5.0.0 and later C:\Program Files\Duo Security Authentication Proxy\conf
Windows v4.0.2 and earlier C:\Program Files (x86)\Duo Security Authentication Proxy\conf
Linux All /opt/duoauthproxy/conf

Version 4.0.0 and later restricts the default file access for the conf directory to the Windows built-in "Administrators" group during installation. Version 5.4.1 and later also applies the same "Administrators" default file access permissions for the bin directory.

The configuration file is formatted as a simple INI file. Section headings appear as:

[section]

Individual properties beneath a section appear as:

name=value

Section headings and section specific parameters should be lowercase.

You may comment out lines in the cfg file by prepending the line with REM, #, or ;. As the semicolon character ; and octothorp character # are interpreted as the beginning of a comment, do not use any secrets or passwords in your config that contain these characters as this may cause truncation of the password or secret at the comment character.

Tip: Use comments to identify hosts in your config file

Adding a comment line with some contextual information preceding each of the sections in your authproxy.cfg file can help you and the other Duo admins at your organization identify devices and hosts used in the config when they're not recognizable by IP address. For example...

# This uses acme-dc01 for AD authentication
[ad_client]
host=1.2.3.4
service_account_username=duoservice
service_account_password=password1
search_dn=cn=Users,dc=example,dc=com
 
# This is the Cisco VPN in the Michigan office
[radius_server_auto]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
radius_ip_1=5.6.7.8
radius_secret_1=thisisaradiussecret

All relative paths specified in the configuration path are relative to the root proxy installation directory. For example, the default value for the main section's 'log_dir' configuration option is 'log' (as documented below). Given a default install location on Windows Server 2019, the log directory location is:

C:\Program Files\Duo Security Authentication Proxy\log

Important: If you modify your authproxy.cfg configuration, you'll need to stop and restart the Duo Authentication Proxy service or process for your change to take effect.

Encrypting Passwords

When running the Authentication Proxy on Windows, you may use encrypted alternatives for all service account passwords, Duo secret keys, and RADIUS secrets if you do not want to store them as plain text. In-place upgrades of the Authentication Proxy preserve this password and/or secret encryption.

Use the authproxy_passwd.exe program, located in the bin directory of your Authentication Proxy installation:

"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe"`
Encrypted values are machine-specific

The encrypted password or secret is specific to the server that generated it, and will not work if copied to a different machine. If you have multiple Authentication Proxy servers, be sure to run authproxy_passwd.exe separately on each one.

Execute the authproxy_passwd.exe from Windows Command Prompt, and provide the password or secret to encrypt when prompted. This example shows the encryption of a single password or secret typed in when prompted:

"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe"
Password:
Re-enter password:
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAFAXGTZJdPUuF9JbcuvSwagQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5
AAAAA2YAAMAAAAAQAAAANZiilAGq57x56P7+pdOPLgAAAAAEgAAAoAAAABAAAABdyNk87n/s53Jgyn4X6h+4IAAAADd4goUuz1WL
f6FEHmFZbL0wSxpH6GWFbyFGTw32fedsFAAAAMYIwtQ8Ac2ZalrXaSReUivsdkJ+

You can also run the command with the password or secret to encrypt specified inline, making it easy to verify that you've entered the correct string. Surround the password string with quotes (" ") as shown in this example:

"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe" "encryptthispasswordplease"
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAFAXGTZJdPUuF9JbcuvSwagQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5
AAAAA2YAAMAAAAAQAAAAzC6SJ/a9fPFb6pd5lKZ63QAAAAAEgAAAoAAAABAAAADG3ixBkUf7HbAZd32xgSB+IAAAACgFOn7z/ved
aFvCRaoIi5BbwXCpOtIYEdFimRRu5mmcFAAAAMW8d3Xdp5gJl0mUFAPCUBDgeYFC

Copy and paste the output into your configuration file open in the Proxy Manager or your text editor and remove any line breaks. You may find it easier to redirect the command output to a file and then open the file in Notepad to copy the encrypted string.

Repeat this for each password or secret in your authproxy.cfg file that you want encrypted.

If you'd like to encrypt all passwords and secrets in your authproxy.cfg file at once, run the command with the --whole-config option (in version 2.10.0 and later). This will encrypt each password and secret value and also update the configuration sections to use the "protected" parameter name. If you have the Proxy Manager application open while you encrypt all passwords and secrets with --whole-config you won't see the changes reflected in the application. We recommend performing whole-config encryption with the Proxy Manager application closed, then launching it after the encryption utility completes to see the changes.

In Authentication Proxy versions prior to 5.3.0, running the encryption tool against the whole file would also remove any comments; 5.3.0 and later preserve your comments.

Note that in Authentication Proxy versions prior to 5.4.0 you won't be able to decrypt the password and secret values once encrypted. Be sure to make a backup copy of authproxy.cfg before using this option (and secure the backup file as it contains your passwords and secrets).

"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe" --whole-config
Utilizing the feature to encrypt the entire configuration will overwrite any non critical
modifications to your configuration file such as comments. Are you sure you want to proceed?
[Yes/no] yes
Encryption complete. The Authentication Proxy configuration file has been updated.

You can append the option --yes (--yes-overwrite in proxy versions before 5.3.0) to bypass the warning.

When using encrypted passwords or secrets, use the "protected" version of the parameter:

Instead of... Use...
service_account_password service_account_password_protected
secret secret_protected
radius_secret_1, radius_secret_2, etc. radius_secret_protected_1, radius_secret_protected_2, etc.
skey skey_protected

Duo Authentication Proxy v5.4.0 and later permit decryption of previously encrypted passwords saved in the config file. To decrypt all passwords and secrets in your authproxy.cfg file, run the command with the --whole-config --decrypt options (in version 5.4.0 and later). This will decrypt each password and secret value and also update the configuration sections to no longer use "protected" parameter name.

"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe" --whole-config --decrypt
Using --whole-config will decrypt all passwords and secrets in your configuration file, overwriting
the encrypted values in-place. Would you like to continue? [Yes/no]: yes
Decryption complete. The Authentication Proxy configuration file has been updated.

There is no equivalent utility for encrypting passwords and secrets on Linux. Instead, you can restrict read and write access on the file to only the account that runs the proxy service.

First, determine what account is running the duoauthproxy service.

[root@duo ~]# ps -ef | grep duoauthproxy
nobody    1149     1  0 10:31 ?        00:00:15 /opt/duoauthproxy/usr/local/bin/python /opt/duoauthproxy/usr/local/bin/twistd --pidfile=/opt/duoauthproxy/run/duoauthproxy.pid --python=/opt/duoauthproxy/bin/duoauthproxy.tap --uid=99 --gid=99

In the example, the service is running as nobody. Set nobody as the owner and remove write and read permissions for any other user on the authproxy.cfg file.

[root@duo ~]# chown nobody /opt/duoauthproxy/conf/authproxy.cfg
[root@duo ~]# chmod 400 /opt/duoauthproxy/conf/authproxy.cfg

Verify the owner and permissions on the file.

[root@duo ~]# ls -l /opt/duoauthproxy/conf/authproxy.cfg
-r--------. 1 nobody root 3010 Feb 29 16:28 /opt/duoauthproxy/conf/authproxy.cfg

Main Section

The [main] section is optional. It can be used to specify some global options, all of which are optional:

debug

Enable debug logging when set to "true".

Default: "false"

log_dir Directory in which to store log files. Default: "log".
log_auth_events

Output SIEM-consumable authentication events to an 'authevents.log' file located in the log_dir directory when set to "true". Supported in version 2.5.4 or later.

Default: "false"

Be sure to add the user that runs the SIEM collection process to the group that owns the Duo proxy log directory and files (installer default group name is duo_authproxy_grp).

We recommend securing communications between the Authentication Proxy and your SIEM application with TLS. Additionally, you may want to enable heartbeat alerts or other notifications on your SIEM for awareness of interruptions to Authentication Proxy log collection. Consult your SIEM vendor for more information.

log_sso_events

Output SIEM-consumable Duo Single Sign-On (SSO) Active Directory authentication events to an 'ssoevents.log' file located in the log_dir directory. This log contains entries for SSO events such as connecting to or disconnecting from Duo's SSO service, and success/failure results for LDAP SSO authentications. Supported in version 3.2.0 or later.

Default: "true"

Be sure to add the user that runs the SIEM collection process to the group that owns the Duo proxy log directory and files (installer default group name is duo_authproxy_grp).

We recommend securing communications between the Authentication Proxy and your SIEM application with TLS. Additionally, you may want to enable heartbeat alerts or other notifications on your SIEM for awareness of interruptions to Authentication Proxy log collection. Consult your SIEM vendor for more information.

log_max_files

Maximum number of log files to create. When the current 'authproxy.log' or 'authevents.log' log files reach log_max_size, the proxy rotates the existing file out by renaming it 'authproxy.log.1' or 'authevents.log.1' (the existing '.log.1' becomes '.log.2', and so on; the oldest log file gets discarded), then start logging to a new, empty 'authproxy.log' or 'authevents.log' file. We do not recommend setting this value to 0.

Default: 6

log_max_size

Maximum file size of an individual 'authproxy' or 'authevents' log file, in bytes. We do not recommend setting this value to 0.

Default: 10485760 (10 megabytes)

log_file

Log to the log file specified during installation when set to "true". Note: if log_file, log_stdout, and log_syslog are all false, then logs will be sent to log file. As a result, if nothing is specified in the main section, logging to log file will occur by default. Supported in version 2.4.2 or later.

Default: "false"

log_stdout

Log to stdout when set to "true". If log_auth_events is enabled, the SIEM-consumable event entries do not redirect to stdout.

Default: "false"

log_syslog

Log to syslog when set to "true". Only available for Unix systems. Supported in version 2.4.2 or later. If log_auth_events is enabled, the SIEM-consumable event entries do not redirect to syslog.

Default: "false"

syslog_facility

The syslog_facility option sets the default facility for syslog messages that do not have a facility explicitly encoded. Only available for Unix systems. Supported in version 2.4.2 or later.

Default: LOG_USER

http_ca_certs_file

Location of ca-bundle.crt file.

Default: conf/ca-bundle.crt

interface

The IP address of the interface which Duo Authentication Proxy binds to on startup.

Default: listen on all interfaces

http_proxy_host

Hostname or IP address of an HTTP proxy accepting unauthenticated connections. If set, will be used for communicating with Duo Security's service. The upstream HTTP proxy must support the CONNECT protocol and not require authentication.

Default: do not use a proxy

Note that if the Authentication Proxy is configured to use an upstream HTTP proxy, then it cannot also act as an HTTP proxy for Duo applications itself.

http_proxy_port

Port to connect to on http_proxy_host.

Default: '80'

test_connectivity_on_startup

Run the connectivity troubleshooting tool at startup when set to "true". Output appended to the 'connectivity_tool.log' file located in the log_dir directory. Supported in version 2.9.0 or later.

Default: "false"

fips_mode

Start the proxy in FIPS mode when set to "true". Supported in version 2.12.0 or later. Read more about FIPS configuration.

Default: "false"

Example:

[main]
debug=true
log_max_files=10
log_max_size=20971520

Client Sections

When deploying the Duo Authentication Proxy in order to service user authentications, you will need to include one or more of the following configuration sections. These sections provide the proxy the information it needs to act as a client, that is, to forward primary authentication requests to another server in your environment.

Multiple server section configurations can use the same client section configuration. To configure more than one client configuration of the same type (in order to specify a different primary authentication source for some of your applications), append a number to the section name e.g. [ad_client2] or [radius_client2].

Multiple client types may coexist in the same configuration file, which means you can have any mixture of [ad_client], [radius_client], etc. present and used by different integrations.

Understand that configuring multiple client sections does not provide any failover ability between client sections, that is, a failure to authenticate against [ad_client] does not cause the proxy to then attempt the same primary authentication request against [ad_client2].

Client section headings should be lowercase.

ad_client

Add an [ad_client] section if you'd like to use an Active Directory domain controller (DC) or LDAP-based directory server to perform primary authentication. This section accepts the following options:

Required

host

The hostname or IP address of your domain controller or directory server. If this host doesn't respond to a primary authentication request and no additional hosts are specified (as host_2, host_3, etc.) then the user's login attempt fails.

service_account_username

The username of a domain account that has permission to bind to your directory and perform searches. We recommend creating a service account that has read-only access.

This parameter not required when using SSPI authentication; see the auth_type optional parameter below for more information.

service_account_password

The password corresponding to service_account_username. If you installed the Duo proxy on Windows and would like to encrypt this password, see Encrypting Passwords in the full Authentication Proxy documentation.

This parameter not required when using SSPI authentication; see the auth_type optional parameter below for more information.

search_dn

The LDAP distinguished name (DN) of an Active Directory/LDAP container or organizational unit (OU) containing all of the users you wish to permit to log in. For example:

search_dn=DC=example,DC=com

Optional

host_2

The hostname or IP address of a secondary/fallback domain controller or directory server, which the Authentication Proxy will use if a primary authentication request to the system defined as host times out. You can add additional servers as fallback hosts by specifying them as as host_3, host_4, etc.

security_group_dn

To further restrict access, specify the LDAP distinguished name (DN) of a security group that contains the users who should be able to log in as direct group members. Nested groups are not supported. Users who are not direct members of the specified group will not pass primary authentication. Example:

security_group_dn=CN=DuoVPNUsers,OU=Groups,DC=example,DC=com

Starting with Authentication Proxy v3.2.0, the security_group_dn may be the DN of an AD user's primarygroup. Prior versions do not support primary groups.

ldap_filter

Only users who match this LDAP filter will be permitted to log in. The filters should use standard LDAP filter syntax. Abbreviated example:

ldap_filter=(|(memberOf=CN=Admin,CN=...)(memberOf=CN=VPN,CN=...))

If matching a user's group membership with memberOf, the user must be a direct member of a group specified in the filter. If ldap_filter and security_group_dn are both set, users must match both in order to authenticate.

transport

This option can be used to enable SSL/TLS communication with your Active Directory server. The available options are:

"clear"

Do not use SSL or TLS. (Default)

"ldaps"

Wrap the entire LDAP connection in SSL. Unless you specify a custom port, this will cause the proxy to contact your Active Directory or LDAP server on port 636 rather than 389. Starting with Authentication Proxy version 6.0.0, the certificate issued to the domain controller or directory server host must use SHA256 or greater.

"starttls"

Open an unencrypted connection (to port 389, by default), but immediately send a "StartTLS" request to the Active Directory server. Starting with Authentication Proxy version 6.0.0 the certificate issued to the domain controller or directory server host must use SHA256 or greater.

The proxy defaults to "clear" communication because not all Active Directory or LDAP server configurations will support SSL/TLS out-of-the-box. To enable either "ldaps" or "starttls", your Active Directory server must be configured with an SSL certificate, otherwise attempts to establish secure connections will fail.

If your directory server is configured with an SSL certificate, we do recommend you select a choice other than "clear". (There should be little practical difference between "ldaps" and "startls", except the port number used). If you do, then you should also specify a value for the ssl_ca_certs_file option.

If the transport type is CLEAR and the auth_type is ntlm2 (the proxy default) or sspi, Authentication Proxy v5.0.0 and later will use LDAP Signing and Encryption (or "Sign and Seal") if the domain controller allows it.

timeout

The maximum number of seconds the Authentication Proxy should wait before aborting a primary authentication attempt to a domain controller and attempting authentication against the next fallback host (or returning an authentication failure if no more fallback hosts remain).

Default: 10

ssl_ca_certs_file

Path to a file containing the CA certificate(s) to be used to validate SSL/TLS connections to your Active Directory server. If you enable SSL/TLS connections to your Active Directory or LDAP server, you should specify a value for this option. Certificates should be PEM-formatted.

By default, no certificate validation will be performed, which significantly compromises the security properties offered by SSL/TLS.

In order to secure LDAP connections to your directory server using LDAPS or STARTTLS protocols, you'll need the PEM formatted certificate of the certificate authority (CA) that issued your AD domain controller's or LDAP directory server's SSL certificate.

To obtain the PEM formatted version of an AD domain controller certificate's issuing CA certificate, view the "Certification Path" tab of the DC's certificate properties and double-click the issuing certificate to view it. Export the issuing CA certificate as a Base-64 encoded X.509 (CER) format.

If you have intermediate CAs in your certificate issuer chain, export all the certs (such as the root CA and the intermediate CA) in the certification path as CER files and then combine them into one file using a text editor.

If you use a self-signed certificate to secure LDAPS communications to your directory server, the certificate's key usage should include "Certificate Signing". Starting with Authentication Proxy version 6.0.0, the self-signed certificate issued to the domain controller or directory server must use SHA256 or greater.

ssl_verify_hostname

If set to "true", then when establishing an SSL/TLS connection to the directory server, the proxy will ensure that the common name in the server-provided certificate matches the value specified in the host option.

If your directory server uses a certificate with an mismatched common name, or you specified the host as an IP address, set this option to "false". However, this will somewhat reduce the security guarantees otherwise provided by the use of TLS/SSL.

Default: "true"

auth_type

The authentication protocol to use with the Active Directory server. The available options are:

"ntlm2"

Microsoft NTLM, version 2.

If the transport type is CLEAR (the proxy default), then Authentication Proxy v5.0.0 and later will use LDAP Signing and Encryption (or "Sign and Seal") if the domain controller allows it.

"plain"

Plain LDAP authentication. This option should not be used without enabling transport-layer security (see 'transport', above). In addition, it requires that you specify a value for the bind_dn option.

"sspi"

Integrated Windows authentication. The server that hosts the Authentication Proxy must be a Windows server joined to an Active Directory domain. There is no need to provide service_account_username and service_account_password; authentication uses the context of the account that starts the "Duo Security Authentication Proxy" service (defaults to the domain-joined machine account).

If the host value is a domain controller with hostname, the proxy will use Kerberos if an LDAP Service Principal Name (SPN) exists for that target DC as ldap/hostname. If no such SPN exists, the proxy falls back to NTLM.

If the host value is an IP address, the proxy will use NTLM.

If the transport type is CLEAR (the proxy default), then the proxy will use LDAP Signing and Encryption (or "Sign and Seal") if the domain controller allows it.

Supported starting with Authentication Proxy v5.0.0.

Default: "ntlm2"

bind_dn

The full LDAP distinguished name of an account permitted to read from the Active Directory database. Typically, this would be the distinguished name of the user specified in service_account_username.

This option is required if auth_type is set to "plain".

ntlm_domain

Domain to provide when performing NTLM authentication. In most configurations, it should not be necessary to specify a value for this.

By default, the proxy will not specify a Domain.

ntlm_workstation

A workstation name to specify (identifying the proxy) when performing NTLM authentication. In most configurations, it should not be necessary to specify a value for this. By default, the proxy will not specify a workstation name.

port

Port on which to contact the domain controller. By default, port 636 will be used for LDAPS connections, and port 389 will be used for all others. Specify the Global Catalog port (e.g. 3268) to search a multi-domain forest.

username_attribute

LDAP attribute found on a user entry which will contain the submitted username. In most Active Directory configurations, it should not be necessary to change this option from the default value. OpenLDAP directories may use "uid" or another attribute for the username, which should be specified with this option.

Default: "sAMAccountName"

at_attribute

If a user logs in with a username containing an @ symbol, the proxy defaults to searching the userPrincipalName attribute for a match. If username_attribute is set to an LDAP attribute other than userPrincipalName whose values contain the @ symbol (such as mail), set this option to the same attribute used for username_attribute.

Default: "userPrincipalName"

Basic example:

[ad_client]
host=1.2.3.4
host_2=1.2.3.5
service_account_username=duoservice
service_account_password=password1
search_dn=DC=example,DC=com
security_group_dn=CN=DuoVPNUsers,OU=Groups,DC=example,DC=com

TLS-secured example:

[ad_client]
host=1.2.3.4
host_2=1.2.3.5
service_account_username=duoservice
service_account_password=password1
search_dn=DC=example,DC=com
security_group_dn=CN=DuoVPNUsers,OU=Groups,DC=example,DC=com
transport=starttls
ssl_ca_certs_file=conf\example_com_ca.pem

In the second example, place example_com_ca.pem into the "conf" subdirectory of your Authentication Proxy installation.

radius_client

Use [radius_client] when the Authentication Proxy contacts another RADIUS server (like Microsoft NPS or Cisco ACS) to perform primary authentication. This section accepts the following options:

Required

host

The IP address of your primary RADIUS server. If this host doesn't respond to a primary authentication request and no additional hosts are specified (as host_2, host_3, etc.) then the user's login attempt fails.

secret

RADIUS secret shared between the proxy and the primary authentication server. If you add more than one RADIUS server (host, host_2, etc.) they all must use the same shared secret setting.

If you installed the Duo proxy on Windows and would like to encrypt this secret, see Encrypting Passwords and use secret_protected instead.

Optional

host_2

The IP address of a secondary/fallback primary RADIUS server, which the Authentication Proxy will use if a primary authentication request to the system defined as host times out. You can add additional servers as fallback hosts by specifying them as as host_3, host_4, etc.

port

The authentication port on your RADIUS server. By default, the proxy will attempt to contact your RADIUS server on port 1812. Use port_2, port_3, etc. to specify ports for the backup servers.

retries

Number of retries to attempt before considering an authentication attempt to have failed. Default: 3

retry_wait

Number of seconds to wait between retry attempts. Default: 2

nas_ip

IP address to provide to the primary authentication server in the "NAS-IP-Address" attribute. By default, the proxy will attempt to determine its own IP address and use that.

pass_through_attr_names

Comma-separated list of additional RADIUS attributes to pass through from the primary authentication to the device integrating with the Authentication Proxy when authentication is accepted. The attribute must exist in the Authentication Proxy's RADIUS dictionary. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto. If it is not known whether the dictionary includes the specific RADIUS attribute you wish to send, use pass_through_all instead.

Only valid when used with radius_client. By default, the proxy will create a new Accept message without passing through any attributes.

pass_through_all

If this option is set to "true", all RADIUS attributes set by the primary authentication server will be copied into RADIUS responses sent by the proxy. Only valid when used with radius_client.

Default: "false"

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to "latin-1".

For example:

[radius_client]
host=1.2.3.4
host_2=1.2.3.5
secret=radiusclientsecret

duo_only_client

If your device supports separate configurations for primary and secondary authentication, you can use the Authentication Proxy for the secondary authentication and let your device handle primary authentication independently. To achieve this, add a new section called [duo_only_client] to your config file. This section has no additional properties to configure.

[duo_only_client]

Server Sections

Depending on which type of application you're configuring to send authentication requests to the Duo Authentication proxy, you will need to include one or more of the following configuration sections for the proxy to act as a server and receive the incoming authentications. Each type has a different impact on the end-user authentication experience.

  • RADIUS Auto
    The user's device and factor is automatically selected for each login. Users can also use the "password,factor" append format to specify an alternate device and/or factor. This mode is recommended for most applications, and is compatible with almost all systems that support RADIUS authentication.
  • RADIUS iFrame
    Users will see a web-based authentication prompt. This mode is only available on supported devices, like Array, Citrix, and F5 SSL VPNs.
  • RADIUS Challenge
    Users will be presented with a textual challenge after entering their existing passwords. Note that not all systems supporting RADIUS authentication can support RADIUS challenges. However, for systems that do support challenges, this offers a cleaner and more flexible integration than RADIUS Concat (described next). Note: In most cases, we recommend RADIUS Auto instead of RADIUS Challenge.
  • RADIUS Concat
    Users will append a Duo passcode to their existing passwords in the format "password,factor". This mode should be compatible with almost any system that supports RADIUS authentication using the PAP mechanism. Note: In most cases, we recommend RADIUS Auto instead of RADIUS Concat.
  • RADIUS Duo Only
    Use a RADIUS integration which does not handle primary authentication credentials. The user's passcode or factor choice, encrypted using the PAP mechanism, is submitted for the RADIUS password.
  • LDAP Auto
    The factor is automatically selected for each login, instead of prompting the user. Users can also use the "password,factor" append format to specify an alternate device and/or factor.

Multiple server configurations can be used by appending a number onto the end of the section name (e.g. radius_server_auto1, radius_server_auto2, etc.). Incoming requests will be filtered to a given server configuration based on IPs set in radius_ip_x in each server section.

RADIUS Auto

The user's device and factor is automatically selected for each login. This mode is compatible with almost all systems that support RADIUS authentication, including mechanisms like EAP and PEAP. Inline password reset over RADIUS is also supported with MS-CHAPv2 only.

PEAP and EAP methods like EAP-TLS, EAP-MSCHAPv2, PEAP/EAP-MSCHAPv2, and MSCHAP-v2 are supported when the client mechanism is radius_client, and for automatic push or call only — not factor names or passcodes appended to passwords. Note that EAP-MSCHAPv2 and PEAP/EAP-MSCHAPv2 require Authentication Proxy version 5.2.0 or later.

  • If the password is encrypted with PAP: users may append a factor name or passcode after their existing passwords.
  • If there is no Duo factor appended or the password is encrypted with EAP: the factor is selected based on Duo's recommendation or the administrator's preferences.
  • If the password was encrypted with PAP and the administrator enables passcodes: the user may be prompted for a passcode with a RADIUS challenge. Otherwise, no RADIUS challenges are issued and only out-of-band factors (as opposed to token or passcode based authentication) are supported.
  • If the password is encrypted with EAP and the user appends a factor name or passcode after their password then authentication fails.

For PEAP/EAP-GTC authentications, radius_server_eap can be used with either ad_client or radius_client. NetMotion Mobility is the only officially supported integration for this authentication type.

To use RADIUS Auto, add a [radius_server_auto] section, which accepts the following options:

Required

ikey

Your Duo integration key, obtained from the details page for the application in the Duo Admin Panel.

skey

Your Duo secret key, obtained from the details page for the application in the Duo Admin Panel.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host

Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the application in the Duo Admin Panel.

radius_ip_1

IP address or IP address range for RADIUS clients. Only clients with configured addresses and shared secrets will be allowed to send requests to the Authentication Proxy. If two server configurations have the same or overlapping IP ranges, the request will go to whichever comes first in the file.

This can be a single IP address (e.g. 1.2.3.4), a specification in CIDR notation (e.g. 1.2.3.0/24), or an IP address range (e.g. 3.3.3.3 - 3.3.3.6 for the IPs 3.3.3.3, 3.3.3.4, 3.3.3.5, and 3.3.3.6).

radius_secret_1

The secret shared with RADIUS clients matching radius_ip_1.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_1 instead.

client

The mechanism that the Authentication Proxy should use to perform primary authentication. This should correspond with a "client" section elsewhere in the config file.

ad_client

Use Active Directory for primary authentication. Make sure you have an [ad_client] section configured.

radius_client

Use RADIUS for primary authentication. Make sure you have a [radius_client] section configured.

duo_only_client

Do not perform primary authentication. Make sure you have a [duo_only_client] section configured.

This parameter is optional if you only have one "client" section. If you have multiple, each "server" section should specify which "client" to use.

Optional

radius_ip_2

Address(es) of an additional RADIUS client. Specify more as radius_ip_3, etc.

radius_secret_2

The secret shared with RADIUS clients matching radius_ip_2. Specify more as radius_secret_3, etc.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_2 (or radius_secret_protected_3, etc.) instead.

factors

List of factors ordered by preference. Separate each factor name with a comma (','). The first of these factors supported by a user's configured devices will be used to authenticate that user, unless the user specifies which factor to use by appending the factor name to the password at login.

auto

Use the out-of-band factor ("push" or "phone") recommended by Duo as the best for the user's devices. This is the default.

push

Use Duo Push.

phone

Call the user's phone.

passcode

Send a RADIUS Access-Challenge message prompting the user to enter a passcode.

delimiter

Character (or string) which separates the primary authentication password from the Duo passcode or factor name. If a user's password contains this character, the Authentication Proxy will try interpreting it as an append-mode password, falling back to auto-factor selection if the part of the password before the delimiter is not valid for primary authentication.

This must be a character or string that can never appear within a Duo passcode or factor name. This generally means that punctuation marks are acceptable; alphanumeric characters are not.

Default: the delimiter character is a comma (',').

delimited_password_length

Permits appending a Duo factor or passcode to a user password without specifying a delimiter character, e.g. instead of password,123456 the user enters password123456. Requires Authentication Proxy 3.1.0.

To configure, set to a digit that represents the length of users' passwords. The Authentication Proxy will attempt to parse a specified authentication factor name or a passcode at the n+1 character. If a delimiter character is present, the proxy strips the delimiter and then parses the factor name or passcode (so password123456 and password,123456 would have the same result). In the prior example, you would set delimited_password_length=8 to parse the passcode beginning with the ninth character. All user passwords must be the same length as the number of characters specified in this setting to avoid truncation.

allow_concat

If false, never check for a delimiter in user passwords; always use auto-factor selection.

Default: true (do check for the delimiter and an appended Duo factor or passcode). Concatenation is not supported with MS-CHAPv2.

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Note that this time includes waiting for the user to respond to out-of-band factors ("push" or "phone"). If an authentication request is issued but not completed before this timeout is reached, the authentication attempt is rejected.

Default: 0 (no timeout).

failmode

Either safe or secure:

Failmode

Description

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds.

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

Default: safe

port

Port on which to listen for incoming RADIUS Access Requests. If you have multiple RADIUS server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default RADIUS port 1812, you will need to set this to a different port number to avoid a conflict.

Default: 1812

interface

IP address of the network interface on which to listen for incoming RADIUS Access Requests.

Default: listen on all interfaces

pass_through_attr_names

A comma separated list of RADIUS attribute names which, if sent to the Authentication Proxy from the peer, will be passed through to the primary RADIUS server. The attribute must exist in the Authentication Proxy's RADIUS dictionary. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto. If it is not known whether the dictionary includes the specific RADIUS attribute you wish to send, use pass_through_all instead. Only valid when used with radius_client.

Example:

NAS-Identifier,Calling-Station-Id

Default: No attributes passed through

pass_through_all

If this option is set to true all RADIUS attributes the proxy receives in a request will be copied into requests sent to RADIUS primary authentication servers. Only valid when used with radius_client.

Default: false

client_ip_attr

When authenticating, the proxy sends the value of the RADIUS calling-station-id to Duo and to the upstream primary authenticator as the client IP address.

Send the value of another RADIUS attribute as the client IP address by setting this option to the desired RADIUS attribute. The attribute must exist in the Authentication Proxy's RADIUS dictionary; defining an attribute that does not exist in the dictionary prevents proxy service startup. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto.

For example, to send the value of the NAS-IP-Address as the client IP, specify client_ip_attr=NAS-IP-Address.

exempt_username_1

Specify a single username. Multi-factor authentication will not be required for this user.

Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate RADIUS connection. The exemptions should cover those service user(s). The username specified here is case-sensitive, meaning that the username case in the incoming RADIUS authentication request must match the exempt username specified here.

Requires version 2.4.10 or later.

exempt_username_2

Additional username to exempt from multi-factor authentication. Specify more as exempt_username_3, exempt_username_4, etc. Requires version 2.4.10 or later.

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to latin-1.

For example:

[radius_server_auto]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
failmode=safe
radius_ip_1=5.6.7.8
radius_secret_1=thisisalsoaradiussecret
client=radius_client

RADIUS iframe

The iframe-based traditional Duo Prompt for RADIUS configurations ([radius_server_iframe]) reached its end of support on March 30, 2024 for all configurations except NetScaler, which is supported until December 31, 2024.

Customers must migrate to a supported Duo configuration that does not use the iframe for continued support after the end-of-support dates.

We recommend migrating existing RADIUS iframe configurations to a Duo Single Sign-On application with Universal Prompt if your device supports SAML 2.0 authentication. If not, switch to a RADIUS configuration without the iframe, for example, RADIUS with Automatic Push ([radius_server_auto]).

Users will see a web-based authentication prompt. This mode was only available on select supported devices.

To use RADIUS iframe, add a [radius_server_iframe] section, which accepts the following options:

Required

ikey

Your Duo integration key, obtained from the details page for the application in the Duo Admin Panel.

skey

Your Duo secret key, obtained from the details page for the application in the Duo Admin Panel.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host

Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the application in the Duo Admin Panel.

radius_ip_1

IP address or IP address range for RADIUS clients. Only clients with configured addresses and shared secrets will be allowed to send requests to the Authentication Proxy. If two server configurations have the same or overlapping IP ranges, the request will go to whichever comes first in the file.

This can be a single IP address (e.g. 1.2.3.4), a specification in CIDR notation (e.g. 1.2.3.0/24), or an IP address range (e.g. 3.3.3.3 - 3.3.3.6 for the IPs 3.3.3.3, 3.3.3.4, 3.3.3.5, and 3.3.3.6).

radius_secret_1

The secret shared with RADIUS clients matching radius_ip_1.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_1 instead.

type The type of device with which you are integrating. Options:
array Array SPX SSL-VPN - unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
barracuda Barracuda Networks SSL VPN - unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
citrix Citrix Access Gateway - not to be confused with NetScaler Gateway or Citrix Gateway. Unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
citrix_netscaler NetScaler or Citrix Gateway: all themes except RFWebUI. Unsupported for traditional Duo Prompt delivery via iframe after December 31, 2024.
citrix_netscaler_rfwebui NetScaler or Citrix Gateway with nFactor (all themes). Requires Authentication Proxy v3.1.0 and NS build 12.1-51.16 or later. Unsupported for traditional Duo Prompt delivery via iframe after December 31, 2024.
f5 F5 FirePass SSL VPN - unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
f5_bigip F5 BIG-IP Access Policy Manager - unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
fortinet Fortinet FortiGate SSL VPN up to FortiOS v5.4. Unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
juniper Juniper or Pulse SSL VPN up to v9.0R3 firmwares. Unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
paloalto Palo Alto Networks SSL-VPN up to PAN-OS v5. Unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
sonicwall_sra SonicWALL SRA or SMA SSL VPN - 100 series devices only. Unsupported for traditional Duo Prompt delivery via iframe as of March 30, 2024.
client

The mechanism that the Authentication Proxy should use to perform primary authentication. This should correspond with a "client" section elsewhere in the config file.

ad_client

Use Active Directory for primary authentication. Make sure you have an [ad_client] section configured.

radius_client

Use RADIUS for primary authentication. Make sure you have a [radius_client] section configured.

duo_only_client

Do not perform primary authentication. Make sure you have a [duo_only_client] section configured.

This parameter is optional if you only have one "client" section. If you have multiple, each "server" section should specify which "client" to use.

Optional

radius_ip_2

Address(es) of an additional RADIUS client. Specify more as radius_ip_3, etc.

radius_secret_2

The secret shared with RADIUS clients matching radius_ip_2. Specify more as radius_secret_3, etc.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_2 (or radius_secret_protected_3, etc.) instead.

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Default: 15 (8 for Citrix).

failmode

Either safe or secure:

Failmode

Description

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds.

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

Default: safe

port

Port on which to listen for incoming RADIUS Access Requests. If you have multiple RADIUS server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default RADIUS port 1812, you will need to set this to a different port number to avoid a conflict.

Default: 1812

interface

IP address of the network interface on which to listen for incoming RADIUS Access Requests.

Default: listen on all interfaces

pass_through_attr_names

A comma separated list of RADIUS attribute names which, if sent to the Authentication Proxy from the peer, will be passed through to the primary RADIUS server. The attribute must exist in the Authentication Proxy's RADIUS dictionary. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto. If it is not known whether the dictionary includes the specific RADIUS attribute you wish to send, use pass_through_all instead. Only valid when used with radius_client.

Example:

NAS-Identifier,Calling-Station-Id

Default: No attributes passed through

pass_through_all

If this option is set to true all RADIUS attributes the proxy receives in a request will be copied into requests sent to RADIUS primary authentication servers. Only valid when used with radius_client.

Default: false

client_ip_attr

When authenticating, the proxy sends the value of the RADIUS calling-station-id to Duo and to the upstream primary authenticator as the client IP address.

Send the value of another RADIUS attribute as the client IP address by setting this option to the desired RADIUS attribute. The attribute must exist in the Authentication Proxy's RADIUS dictionary; defining an attribute that does not exist in the dictionary prevents proxy service startup. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto.

For example, to send the value of the NAS-IP-Address as the client IP, specify client_ip_attr=NAS-IP-Address.

exempt_username_1

Specify a single username. Multi-factor authentication will not be required for this user.

Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate RADIUS connection. The exemptions should cover those service user(s). The username specified here is case-sensitive, meaning that the username case in the incoming RADIUS authentication request must match the exempt username specified here.

Requires version 2.4.10 or later.

exempt_username_2

Additional username to exempt from multi-factor authentication. Specify more as exempt_username_3, exempt_username_4, etc. Requires version 2.4.10 or later.

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to latin-1.

For example:

[radius_server_iframe]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
type=citrix_netscaler
failmode=safe
radius_ip_1=5.6.7.8
radius_secret_1=thisisalsoaradiussecret
client=radius_client

RADIUS Challenge

Users will be presented with a textual challenge after entering their existing passwords. If the user is not enrolled in Duo and the new user policy requires enrollment, then the challenge response will be a generated enrollment URL the user can copy into a browser window to complete Duo enrollment. Prevent enrollment via challenge response by setting the new user policy to "Deny access".

Note that not all systems supporting RADIUS authentication can support RADIUS challenges. Challenge response factor selection is not supported with any use of MS-CHAPv2.

To use RADIUS Challenge, add a [radius_server_challenge] section, which accepts the following options:

Required

ikey

Your Duo integration key, obtained from the details page for the application in the Duo Admin Panel.

skey

Your Duo secret key, obtained from the details page for the application in the Duo Admin Panel.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host

Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the application in the Duo Admin Panel.

radius_ip_1

IP address or IP address range for RADIUS clients. Only clients with configured addresses and shared secrets will be allowed to send requests to the Authentication Proxy. If two server configurations have the same or overlapping IP ranges, the request will go to whichever comes first in the file.

This can be a single IP address (e.g. 1.2.3.4), a specification in CIDR notation (e.g. 1.2.3.0/24), or an IP address range (e.g. 3.3.3.3 - 3.3.3.6 for the IPs 3.3.3.3, 3.3.3.4, 3.3.3.5, and 3.3.3.6).

radius_secret_1

The secret shared with RADIUS clients matching radius_ip_1.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_1 instead.

client

The mechanism that the Authentication Proxy should use to perform primary authentication. This should correspond with a "client" section elsewhere in the config file.

ad_client

Use Active Directory for primary authentication. Make sure you have an [ad_client] section configured.

radius_client

Use RADIUS for primary authentication. Make sure you have a [radius_client] section configured.

duo_only_client

Do not perform primary authentication. Make sure you have a [duo_only_client] section configured.

This parameter is optional if you only have one "client" section. If you have multiple, each "server" section should specify which "client" to use.

Optional

radius_ip_2

Address(es) of an additional RADIUS client. Specify more as radius_ip_3, etc.

radius_secret_2

The secret shared with RADIUS clients matching radius_ip_2. Specify more as radius_secret_3, etc.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_2 (or radius_secret_protected_3, etc.) instead.

prompt_format This controls how the Challenge message is formatted. Options
console

The proxy will return a textual prompt, with a list of available authentication devices and lines separated by newline characters. This is most appropriate for console-based integrations, and might not work correctly with web-based logins (e.g. SSL VPN devices). This is the default format.

html

The proxy will return the same textual prompt as with the "console" option, but replace line breaks with HTML line-break (i.e. '<br />') tags. This is more likely to work correctly with web-based logins.

short

The proxy will format a simple, short textual-challenge message, listing only the available factor names (but not their descriptions).

The proxy will also fall back on this format if any of the other options were selected, but the message length exceeds the permissible length of a RADIUS challenge message.

The more Duo factors your users enroll, the longer the resulting RADIUS challenge prompt text will be, and the more likely that user will see the short format prompt text.

enroll_challenge

The RADIUS specification allows for reply messages in both Access-Challenge and Access-Reject responses. However, many devices will only actually display the reply message if it appears in an Access-Challenge. Thus, while sending an Access-Reject response with the appropriate enrollment link would generally be more logical, using an Access-Challenge will provide broader compatibility.

If this option is set to true, then when an unenrolled user logs in, the proxy will send back an enrollment message in a RADIUS Access-Challenge response, but deny any subsequent responses to the challenge.

If set to false, then the proxy will send back the enrollment message in an Access-Reject response.

Default: true

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Note that this time includes waiting for the user to respond to out-of-band factors ("push" or "phone"). If an authentication request is issued but not completed before this timeout is reached, the authentication attempt is rejected.

Default: 0 (no timeout).

failmode

Either safe or secure:

Failmode

Description

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds.

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

Default: safe

port

Port on which to listen for incoming RADIUS Access Requests. If you have multiple RADIUS server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default RADIUS port 1812, you will need to set this to a different port number to avoid a conflict.

Default: 1812

interface

IP address of the network interface on which to listen for incoming RADIUS Access Requests.

Default: listen on all interfaces

pass_through_attr_names

A comma separated list of RADIUS attribute names which, if sent to the Authentication Proxy from the peer, will be passed through to the primary RADIUS server. The attribute must exist in the Authentication Proxy's RADIUS dictionary. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto. If it is not known whether the dictionary includes the specific RADIUS attribute you wish to send, use pass_through_all instead. Only valid when used with radius_client.

Example:

NAS-Identifier,Calling-Station-Id

Default: No attributes passed through

pass_through_all

If this option is set to true all RADIUS attributes the proxy receives in a request will be copied into requests sent to RADIUS primary authentication servers. Only valid when used with radius_client.

Default: false

client_ip_attr

When authenticating, the proxy sends the value of the RADIUS calling-station-id to Duo and to the upstream primary authenticator as the client IP address.

Send the value of another RADIUS attribute as the client IP address by setting this option to the desired RADIUS attribute. The attribute must exist in the Authentication Proxy's RADIUS dictionary; defining an attribute that does not exist in the dictionary prevents proxy service startup. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto.

For example, to send the value of the NAS-IP-Address as the client IP, specify client_ip_attr=NAS-IP-Address.

exempt_username_1

Specify a single username. Multi-factor authentication will not be required for this user.

Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate RADIUS connection. The exemptions should cover those service user(s). The username specified here is case-sensitive, meaning that the username case in the incoming RADIUS authentication request must match the exempt username specified here.

Requires version 2.4.10 or later.

exempt_username_2

Additional username to exempt from multi-factor authentication. Specify more as exempt_username_3, exempt_username_4, etc. Requires version 2.4.10 or later.

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to latin-1.

For example:

[radius_server_challenge]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
failmode=safe
radius_ip_1=5.6.7.8
radius_secret_1=thisisalsoaradiussecret
client=radius_client
prompt_format=html

RADIUS Concat

Users will append a Duo passcode to their existing passwords. This mode should be compatible with almost any system that supports RADIUS authentication using the PAP mechanism. Concatenation is not supported with any use of MS-CHAPv2.

To use RADIUS Concat, add a [radius_server_concat] section, which accepts the following options:

Required

ikey

Your Duo integration key, obtained from the details page for the application in the Duo Admin Panel.

skey

Your Duo secret key, obtained from the details page for the application in the Duo Admin Panel.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host

Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the application in the Duo Admin Panel.

radius_ip_1

IP address or IP address range for RADIUS clients. Only clients with configured addresses and shared secrets will be allowed to send requests to the Authentication Proxy. If two server configurations have the same or overlapping IP ranges, the request will go to whichever comes first in the file.

This can be a single IP address (e.g. 1.2.3.4), a specification in CIDR notation (e.g. 1.2.3.0/24), or an IP address range (e.g. 3.3.3.3 - 3.3.3.6 for the IPs 3.3.3.3, 3.3.3.4, 3.3.3.5, and 3.3.3.6).

radius_secret_1

The secret shared with RADIUS clients matching radius_ip_1.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_1 instead.

client

The mechanism that the Authentication Proxy should use to perform primary authentication. This should correspond with a "client" section elsewhere in the config file.

ad_client

Use Active Directory for primary authentication. Make sure you have an [ad_client] section configured.

radius_client

Use RADIUS for primary authentication. Make sure you have a [radius_client] section configured.

duo_only_client

Do not perform primary authentication. Make sure you have a [duo_only_client] section configured.

This parameter is optional if you only have one "client" section. If you have multiple, each "server" section should specify which "client" to use.

Optional

radius_ip_2

Address(es) of an additional RADIUS client. Specify more as radius_ip_3, etc.

radius_secret_2

The secret shared with RADIUS clients matching radius_ip_2. Specify more as radius_secret_3, etc.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_2 (or radius_secret_protected_3, etc.) instead.

delimiter

Character (or string) which separates the primary authentication password from the Duo passcode or factor name. If a user's password contains this character, the Authentication Proxy will try interpreting it as an append-mode password, falling back to auto-factor selection if the part of the password before the delimiter is not valid for primary authentication.

This must be a character or string that can never appear within a Duo passcode or factor name. This generally means that punctuation marks are acceptable; alphanumeric characters are not.

Default: the delimiter character is a comma (',').

delimited_password_length

Permits appending a Duo factor or passcode to a user password without specifying a delimiter character, e.g. instead of password,123456 the user enters password123456. Requires Authentication Proxy 3.1.0.

To configure, set to a digit that represents the length of users' passwords. The Authentication Proxy will attempt to parse a specified authentication factor name or a passcode at the n+1 character. If a delimiter character is present, the proxy strips the delimiter and then parses the factor name or passcode (so password123456 and password,123456 would have the same result). In the prior example, you would set delimited_password_length=8 to parse the passcode beginning with the ninth character. All user passwords must be the same length as the number of characters specified in this setting to avoid truncation.

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Note that this time includes waiting for the user to respond to out-of-band factors ("push" or "phone"). If an authentication request is issued but not completed before this timeout is reached, the authentication attempt is rejected.

Default: 0 (no timeout).

failmode

Either safe or secure:

Failmode

Description

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds.

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

Default: safe

port

Port on which to listen for incoming RADIUS Access Requests. If you have multiple RADIUS server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default RADIUS port 1812, you will need to set this to a different port number to avoid a conflict.

Default: 1812

interface

IP address of the network interface on which to listen for incoming RADIUS Access Requests.

Default: listen on all interfaces

pass_through_attr_names

A comma separated list of RADIUS attribute names which, if sent to the Authentication Proxy from the peer, will be passed through to the primary RADIUS server. The attribute must exist in the Authentication Proxy's RADIUS dictionary. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto. If it is not known whether the dictionary includes the specific RADIUS attribute you wish to send, use pass_through_all instead. Only valid when used with radius_client.

Example:

NAS-Identifier,Calling-Station-Id

Default: No attributes passed through

pass_through_all

If this option is set to true all RADIUS attributes the proxy receives in a request will be copied into requests sent to RADIUS primary authentication servers. Only valid when used with radius_client.

Default: false

client_ip_attr

When authenticating, the proxy sends the value of the RADIUS calling-station-id to Duo and to the upstream primary authenticator as the client IP address.

Send the value of another RADIUS attribute as the client IP address by setting this option to the desired RADIUS attribute. The attribute must exist in the Authentication Proxy's RADIUS dictionary; defining an attribute that does not exist in the dictionary prevents proxy service startup. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto.

For example, to send the value of the NAS-IP-Address as the client IP, specify client_ip_attr=NAS-IP-Address.

exempt_username_1

Specify a single username. Multi-factor authentication will not be required for this user.

Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate RADIUS connection. The exemptions should cover those service user(s). The username specified here is case-sensitive, meaning that the username case in the incoming RADIUS authentication request must match the exempt username specified here.

Requires version 2.4.10 or later.

exempt_username_2

Additional username to exempt from multi-factor authentication. Specify more as exempt_username_3, exempt_username_4, etc. Requires version 2.4.10 or later.

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to latin-1.

For example:

[radius_server_concat]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
failmode=safe
radius_ip_1=5.6.7.8
radius_secret_1=thisisalsoaradiussecret
client=radius_client

RADIUS Duo Only

Use a RADIUS integration which does not handle primary authentication credentials. The user's passcode or factor choice, encrypted using the PAP mechanism, is submitted for the RADIUS password. Note that this section never requires a client parameter.

To use RADIUS Duo Only, add a [radius_server_duo_only] section, which accepts the following options:

Required

ikey

Your Duo integration key, obtained from the details page for the application in the Duo Admin Panel.

skey

Your Duo secret key, obtained from the details page for the application in the Duo Admin Panel.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host

Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the application in the Duo Admin Panel.

radius_ip_1

IP address or IP address range for RADIUS clients. Only clients with configured addresses and shared secrets will be allowed to send requests to the Authentication Proxy. If two server configurations have the same or overlapping IP ranges, the request will go to whichever comes first in the file.

This can be a single IP address (e.g. 1.2.3.4), a specification in CIDR notation (e.g. 1.2.3.0/24), or an IP address range (e.g. 3.3.3.3 - 3.3.3.6 for the IPs 3.3.3.3, 3.3.3.4, 3.3.3.5, and 3.3.3.6).

radius_secret_1

The secret shared with RADIUS clients matching radius_ip_1.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_1 instead.

Optional

radius_ip_2

Address(es) of an additional RADIUS client. Specify more as radius_ip_3, etc.

radius_secret_2

The secret shared with RADIUS clients matching radius_ip_2. Specify more as radius_secret_3, etc.

If you're on Windows and would like to encrypt this password, see Encrypting Passwords and use radius_secret_protected_2 (or radius_secret_protected_3, etc.) instead.

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Note that this time includes waiting for the user to respond to out-of-band factors ("push" or "phone"). If an authentication request is issued but not completed before this timeout is reached, the authentication attempt is rejected.

Default: 0 (no timeout).

failmode

Either safe or secure:

Failmode

Description

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds.

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

Default: safe

port

Port on which to listen for incoming RADIUS Access Requests. If you have multiple RADIUS server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default RADIUS port 1812, you will need to set this to a different port number to avoid a conflict.

Default: 1812

interface

IP address of the network interface on which to listen for incoming RADIUS Access Requests.

Default: listen on all interfaces

client_ip_attr

When authenticating, the proxy sends the value of the RADIUS calling-station-id to Duo.

Send the value of another RADIUS attribute as the client IP address by setting this option to the desired RADIUS attribute. The attribute must exist in the Authentication Proxy's RADIUS dictionary; defining an attribute that does not exist in the dictionary prevents proxy service startup. The dictionary includes standard RADIUS attributes, as well as some vendor specific attributes from Cisco, Juniper, Microsoft, and Palo Alto.

For example, to send the value of the NAS-IP-Address as the client IP, specify client_ip_attr=NAS-IP-Address.

exempt_username_1

Specify a single username. Multi-factor authentication will not be required for this user.

Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate RADIUS connection. The exemptions should cover those service user(s). The username specified here is case-sensitive, meaning that the username case in the incoming RADIUS authentication request must match the exempt username specified here.

Requires version 2.4.10 or later.

exempt_username_2

Additional username to exempt from multi-factor authentication. Specify more as exempt_username_3, exempt_username_4, etc. Requires version 2.4.10 or later.

pw_codec

The default encoding for RADIUS is UTF-8. If Latin-1 is required, set to latin-1.

For example:

[radius_server_duo_only]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
failmode=safe
radius_ip_1=5.6.7.8
radius_secret_1=thisisalsoaradiussecret

LDAP Auto

Use this for an LDAP integration in which the factor is automatically selected for each login. LDAP Auto must use an LDAP directory for primary authentication.

  • If the authenticating application, service, or device uses the LDAP "plain" authentication mechanism to communicate with the Duo proxy server, then users may append a factor name or passcode after their existing passwords.
  • If there is no Duo factor appended to the password or if the password is encrypted with SASL (i.e. NTLM or SSPI), then Duo's service selects a factor based on Duo's recommendation or the administrator's preferences.

LDAP authentication does not pass client IP information to Duo. Therefore policy settings based on available IP address information, like authorized networks or user location have no effect on LDAP logins to Duo-protected applications.

To use LDAP Auto, add a [ldap_server_auto] section, which accepts the following options:

Required

ikey Your Duo integration key.
skey

Your Duo secret key.

If you installed the Duo proxy on Windows and would like to encrypt this password, see Encrypting Passwords and use skey_protected instead.

api_host Your Duo API hostname (e.g. "api-XXXXXXXX.duosecurity.com").
client

The mechanism that the Authentication Proxy should use to perform primary authentication. This should correspond with a "client" section elsewhere in the config file.

ad_client

Use Active Directory for primary authentication. Make sure you have an [ad_client] section configured. Neither [radius_client] nor [duo_only_client] are valid for use with [ldap_server_auto].

This parameter is optional if you only have one "ad_client" section. If you have multiple, each "server" section should specify which "client" to use.

Optional

factors

List of factors ordered by preference. Separate each factor name with a comma (','). The first of these factors supported by a user's configured devices will be used to authenticate that user, unless the user specifies which factor to use by appending the factor name to the password at login.

auto

Use the out-of-band factor ("push" or "phone") recommended by Duo as the best for the user's devices. This is the default.

push

Use Duo Push.

phone

Call the user's phone.

passcode

Accepts a passcode.

failmode

Either "safe" or "secure":

safe

In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds. (Default)

secure

In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

port

Port on which to listen for incoming LDAP connections. If you have multiple LDAP server sections you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default LDAP port 389, you will need to set this to a different port number to avoid a conflict.

Default: 389

interface

IP address of the network interface on which to listen for incoming LDAP connections. By default, the proxy will listen on all interfaces.

api_timeout

Maximum time (in seconds) to wait for a response from the Duo API server. Note that this time includes waiting for the user to respond to out-of-band factors ("push" or "phone"). If an authentication request is issued but not completed before this timeout is reached, the authentication attempt is rejected.

Default: 0 (no timeout).

network_timeout

Maximum idle time (in seconds) on connections to the backing directory server (from the configured ad_client section). When reached, the proxy closes both LDAP client and server connections.

Default: 600 seconds (10 minutes).

idle_timeout

Maximum idle time (in seconds) on connections from the authenticating LDAP application or service. When reached, the proxy closes both LDAP client and server connections.

Default: 3600 seconds (1 hour).

ssl_port

If ssl_key_path and ssl_cert_path are present then the Authentication Proxy will listen for incoming LDAPS connections on this port, as well as listening on port 389 (or the specified value for port for unsecured LDAP or STARTTLS connections.

If you have multiple LDAP server sections with SSL certs configured you should use a unique port for each one. If you have another service running on the server where you installed Duo that is using the default LDAPS port 636, you will need to set this to a different port number to avoid a conflict.

Default: 636

ssl_key_path

Path to PEM-formatted SSL/TLS private key. The key should not be encrypted or require a password. Both ssl_key_path and ssl_cert_path must be specified to listen for STARTTLS or LDAPS requests.

ssl_cert_path

Path to PEM-formatted SSL/TLS server certificate. Both ssl_key_path and ssl_cert_path must be specified to listen for STARTTLS or LDAPS requests.

exempt_primary_bind

If set to "true" (the default) then multi-factor authentication will not be performed for the first successful LDAP authentication in each connection. Use this if the device using the Authentication Proxy first connects as a service user and then authenticates the user who is logging in.

exempt_ou_1

Specify either the DN of a single user or an OU. Multi-factor authentication will not be required for these users. Set this option if the device using the Authentication Proxy first connects as a service user, disconnects, and then authenticates the user who is logging in with a separate LDAP connection. The exemptions should cover those service user(s).

A full DN must be sent as the username in the bind request from the authenticating device or service (example: CN=Norben Arroway,OU=Acme Users,DC=Acme,DC=Corp) in Authentication Proxy versions up to 3.1.1. Starting with v3.2.0, the username format received by the Duo proxy may also be in UPN format narroway@acme.corporate) or NTLM format ACME\narroway).

exempt_ou_2

Additional OU or DN to exempt from multi-factor authentication. Specify additional exemptions with exempt_ou_3, exempt_ou_4, etc.

delimiter

Character (or string) which separates the primary authentication password from the Duo passcode or factor name. If a user's password contains this character, the Authentication Proxy will try interpreting it as an append-mode password, falling back to auto-factor selection if the part of the password before the delimiter is not valid for primary authentication.

This must be a character or string that can never appear within a Duo passcode or factor name. This generally means that punctuation marks are acceptable; alphanumeric characters are not.

Default: the delimiter character is a comma (',').

delimited_password_length

Permits appending a Duo factor or passcode to a user password without specifying a delimiter character, e.g. instead of password,123456 the user enters password123456. Requires Authentication Proxy 3.1.0.

To configure, set to a digit that represents the length of users' passwords. The Authentication Proxy will attempt to parse a specified authentication factor name or a passcode at the n+1 character. If a delimiter character is present, the proxy strips the delimiter and then parses the factor name or passcode (so password123456 and password,123456 would have the same result). In the prior example, you would set delimited_password_length=8 to parse the passcode beginning with the ninth character. All user passwords must be the same length as the number of characters specified in this setting to avoid truncation.

allow_concat

If false, never check for a delimiter in user passwords; always use auto-factor selection.

Default: true (do check for the delimiter and an appended Duo factor or passcode). Concatenation is not supported with MS-CHAPv2.

allow_searches_after_bind

If "false", the incoming LDAP connection is disconnected immediately after a successful bind. Defaults to "true"; keep LDAP connection open after a successful bind to allow additional queries. The session is closed upon receiving a subsequent bind request. Requires Authentication Proxy version 2.4.14.

allow_unlimited_binds

If "true", the proxy maintains open connections and permits reuse of these connections for multiple LDAP bind requests after completing 2FA. Defaults to "false"; which either closes the LDAP connection after 2FA, or keeps the connection open for searches only if allow_searches_after_bind is true. The session is closed upon receiving a disconnect. Requires Authentication Proxy version 2.9.0 or later.

To avoid 2FA requests for service and lookup account bind requests, specify exempt_primary_bind=false and list the service/lookup account(s) by DN as exempt_ou_1, exempt_ou_2, etc.

minimum_tls_version

Specify the minimum TLS version for SSL connections when the Authentication Proxy acts as a server. One of: "ssl3", "tls1.0", "tls1.1", or "tls1.2".

If not specified, defaults to TLS 1.2 as the minimum as of Authentication Proxy version 3.0.0. Configurable in version 2.12.0 or later.

cipher_list

If configured, this limits the SSL cipher suites used by the Authentication Proxy when acting as a server to the specific ciphers listed. Include an individual cipher name or group of ciphers using the OpenSSL cipher list format. See the Mozilla TLS Recommended configurations for more information.

If not specified, any valid cipher suite is allowed. Requires Authentication Proxy version 2.12.0 or later.

For example:

[ldap_server_auto]
client=ad_client
ikey=DIXXXXXXXXXXXXXXXXXX
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-XXXXXXXX.duosecurity.com
failmode=safe
exempt_primary_bind=false
exempt_ou_1=CN=ldaplookup,dc=acme,dc=org
ssl_key_path=ldap_server.key
ssl_cert_path=ldap_server.pem

Cloud Section

The [cloud] section is a special configuration used only when importing users to Duo via OpenLDAP or Active Directory (AD) synchronization. See our AD Sync documentation or OpenLDAP sync documentation to learn more.

As of Authentication Proxy version 5.2.0, multiple [cloud] sections (e.g. [cloud], [cloud2], etc.) may co-exist in the same authproxy.cfg configuration file, each corresponding to a different sync in the same Duo account (identical api_host values). In versions 5.1.0 and earlier, only one [cloud] may be present in the configuration file (therefore requiring a separate Authentication Proxy server for each AD or OpenLDAP sync you configure).

Required

ikey

Directory sync integration key

skey

Directory sync integration secret

api_host

Directory sync API hostname

service_account_username

The username of an account that has permission to read from your Active Directory or OpenLDAP directory. We recommend creating a service account that has read-only access. This parameter requires Authentication Proxy v2.6.0 or later, and is used with NTLMv2 and Plain authentication.

If service account credentials are specified in Authentication Proxy v3.2.0 and later when the corresponding Active Directory sync config in the Duo Admin Panel uses "Integrated" authentication, then the proxy negotiates NTLM over SSPI authentication using the credentials instead of the machine account.

service_account_password

The password that corresponds to the service_account_username. This parameter requires Authentication Proxy v2.6.0 or later, and is used with NTLMv2 and Plain authentication.

If service account credentials are specified in Authentication Proxy v3.2.0 and later when the corresponding Active Directory sync config in the Duo Admin Panel uses "Integrated" authentication, then the proxy negotiates NTLM over SSPI authentication using the credentials instead of the machine account.

The values for the [cloud] section are provided on the directory's properties page in the Duo Admin Panel as a downloadable text file. Copy the information from that file and append it to your existing authproxy.cfg file.

Example for Integrated (SSPI) authentication. The Duo proxy is a Windows server joined to the authenticating domain:

[cloud]
ikey=DIABCDEFGHIJKLMNOPQR
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-12345678.duosecurity.com

Example for Plain or NTLM authentication:

[cloud]
ikey=DIABCDEFGHIJKLMNOPQR
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-12345678.duosecurity.com
service_account_username=duosync
service_account_password=Pass12345

Example for multiple directory syncs using Integrated (SSPI) authentication. Note that the integration key differs but the API host is the same in both [cloud] sections; this reflects the requirement that the multiple syncs must be for a single Duo customer account:

[cloud]
ikey=DIABCDEFGHIJKLMNOPQR
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-12345678.duosecurity.com

[cloud2]
ikey=DISTUVWXYZABCDEFGHIJ
skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api_host=api-12345678.duosecurity.com

SSO Section

The [sso] section configures the Authentication Proxy to act as a Duo Single Sign-On Active Directory authentication source. This section must be present in the config with the remote identity key provided during SSO setup in the Duo Admin Panel before running the SSO enrollment command. Only one [sso] section may be present in authproxy.cfg section, which means that a given Authentication Proxy server may only perform authentications for a single SSO deployment. Please refer to the complete Duo Single Sign-On instructions.

Example for Integrated (SSPI) authentication. The Duo proxy is a Windows server joined to the authenticating domain:

[sso]
rikey=RIABCDEFGHIJKLMNOPQR

Example for Plain or NTLM authentication:

[sso]
rikey=RIABCDEFGHIJKLMNOPQR
service_account_username=duosync
service_account_password=Pass12345

HTTP Proxy Section

The [http_proxy] section configuration allows supported Duo applications to proxy HTTPS connections to Duo's cloud service through the Authentication Proxy server. This is useful in environments where client systems do not have direct Internet access to Duo. You must also configure the Duo application to use the Authentication Proxy server as an HTTP proxy. See that specific Duo application's documentation for proxy instructions. Supported in version 2.4.13 or later.

Note that if you configure the Authentication Proxy to act as an HTTP proxy for Duo applications installed on other systems then the Authentication Proxy must be able to contact Duo's service directly. You may not use the Authentication Proxy as an HTTP proxy for other systems when it is itself using an HTTP proxy for internet access.

To use the HTTP proxy feature, add a [http_proxy] section, which accepts the following options:

Required

api_host Your Duo API hostname (e.g. "api-XXXXXXXX.duosecurity.com"). Use the hostname from the Duo application that will be connecting to Duo's service through your Authentication Proxy server.

Optional

port The port on which to accept incoming HTTP proxy connections. Default: 80
client_ip

Restricts inbound HTTP proxy connections to the specified IP address. If no client IPs are specified then the Authentication Proxy accepts HTTP proxy connections from any client.

This can be a single IP address (e.g. "1.2.3.4"), multiple client IPs separated by a comma ("1.2.3.4,1.2.3.14,1.2.3.24"), or a CIDR range (e.g. "1.2.3.0/23").

interface

IP address of the network interface on which to listen for incoming HTTP proxy connections. By default, the proxy will listen on all interfaces or inherit any interface specified in the [main] section.

Example:

[http_proxy]
api_host=api-XXXXXXXX.duosecurity.com
port=8080
client_ip=192.168.23.42,192.168.23.64

Multiple HTTP proxy configurations can be used by appending a number onto the end of the section name (e.g. http_proxy1, http_proxy2, etc.). The port must be unique for each http_proxy section. Incoming requests are filtered to a given proxy configuration based on the connection request's port, then optionally further restricted by the IPs listed in client_ip.

FIPS Mode

To run the authentication proxy in FIPS mode, please use the following configuration:

  1. Install Duo Authentication Proxy 2.12.0 or later on a Windows or Linux system with FIPS enabled at the OS level.

  2. Enable FIPS mode for the Duo proxy by adding fips_mode=true to the main section of authproxy.cfg.

    [main]
     fips_mode=true

    Verify that your Duo Authentication Proxy is running in FIPS mode by examining the authproxy.log output after startup. You'll see a line similar to this:

    FIPS mode 1 is enabled with OpenSSL 1.0.2o-fips
  3. The only FIPS-compliant client option is ad_client with ntlm2, plain, or sspi auth_type. Additionally, the client must be configured for encrypted transport with the transport setting set to ldaps or starttls, and you must specify a ssl_ca_certs_file used to secure communications between the Duo proxy server and your upstream LDAP/AD server.

    [ad_client]
     host=1.2.3.4
     service_account_username=duoservice
     service_account_password=password1
     search_dn=DC=example,DC=com
     transport=starttls
     ssl_ca_certs_file=conf\example_com_ca.pem

    The radius_client is not FIPS-compliant due to RADIUS's use of the md5 hash without the option of stronger outer encryption.

    The directory server OS should be in FIPS mode as well. We recommend enabling LDAP Channel Binding validation on your Windows AD domain controllers. A Linux LDAP server should use FIPS-enabled OpenSSL (refer to your directory service's implementation guide to determine requirements for FIPS).

  4. The only FIPS-compliant server options are ldap_server_auto and radius_server_eap (which is only supported with the NetMotion Mobility VPN).

    The ldap_server_auto server section must be configured to listen for ldaps or starttls requests. Enable this by setting the ssl_key_path, ssl_cert_path and ssl_port options. The ad_client used must be configured for encrypted transport as well (as specified in step 2).

    [ldap_server_auto]
     client=ad_client
     ikey=DIXXXXXXXXXXXXXXXXXX
     skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     api_host=api-XXXXXXXX.duosecurity.com
     ssl_key_path=ldap_server.key
     ssl_cert_path=ldap_server.pem
     ssl_port=636

    If configuring RADIUS for NetMotion Mobility, the radius_server_eap server section must specify an ad_client configured for encrypted transport. You should also require FIPS-compliant encryption for clients on your Mobility server.

    No other RADIUS server module is FIPS-compliant (radius_server_auto, etc.).

  5. Ensure that you are using TLS 1.2 for any communication that passes through the Authentication Proxy. Setting fips_mode=true automatically restricts the allowed protocol to TLS 1.2 for these communications:

    • Communication between ldap_server_auto or radius_server_eap and the application or device you are protecting with Duo.

    • Communication between ad_client and the LDAP directory server.

    • Communication between the Duo Authentication Proxy and Duo's cloud service.

    For end-to-end TLS 1.2 communications you should ensure that the clients of the device or application sending requests to the Duo proxy and the upstream authenticating LDAP server are all only permitting TLS 1.2 as well.

  6. Windows users should encrypt all passwords and secrets in the authproxy.cfg file. There is no password encryption tool available for Linux authentication proxy installs, but you can protect access to the authproxy.cfg file by ensuring that the account that runs the duoauthproxy service is the owner of the authproxy.cfg file, and then restricting read access on authproxy.cfg to the file owner (chmod 600).

  7. If you are syncing users into Duo via this authentication proxy, configure the sync to use LDAPS or STARTTLS transport.

Start the Proxy

If you installed the Duo Authentication Proxy Manager utility (available with 5.6.0 and later), click the Start Service button at the top of the Proxy Manager window to start the service.

To start the service from the command line, open an Administrator command prompt and run:

net start DuoAuthProxy

Alternatively, open the Windows Services console (services.msc), locate "Duo Security Authentication Proxy Service" in the list of services, and click the Start Service button.

Authentication Proxy v5.1.0 and later includes the authproxyctl executable, which shows the connectivity tool output when starting the service. The installer adds the Authentication Proxy C:\Program Files\Duo Security Authentication Proxy\bin to your system path automatically, so you should not need to specify the full path to authproxyctl to run it.

From an administrator command prompt run:

authproxyctl start

If the service starts successfully, Authentication Proxy service output is written to the authproxy.log file, which can be found in the log subdirectory.

If you see an error saying that the "service could not be started", open the Application Event Viewer and look for an Error from the source "DuoAuthProxy". The traceback may include a "ConfigError" that can help you find the source of the issue.

Stop and restart the Authentication Proxy service by either clicking the Restart Service button in the Duo Authentication Proxy Manager or the Windows Services console or issuing these commands from an Administrator command prompt:

net stop DuoAuthProxy & net start DuoAuthProxy

To stop and restart the Authentication Proxy using authproxyctl, from an administrator command prompt run:

authproxyctl restart

Open a root shell and run:

# /opt/duoauthproxy/bin/authproxyctl start

To ensure the proxy started successfully, run:

# /opt/duoauthproxy/bin/authproxyctl status

Authentication Proxy service output is written to the authproxy.log file, which can be found in the log subdirectory.

To stop and restart the Authentication Proxy, open a root shell and run:

# /opt/duoauthproxy/bin/authproxyctl restart

If you modify your authproxy.cfg configuration after initial setup, you'll need to stop and restart the Duo Authentication Proxy service or process for your change to take effect.

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

Authentication Proxy Dashboard

Role required: Owner, Administrator, or Application Manager

The Authentication Proxy Dashboard allows you to monitor the state of your Authentication Proxies. You can access this dashboard by logging in to the Duo Admin Panel and navigating to ApplicationsAuthentication Proxy. The dashboard will display a table with the name, hostname, status, and version for each of your Authentication Proxies.

Authentication Proxy Dashboard

Authentication Proxies must be running version 6.0.1 or later to appear in the Authentication Proxy dashboard. Authentication Proxies configured only for [http_proxy] or configured to protect applications from multiple Duo accounts will not appear in the dashboard.

You will need to perform one of the following in order for your Authentication Proxy to appear in the dashboard:

  • If your Authentication Proxy is running versions 6.0.1 or earlier, you will need to upgrade.

  • If your Authentication Proxy is already running version 6.0.1 or later, you will need to restart your Authentication Proxy.

Click on the name of an Authentication Proxy to view further details. The details page will contain the name, description, hostname, status, version, and operating system. To change the name or description, enter the desired text into the corresponding fields then click Save.

Authentication Proxy Dashboard Details page

You can view the configuration details for an Authentication Proxy on its detail page. There is a table for each of the following:

  • Authentication Sources: Active Directory Authentication Sources used for Single Sign-on.
  • Directory Sync Connections: Active Directory and OpenLDAP connections used for user syncs and admin syncs.
  • Configured Applications: RADIUS and LDAP applications protected by this Authentication Proxy.
Authentication Proxy Dashboard Configuration Details

If you wish to hide an Authentication Proxy from the dashboard, click Hide from dashboard. This will only hide the Authentication Proxy from displaying on the dashboard and will not delete it from your environment. If you want to unhide an Authentication Proxy, in the upper-right corner select Show hidden Authentication Proxies and then click Show on dashboard for each Authentication Proxy you want to unhide.

Troubleshooting

Determine the Installed Version

Windows

Open the Programs and Features Control Panel applet. Locate the "Duo Security Authentication Proxy" item in the program list. Both the program name and the version column show the installed version e.g. "Duo Security Authentication Proxy 5.2.0".

If you have Authentication Proxy version 5.2.0 or later installed, you can also find the installed version with the authproxyctl utility.

From an administrator command prompt run this command and examine the on-screen output:

authproxyctl version

Linux

Find the installed version with the authproxyctl utility.

From a root shell or with su run this command and examine the on-screen output:

/opt/duoauthproxy/bin/authproxyctl version

Issues Starting the Proxy

If you are unable to start the Duo Authentication Proxy service, there may be an issue with your configuration file. Use the connectivity tool included with Duo Authentication Proxy 2.9.0 and later to help find issues preventing successful start of the proxy service.

You can also try starting the proxy and looking for errors.

Windows

Open the Application Event Viewer and look for an "Error" from the source "DuoAuthProxy". The traceback may include a "ConfigError" that can help you find the source of the issue.

From an administrator command prompt run this command and examine the on-screen output:

authproxyctl start

Linux

From a root shell or with su run this command and examine the on-screen output:

/opt/duoauthproxy/bin/authproxyctl start

Enable Debug Logging

Enable debug mode if you're experiencing issues with authentication or directory sync processes. This writes additional information to the authproxy.log file. which may help you figure out the root cause. Additionally, if you contact Duo Support about any application that uses the Authentication Proxy, the support engineer will request this debug output as part of the troubleshooting process.

To enable debug output:

  1. Open your authproxy.cfg file in a text editor.

  2. Locate the [main] section. If this section does not exist, then create it.

  3. Add the setting debug=true on a new line in the [main] section (leave any other settings you might have in the [main] section unchanged).

    [main]
     debug=true
  4. Save the authproxy.cfg file and stop then restart the Duo Authentication Proxy service.

The default locations for log file output are:

Operating System Authentication
Proxy Version
Path
Windows v5.0.0 and later C:\Program Files\Duo Security Authentication Proxy\log
Windows v4.0.2 and earlier C:\Program Files (x86)\Duo Security Authentication Proxy\log
Linux All /opt/duoauthproxy/log

Using the Connectivity Tool

Starting with Authentication Proxy version 2.9.0 we've provided a utility you can use to discover and troubleshoot general connectivity issues. This tool is not backward-compatible with prior Authentication Proxy releases.

As of version 2.12.0 the Authentication Proxy will automatically perform some validation checking on your configuration at startup, as well as when you run the connectivity tool manually.

Note that this is not a configuration utility. It won't walk you through setting up the Duo proxy services, but can point out basic misconfigurations and help you figure out issues such as an inability to listen on a port, inability to contact remote servers, inability to communicate with the Duo cloud service, and similar problems.

Running the Connectivity Tool

Interactively on Windows
  1. Open an administrative command prompt on your Duo proxy server.

  2. Run this command to launch the tool:

    "C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_connectivity_tool.exe"
    
Interactively on Linux
  1. SSH to your Duo proxy server.

  2. Run this command to launch the tool:

    sudo /opt/duoauthproxy/bin/authproxy_connectivity_tool
    
Automatically on Startup

To always run the connectivity tool when the Duo Authentication Proxy starts, edit your authproxy.cfg file to add the line test_connectivity_on_startup=true to the [main] section, save the file, and restart the Duo proxy service.

Note that the proxy will always perform configuration validation at startup, even if you haven't enabled test_connectivity_on_startup=true.

Reviewing Connectivity Tool Output

When you run the connectivity tool manually, it logs the results of all configuration and connectivity tests to the file C:\Program Files\Duo Security Authentication Proxy\log\connectivity_tool.log on Windows and /opt/duoauthproxy/log/connectivity_tool.log on Linux. When run interactively it also echoes all test results to the screen, with passing tests in green and failing tests in red.

When run, the tool performs a series of tests against each configured section (e.g. [ad_client] and [radius_server_auto]) of your authproxy.cfg file, and presents the results of all tests for each section grouped together in the output. Configuration checks are run before connectivity tests, and if any configuration issues are found then the connectivity tests are not run.

If all tests on a configuration section pass, then the output indicates that specific client or server section has no connectivity problems and does not print the results of each individual test.

If any tests on a configuration section fail or are skipped due to missing information or a failed prerequisite test, then all individual test results are reported for that section, including any tests that succeeded.

Version Update Check

As of Authentication Proxy 5.1.0, the connectivity tool checks for available proxy version updates and notifies you when you're running an outdated version. This check makes an outbound HTTPS/443 connection from your Authentication Proxy server to dl.duosecurity.com.

Example: Update Available

Checking updates for Duo Authentication Proxy...
[info] A new version of Duo Authentication Proxy is available now.
[info] You are using version n.n.n, but version n.n.n has been released.
[warn] You are missing n update(s), including n major update(s), n security fix(es), and some minor changes
[info] Please visit https://duo.com/docs/authproxy-notes to check release notes of the Duo Authentication Proxy
[info] Please visit https://dl.duosecurity.com/duoauthproxy-latest.exe to download the latest version of the Duo Authentication Proxy

Example: Installed Version Up to Date

Checking updates for Duo Authentication Proxy...
[info]  No updates detected. Your Duo Authentication Proxy is up to date.

Configuration Section Tests

The following table shows which tests are performed for the various section types permitted in authproxy.cfg:

Section Type Connectivity Checks
HTTP Proxy
AD Client
RADIUS Client
LDAP Server
RADIUS Server (any type)
Cloud
Duo-only client

In addition to the sections listed above, the configuration as a whole is checked for the following:

  • The Duo Authentication Proxy is not configured to both act as and use an HTTP proxy.
  • There are no overlaps in the RADIUS servers' coverage of ports and interfaces.
  • The servers links to their specified clients are valid.

The following table describes the types of tests performed by the connectivity tool:

Check Type Details
Configuration The section configuration is checked for a number of invalid settings:

  • All required keys are present
  • All key values are valid for their expected data
  • No unexpected keys are provided
  • No invalid combinations of keys are specified
Listen on configured port The tool will ensure that is is able to listen on the specified (or default) port and interface, for the appropriate protocol (TCP, UDP, or SSL). Verify no other services running on the same machine have the ports in use (i.e. NPS using the same RADIUS port).

TCP: for any ldap_server_auto with SSL NOT configured, http_proxy sections

UDP: for all radius_server sections (radius_server_auto, radius_server_iframe, radius_server_challenge...)

SSL: for any ldap_server_auto section with SSL configured

Ping Duo The tool will attempt to use the /ping Auth API endpoint. This generally ensures the AP machine is able to reach Duo hosts on the internet.
API time drift The tool will assess the time difference between Duo and the Duo Proxy server, since if this drift is too high, authentications may be impacted.
API credential validation The tool will attempt to use the /check Auth API endpoint. This ensures the API credentials are valid and match each other.
TCP connection The tool will attempt to initiate a TCP connection to a remote host to make sure it is reachable. This is done only for host(s) specified in ad_client.
RADIUS connection The tool will use a RADIUS Status-Server packet to attempt to ascertain the status of the RADIUS server. This is done only for host(s) specified in radius_client. If a RADIUS server is reachable but does not support the Status-Server message (for example, NPS), the tool reports the same warning as when the RADIUS server is unreachable.
See IETF RFC 5997 for technical details.
SSL connection The tool will attempt to initiate an SSL connection to a remote host with the provided SSL context data.
SSL context

The tool will validate the provided SSL data (certificates and/or keys) to ensure they are correct and usable for creating SSL connections. This check will only ever be done for ldap_server_auto sections with SSL configured.

Checks for:
- SSL key and certificate files exist, are readable, and are well-formatted PEM files
- Certificate is not expired
- Key and certificate match each other
- Specified cipher list is parseable (checking if it's actually usable happens above in the SSL connection check)
- If certificate was signed off by a CA, the entire cert chain (eg. the root CA cert, any intermediate certs, and the actual cert used to create SSL connections) is present
- If a certificate chain is present, the actual cert the admin wishes to use is at the top of the PEM file, with all others (CA's, intermediates) below it
Note that self-signed certificates will validate with this tool.

LDAP connection

The tool will create an LDAP client connection to the remote LDAP server specified in the user's ad_client section(s).

Bind check The tool will attempt to LDAP bind as the configured service user in their ad_client section(s).
It will use the same transport_type specified in that section- eg. if transport_type=ldaps and ssl_ca_certs_file has been specified, the bind will be done over LDAPS/SSL.
Search check The tool will attempt to determine if an LDAP user search will find users, based on their configured (or default) filter settings in their ad_client section(s). As of version 5.3.0 the tool also searches for the group specified in security_group_dn.

Configuration Validation Examples

No issues found in section
-----------------------------
Testing section 'radius_server_auto' with configuration:
{'api_host': 'api-xxxxxxxx.duosecurity.com',
 'client': 'ad_client',
 'debug': "true",
 'failmode': 'secure',
 'ikey': 'DIXXXXXXXXXXXXXXXXXX',
 'port': '1812',
 'radius_ip_1': '10.1.23.42',
 'radius_secret_1': '*****',
 'skey': '*****[40]'}
There are no configuration problems
-----------------------------
Issues found in section

Issues found when validating configuration.

-----------------------------
Testing section 'radius_server_challenge' with configuration:
{'api_host': 'api-xxxxxxxx.duosecurity.com',
 'client': 'ad_client',
 'failmode': 'safe',
 'ikey': 'DIXXXXXXXXXXXXXXXXXX',
 'port': '1801',
 'prompt_format': 'html',
 'radius_ip_1': '10.1.10.216',
 'radius_secret_9': '*****',
 'skey': '*****[40]'}
There are configuration problems that need to be resolved.
radius_secret_1 must be provided when specifying radius_ip_1
radius_ip_9 must be provided when specifying radius_secret_9
-----------------------------
Summary of configuration tests

The concluding summary section lists any configuration issues discovered.

[info]  SUMMARY
[warn]  Checks for external connectivity were not run. Please fix the configuration and try again.
[info]
[info]  Section [radius_server_challenge]
[warn]  There are configuration problems that need to be resolved.
[error] radius_secret_1 must be provided when specifying radius_ip_1
[error] radius_ip_9 must be provided when specifying radius_secret_9
[info]

In this example, the Duo proxy did not start and no connectivity checks were run due to the invalid configuration.

Connectivity Test Examples

No issues found in section
-----------------------------
Testing configuration section radius_server_auto
The RADIUS Server has no connectivity problems.
-----------------------------
Missing information and skipped tests

Some tests were skipped due to missing information, and other tests were skipped because a prerequisite test failed or was skipped.

-----------------------------
Testing configuration section radius_server_auto2
The RADIUS Server has connectivity problems.
There are configuration problems related to connectivity that need to be resolved.
A configuration item required to test connectivity is missing: ikey
A configuration item required to test connectivity is missing: api_host
A configuration item required to test connectivity is missing: radius_ip_1
A configuration item required to test connectivity is missing: skey / skey_protected
A configuration item required to test connectivity is missing: radius_secret_1 / radius_secret_protected_1
The radius_ip_2 value provided is invalid: 100.200.300.400.
The radius_ip_3 value provided is invalid: 101.201.301.401.
The Auth Proxy did not run the ping check because of the configuration problem with api_host. Resolve that configuration issue and rerun the tester.
The Auth Proxy did not run the time drift check because of the problem(s) with the ping check. Resolve that issue and rerun the tester.
The Auth Proxy did not run the validate api credentials check because of the configuration problem with api credentials. Resolve that configuration issue and rerun the tester.
The Auth Proxy was able to listen to 1812 on all interfaces
-----------------------------

Using the Support Tool

If you open a case with Duo Support for an issue involving the Duo Authentication Proxy, your support engineer will need you to submit your configuration file, recent debug log output showing the issue, and connectivity tool output. Sensitive information, like service account passwords, RADIUS secrets, and Duo SKEYs, should be removed from the config file before sending.

We've made collecting troubleshooting information easy with a script that gathers all the necessary files, scrubs them for passwords and other sensitive information, and creates a zip package ready for you to send to your Duo support engineer. The script is included in version 2.14.0 and later.

The support tool performs the following actions:

  1. Runs the connectivity tool, outputting test results to the connectivity_tool.log file in the log directory.

  2. Copies the current authproxy.cfg to a new clean_authproxy.cfg file and replaces all passwords, RADIUS secrets, and Duo SKEYs with asterisks.

  3. Creates a zip file that contains the clean_authproxy.cfg file and all log files in the log directory, including connectivity_tool.log, authproxy.log (and any previously rotated authproxy.log.n files), and authevents.log.

  4. Saves the zip file in the Duo Authentication Proxy base installation directory as duoauthproxy-support-datestring-timestring.zip. So on Windows, for example, the support file would be C:\Program Files\Duo Security Authentication Proxy\duoauthproxy-support-20190219-140924.zip.

Running the Support Tool on Windows

  1. Open an administrative command prompt on your Duo proxy server.

  2. Run this command to launch the tool:

    "C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_support.exe"
    

Running the Support Tool on Linux

  1. SSH to your Duo proxy server.

  2. Run this command to launch the tool:

    sudo /opt/duoauthproxy/bin/authproxy_support
    

Primary Only Mode

On rare occasions you may wish to bypass Duo authentication for all users and devices that authenticate through your Duo Authentication Proxy. You can do this by running the proxy server in "primary only" mode. This temporarily skips Duo authentication for all logins to RADIUS or LDAP configurations that use the default "fail safe" behavior for a specified amount of time (defaults to one hour). At then end of this time, the proxy automatically restarts in normal operating mode.

Primary only mode respects the failmode setting in any given section. If a RADIUS or LDAP section has failmode=secure then the authentication proxy in primary only mode won't allow users to skip Duo authentication and log in to the services using those configurations.

Primary only mode is available in version 2.14.0 and later.

Starting Primary Only Mode on Windows

  1. Open an administrative command prompt on your Duo proxy server.

  2. Run this command to restart the Duo Authentication Proxy in primary only mode for one hour:

    "C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_primary_only.exe"
    
  3. Keep the command prompt window open.

Starting Primary Only Mode on Linux

  1. SSH to your Duo proxy server.

  2. Run this command to restart the Duo Authentication Proxy in primary only mode for one hour:

    sudo /opt/duoauthproxy/bin/authproxy_primary_only
    
  3. Keep the SSH connection open.

Define the primary only mode duration by appending -t nn, where nn is the desired duration in minutes (to a maximum of 240).

Example command that runs the proxy service in primary only mode for 30 minutes:

sudo /opt/duoauthproxy/bin/authproxy_primary_only -t 30

If the command prompt window or SSH shell used to start the proxy in primary only mode closes while running, then the proxy continues running in primary only mode for the specified period of time but may not be able to restart the proxy service in regular operating mode when the primary only period ends. Should this happen, you would need to manually restart the authentication proxy service, and logins will fail until it is restarted.

If you interrupt or cancel the primary only command while it is running then the Duo proxy restarts in normal operating mode.

Primary Mode Logging

When the Duo Authentication Proxy starts in primary only mode, the authproxy.log output includes a line like this:

2019-02-04T17:27:57+0000 [-] Running in PRIMARY ONLY mode. Stopping in 60 minutes

Authentication events during primary only mode also indicate that Duo 2FA was skipped in the log output, like so:

Primary Only Mode - Secondary authentication bypassed

Additional Resources

Need some more help? Take a look at the Authentication Proxy Frequently Asked Questions (FAQ) page or try searching our Authentication Proxy Knowledge Base articles or Community discussions.

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

Level Up course: The Authentication Proxy in Action

For further assistance, contact Support.

Video References

Installing and Configuring the Authentication Proxy on Windows

View installation and configuration steps for different use cases for the Duo Authentication Proxy on a Windows server in this overview video.

References: Installation, Configuration, Client Sections and ad_client, Server Sections and radius_server_auto, Cloud Section, and Start the Proxy.

Installing and Configuring the Authentication Proxy on Linux

View Duo Authentication Proxy installation steps on a Linux server.

 

Reference: Installation.

Learn how to configure the Duo Authentication Proxy on Linux with a RADIUS server as the primary authentication source.

 

References: Client Sections: ad_client and Start the Proxy.

Troubleshooting and Additional Configuration Options

Discover troubleshooting utilities and additional configuration options for the Duo Authentication Proxy.

References: Using the Connectivity Tool, Using the Support Tool, Main Section, Encrypting Passwords, and Primary Only Mode.