Walkthrough Video

First Steps

Before starting, make sure that Duo is compatible with your Cisco ASA device. Log on to your Cisco ASDM interface and verify that your Cisco ASA firmware is version 8.3 or later.

You should also have a working primary authentication configuration for your SSL VPN users, e.g. LDAP authentication to Active Directory.

Then you’ll need to:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate Cisco SSL VPN in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)
4. Download the Duo Cisco package from your Cisco SSL VPN application’s properties page in the Duo Admin Panel, and unzip it somewhere convenient such as your desktop.

Modify the sign-in page

To add the Duo customization to your Cisco sign-in page:

1. Log on to your Cisco ASA administrator web interface (ASDM).
2. Click the Configuration tab and then click Remote Access VPN in the left menu.
3. Navigate to Clientless SSL VPN Access → Portal → Web Contents. Then click Import.
4. In the Source section, select Local computer, click Browse Local Files…, and find the Duo-Cisco-vX.js file extracted from the Duo-Cisco-vX-accountid.zip file downloaded earlier from the Duo admin console where vX will reflect the actual version of the Duo Cisco package and accountid is your organization’s Duo Account ID (visible on the Settings tab of the Duo Admin Panel) i.e. Duo-Cisco-v5-1234-5678-90.zip). After the file is selected, Duo-Cisco-vX.js will appear in the Web Content Path box.
5. In the Destination section, select No in response to “Require authentication to access its content?”
6. Click Import Now then click Apply
   
7. Navigate to Clientless SSL VPN Access → Portal → Customization, select the Customization Object you want to modify, and then click Edit.
8. In the outline on the left, click Title Panel (under Logon Page).
9. Then type <script src="/+CSCOU+/Duo-Cisco-vX.js"></script> (replacing vX with the file version actually downloaded) in the Text: box. Click OK.
10. Click Apply

Add the Duo LDAP server

1. Navigate to AAA/Local Users → AAA Server Groups, click Add, and fill out the form:

   Server Group	Duo-LDAP
   Protocol	LDAP

   
   
2. Click OK.
3. Select the Duo-LDAP group you just added.

4. In the Servers in the Selected Group section, click Add and fill out the form:

   Interface Name	Choose your external, internet-facing interface (it may be called “outside”)
   Server Name or IP Address	Your API hostname (i.e. api-XXXXXXXX.duosecurity.com)
   Timeout	60 seconds

5. Check Enable LDAP over SSL and fill out the form (replacing INTEGRATION_KEY and SECRET_KEY with your application-specific keys) :

   Server Port	636
   Server Type	— Detect Automatically/Use Generic Type —
   Base DN	dc=INTEGRATION_KEY,dc=duosecurity,dc=com
   Scope	One level beneath the Base DN
   Naming Attribute(s)	cn
   Login DN	dc=INTEGRATION_KEY,dc=duosecurity,dc=com
   Login Password	SECRET_KEY

   
   
6. Click OK.
7. Click Apply.

Configure the Duo LDAP server

1. Navigate to Clientless SSL VPN Access → Connection Profiles
2. Select the connection profile near the bottom and click Edit (the connection profile might be called “DefaultWEBVPNGroup”).
3. Choose Secondary Authentication (under Advanced) from the left menu.
4. Select Duo-LDAP from the Server Group list.
5. Uncheck the Use LOCAL if Server Group fails check box.
6. Check the Use primary username check box.
   
7. Click OK.
8. Click Apply.

Configure AnyConnect

If any of your users will be logging in through desktop or mobile AnyConnect clients (click here to learn more about Duo and AnyConnect), you’ll need to increase the AnyConnect Authentication Timeout so that users have enough time to use Duo Push or phone callback. Here’s how:

1. Navigate to Configuration → Remote Access VPN → Network (Client) Access → AnyConnect Client Profile
2. Click Edit
3. In the left menu, navigate to “Preferences (Part 2)”.
4. Scroll to the bottom of the page and modify the “Authentication Timeout (seconds)” setting to 60 seconds.
   
5. Click OK.
6. Click Apply to activate the new AnyConnect Client settings.

You now have an increased authentication timeout. This timeout will take effect after each client successfully logs into the VPN after applying the new profile.

Test Your Setup

Visit your Cisco ASA SSL VPN Service URL (it usually ends in /+CSCOE+/logon.html). After you complete primary authentication, the Duo enrollment/login prompt appears.

Using AnyConnect? Users see a “Second Password” field when using the AnyConnect client. This field accepts the name of a Duo factor, like “push” or “phone”, or a Duo passcode (generated with Duo Mobile or sent via SMS). Learn how Duo works with desktop and mobile AnyConnect clients.

Troubleshooting

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

Network Diagram

1. Cisco SSL VPN connection initiated
2. Primary authentication
3. Cisco ASA connection established to Duo Security over TCP port 636
4. Secondary authentication via Duo Security’s service
5. Cisco ASA receives authentication response
6. Cisco SSLVPN connection established

CLI Setup

You can configure Duo on your ASA using the Cisco command line.

1. SSH into your ASA and access the config terminal.

   login as: asaadmin
   asaadmin@ciscoasa's password:
   Type help or '?' for a list of available commands.
   ciscoasa> enable
   Password: ********
   ciscoasa# config
   ciscoasa# config terminal
   ciscoasa(config)#
   

2. Enable scopy if not already permitted.

   ciscoasa(config)# ssh scopy enable
   

