Duo Authentication Proxy - Reference

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.

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.

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:

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.

duoauthproxy-version.exe /S

duoauthproxy-version.exe /S /exclude-auth-proxy-manager

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

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:

duoauthproxy-version.exe /S

duoauthproxy-version.exe /S /exclude-auth-proxy-manager

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

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.

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

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.

Configuration

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

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.

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"`

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:

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:

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

search_dn=DC=example,DC=com

Optional

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

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

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

Optional

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

Optional

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

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

Optional

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

Optional

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

Optional

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

Optional

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

Optional

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

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

Optional

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

net start DuoAuthProxy

authproxyctl start

net stop DuoAuthProxy & net start DuoAuthProxy

authproxyctl restart

# /opt/duoauthproxy/bin/authproxyctl start

# /opt/duoauthproxy/bin/authproxyctl status

# /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 Applications → Authentication Proxy. The dashboard will display a table with the name, hostname, status, and version for each of your Authentication Proxies.

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.

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.

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:

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:

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:

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.