3. Use scopy (scp or pscp) to upload the Duo sign-in page customizations (downloaded from your Cisco SSL VPN application’s properties page in the Duo Admin Panel page back in step 3 of “First Steps”) to your ASA.

   c:\>pscp.exe c:\Duo-Cisco-v5.js asaadmin@ciscoasa:Duo-Cisco.v5.js
   asaadmin@ciscoasa's password: ********
   Duo-Cisco-v5.js      | 71 kB |  35.9 kB/s | ETA: 00:00:00 | 100%
   

   Then import the new web content package.

   ciscoasa(config)# import webvpn webcontent /+CSCOU+/Duo-Cisco-v5.js disk0:Duo-Cisco-v5.js
   * Web resource `+CSCOU+/Duo-Cisco-v5.js' was successfully initialized
   

4. Export a web customization object for modification. The default customization object is named “DfltCustomization”.

   ciscoasa(config)# export webvpn customization DfltCustomization disk0:/DfltCustomization
   %INFO: Customization object 'DfltCustomization' was exported to disk0:/DfltCustomization
   

   Then download the exported customization object from the ASA.

   c:\>pscp.exe asaadmin@ciscoasa:disk0:/DfltCustomization DfltCustomization
   asaadmin@ciscoasa's password:
   DfltCustomization         | 9 kB |   9.6 kB/s | ETA: 00:00:00 | 100%
   

5. Open the downloaded web customization object in an XML editor. Edit the “title-panel” section of the page to add the path to the Duo-Cisco-v5.js file you just uploaded to the ASA. The edit should be as follows:

    <text l10n="yes"><![CDATA[<script src="/+CSCOU+/Duo-Cisco-v5.js"></script>]]></text> 

   

   Save the modified DfltCustomization file and upload it back to the ASA.

   c:\>pscp.exe DfltCustomization asaadmin@ciscoasa:disk0:/DfltCustomization
   asaadmin@ciscoasa's password:
   DfltCustomization         | 9 kB |   9.6 kB/s | ETA: 00:00:00 | 100%
   

   Then import the modified customization object from the ASA command line.

   ciscoasa(config)# import webvpn customization DfltCustomization disk0:/DfltCustomization
   %INFO: customization object 'DfltCustomization' was successfully imported
   

6. Add the Duo LDAP server. To do this, create the LDAP AAA Server Group.

   ciscoasa(config-aaa-server-group)# aaa-server Duo-LDAP protocol ldap
   

   Then, add the Duo LDAP server, using your external, internet-facing interface and the following information:

   Host	Your API hostname (i.e. api-XXXXXXXX.duosecurity.com)
   Server Port	636
   Timeout	60
   Base DN	dc=INTEGRATION_KEY,dc=duosecurity,dc=com
   Login DN	dc=INTEGRATION_KEY,dc=duosecurity,dc=com
   Login Password	SECRET_KEY
   Naming Attribute(s)	cn
   LDAP over SSL	enable

   ciscoasa(config-aaa-server-group)# aaa-server Duo-LDAP (outside) host api-xxxxxxxx.duosecurity.com
   ciscoasa(config-aaa-server-host)# server-port 636
   ciscoasa(config-aaa-server-host)# timeout 60
   ciscoasa(config-aaa-server-host)# ldap-base-dn dc=DIXXXXXXXXXXXXXXXXXX,dc=duosecurity,dc=com
   ciscoasa(config-aaa-server-host)# ldap-login-dn dc=DIXXXXXXXXXXXXXXXXXX,dc=duosecurity,dc=com
   ciscoasa(config-aaa-server-host)# ldap-login-password ************
   ciscoasa(config-aaa-server-host)# ldap-naming-attribute cn
   ciscoasa(config-aaa-server-host)# ldap-over-ssl enable
   ciscoasa(config-aaa-server-host)# exit
   

7. Edit the SSL VPN Connection Profile so that the Duo-LDAP server is used for secondary authentication. (In the example below the connection profile is called “VPNConnectionProfile”).

   ciscoasa(config)# tunnel-group VPNConnectionProfile general-attributes
   ciscoasa(config-tunnel-general)# secondary-authentication-server-group Duo-LDAP use-primary-username
   INFO: This command applies only to SSL VPN - Clientless and AnyConnect.
   ciscoasa(config-tunnel-general)# exit
   

8. If your users log in with the AnyConnect desktop or mobile clients increase the authentication timeout in the AnyConnect profile. This will give users enough time to approve the Duo authentication request.

   First, download the AnyConnect Client Profile XM file (normally called “DefaultProfile.xml”).

   c:\>pscp.exe asaadmin@ciscoasa:disk0:DefaultProfile.xml .\DefaultProfile.xml
   asaadmin@ciscoasa's password:
   DefaultProfile.xml        | 2 kB |   2.0 kB/s | ETA: 00:00:00 | 100%
   

   Edit the downloaded XML file add change the AuthenticationTimeout to 60 seconds. The edit should be as follows:

   <AuthenticationTimeout>60</AuthenticationTimeout>
   

   

   Save the modified AnyConnect XML connection profile file and upload it back to the ASA.

   c:\>pscp.exe DefaultProfile.xml asaadmin@ciscoasa:disk0:/DefaultProfile.xml
   asaadmin@ciscoasa's password:
   DefaultProfile.xml        | 2 kB |   2.0 kB/s | ETA: 00:00:00 | 100%