Duo Two-Factor Authentication with LDAPS for Cisco ASA SSL VPN with Browser and Secure Client

Overview

This Duo ASA SSL VPN configuration supports inline self-service enrollment and the Duo Prompt for web-based VPN logins, and push, phone call, or passcode authentication for AnyConnect or Secure Client desktop and mobile client connections that use SSL encryption.

Your ASA device makes a direct connection to Duo's cloud service using LDAPS. LDAPS authentications do not report a client IP address when the client is used. There is no configurable fail mode for LDAPS connections, so if your device cannot contact Duo's service your users won't be able to log in with Duo.

This integration expressly supported Cisco ASA VPN and is not guaranteed to work with any other VPN solution.

The AnyConnect RADIUS configuration does not feature the interactive Duo Prompt for web-based logins, but that configuration does capture client IP information for use with Duo policies, such as geolocation and authorized networks, and offers configurable fail mode.

The SAML VPN deployment features inline enrollment and authentication in the Duo Universal Prompt for both web-based VPN logins and AnyConnect 4.6+ client logins. This deployment option features Duo Single Sign-On, our cloud-hosted SAML 2.0 identity provider. Primary and Duo secondary authentication occur at the identity provider, not at the ASA itself.

Please refer to the Duo & AnyConnect or Cisco Secure Client Overview to learn more about supported options for protecting ASA logins with Duo MFA.

If you need to protect connections that use Cisco's desktop VPN client (IKE encryption), use our Cisco IPSec instructions.

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.

First Steps

Before moving on to the deployment steps, it's a good idea to familiarize yourself with Duo administration concepts and features like options for applications, available methods for enrolling Duo users, and Duo policy settings and how to apply them. See all Duo Administrator documentation.

You should already have a working primary authentication configuration for your SSL VPN users before you begin to deploy Duo, 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. Find your existing Cisco ASA SSL VPN application and click to view the application details. Note that as of September 7, 2023, you cannot create new applications of this type.
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. This file is customized for your account and has your Duo account ID appended to the file name (after the version). You will need to upload this to your ASA.
5. If your ASA software version is 9.13(1) or later, download the DigiCert High Assurance EV Root CA and DigiCert Global Root CA certificates from the DigiCert site for installation on your ASA.

Install CA Certificates

ASA software versions 9.13(1) and later perform certificate validation for secure LDAP connections, which requires that you upload the certificate chains used for the connection to Duo to your device. If you plan to update to 9.13(1) or later after configuring Duo, it's a good idea to install the CA certificates for Duo connectivity now.

Install the DigiCert CA Certificates

Duo's cloud service currently secures SSL traffic with certificates issued by DigiCert. If your device is running 9.13(1) you'll need to install the DigiCert CA certificates on your ASA so that it can establish the secure LDAP connection to Duo.

To install the DigiCert CA certificates used by Duo's service on your ASA:

1. If you did not already do so, download the DigiCert High Assurance EV Root CA and DigiCert Global Root CA certificates from the DigiCert site for installation on your ASA.

2. Log on to your Cisco ASA administrator web interface (ASDM).

3. Click the Configuration tab and then click Device Management in the left menu.

4. Navigate to Certificate Management → CA Certificates.

5. Click the Add button.

6. In the "Install Certificate" window, select the Install from a file option and then click the Browse... button.

7. Select the DigiCert High Assurance EV Root CA file you downloaded from DigiCert (DigiCertHighAssuranceEVRootCA.crt) and click Install.

8. Click the Install Certificate button and then click Send on the "Preview CLI Commands" prompt. The DigiCert Root is installed.

9. Repeat steps 4-8 to install the DigiCert Global Root CA certificate (DigiCertGlobalRootCA.crt).

10. Verify that both DigiCert CA certificates are listed.

    

With all necessary CA certificates uploaded to your device, proceed to the next section.

Modify the Sign-in Page

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

1. While still logged in to your Cisco ASA administrator web interface (ASDM), click the Configuration tab and then click Remote Access VPN in the left menu.

2. Navigate to Clientless SSL VPN Access → Portal → Web Contents. Then click Import.

3. 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. You must use the .js file from the Duo package customized for your account. Uploading the file customized for the wrong account can cause authentication failures.

   After the file is selected, Duo-Cisco-vX.js will appear in the Web Content Path box.

4. In the Destination section, select No in response to "Require authentication to access its content?"

5. Click Import Now then click Apply
   

6. Navigate to Clientless SSL VPN Access → Portal → Customization, select the Customization Object you want to modify, and then click Edit.

7. In the outline on the left, click Title Panel (under Logon Page).

8. Then type <script src="/+CSCOU+/Duo-Cisco-vX.js"></script> (replacing vX with the file version actually downloaded) in the Text: box. Click OK.

9. 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.
8. You can verify connectivity to the Duo LDAP server now. With the Duo AAA server group you just created selected, click the Test button.
9. On the "Test AAA Server" form, select Authentication.
10. Enter the username of user that exists in Duo and has a valid authentication device (like a phone or token).
11. Instead of entering the user's password, enter the name of an authentication method valid for that user, like push or phone, or a passcode, and then click OK.
12. If you entered push or phone, approve the Duo authentication request.
13. A new form pops up letting you know if the test was successful or failed.

Configure the Duo LDAP Server

1. Navigate to Clientless SSL VPN Access → Connection Profiles
2. Select the connection profile to which you want to add Duo Authentication near the bottom and click Edit. This can be the default connection profile "DefaultWEBVPNGroup" or another existing connection profile.
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.

Click Save to write all changes to the ASA device memory.

Configure Secure Client

If any of your users will be logging in through desktop or mobile clients (click here to learn more about Duo and Secure Client), you'll need to increase the client 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 → Secure 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 Client settings.
7. Click Save to write this change to the ASA device memory.

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.

If you find that AnyConnect client connections disconnect after about 12 seconds please see the following FAQ: Why is the AnyConnect client connection attempt disconnecting after 12 seconds when I have increased the timeout?

Test Your Setup

SSL VPN in Browser

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.

AnyConnect or Secure Client

Users see a "Second Password" field when using the client, which cannot be left blank.

Enter the primary username and password, and a Duo factor option as the second password. Choose from:

push	Perform Duo Push authentication You can use Duo Push if you've installed and activated Duo Mobile on your device.
phone	Perform phone callback authentication.
sms	Send a new batch of SMS passcodes. Your authentication attempt will be denied. You can then authenticate with one of the newly-delivered passcodes.
A numeric passcode	Log in using a passcode, either generated with Duo Mobile, sent via SMS, generated by your hardware token, or provided by an administrator. Examples: "123456" or "2345678"

You can also specify a number after the factor name if you have more than one device enrolled (as the automatic push or phone call goes to the first capable device attached to a user). So you can enter push2 or phone2 if you have two phones enrolled and you want the authentication request to go to the second phone.

Troubleshooting

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

Network Diagram

1. Cisco SSL VPN connection initiated
2. Primary authentication to on-premises directory
3. Cisco ASA connection established to Duo Security over TCP port 636
4. User completes Duo two-factor authentication via the interactive web prompt served from Duo's service or text input to the ASA and their selected authentication factor.
5. Cisco ASA receives authentication response
6. Cisco SSL VPN connection established

CLI Setup

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

Convert and Import DigiCert CA Certificates

The CA certificates downloaded from DigiCert are in binary format. You need to convert them to base-64 PEM format in order to add them to the ASA from the CLI. You can do this with OpenSSL.

1. Open a terminal prompt and change directory (cd) to the location where you saved the DigiCert CA .crt files you downloaded earlier.

2. Enter the following to convert the DigiCert High Assurance EV Root CA file to PEM:

   openssl x509 -inform DER -outform PEM -in DigiCertHighAssuranceEVRootCA.crt -out DigiCertHighAssuranceEVRootCA.pem
   

3. Enter the following to convert the DigiCert Global Root CA file to PEM:

   openssl x509 -inform DER -outform PEM -in DigiCertGlobalRootCA.crt -out DigiCertGlobalRootCA.pem
   

4. SSH into your ASA again if no longer connected 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 terminal
   ciscoasa(config)#
   

5. Enter the following to begin uploading the DigiCert High Assurance EV Root CA (the example trustpoint name is ASDM_TrustPoint1):

   ciscoasa(config)#crypto ca trustpoint ASDM_TrustPoint1
   ciscoasa(config-ca-trustpoint)# revocation-check none
   ciscoasa(config-ca-trustpoint)# no id-usage
   ciscoasa(config-ca-trustpoint)# enrollment terminal
   

6. Open the DigiCertHighAssuranceEVRootCA.pem file in a text editor (like Notepad), and copy the entire contents of the file (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines). Paste the certificate text into your terminal when prompted, followed by a carriage return and quit.

   ciscoasa(config-ca-trustpoint)# crypto ca authenticate ASDM_TrustPoint1
   Enter the base 64 encoded CA certificate. End with the word "quit" on a line by itself
   -----BEGIN CERTIFICATE-----
   MIIDxTCCAq2gAwIBAgIQAqxcJmoLQJuPC3nyrkYldzANBgkqhkiG9w0BAQUFADBs
   MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
   d3cuZGlnaWNlcnQuY29tMSswKQYDVQQDEyJEaWdpQ2VydCBIaWdoIEFzc3VyYW5j
   ZSBFViBSb290IENBMB4XDTA2MTExMDAwMDAwMFoXDTMxMTExMDAwMDAwMFowbDEL
   MAkGA1UEBhMCVVMxFTATBgNVBAoTDERpZ2lDZXJ0IEluYzEZMBcGA1UECxMQd3d3
   LmRpZ2ljZXJ0LmNvbTErMCkGA1UEAxMiRGlnaUNlcnQgSGlnaCBBc3N1cmFuY2Ug
   RVYgUm9vdCBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMbM5XPm
   +9S75S0tMqbf5YE/yc0lSbZxKsPVlDRnogocsF9ppkCxxLeyj9CYpKlBWTrT3JTW
   PNt0OKRKzE0lgvdKpVMSOO7zSW1xkX5jtqumX8OkhPhPYlG++MXs2ziS4wblCJEM
   xChBVfvLWokVfnHoNb9Ncgk9vjo4UFt3MRuNs8ckRZqnrG0AFFoEt7oT61EKmEFB
   Ik5lYYeBQVCmeVyJ3hlKV9Uu5l0cUyx+mM0aBhakaHPQNAQTXKFx01p8VdteZOE3
   hzBWBOURtCmAEvF5OYiiAhF8J2a3iLd48soKqDirCmTCv2ZdlYTBoSUeh10aUAsg
   EsxBu24LUTi4S8sCAwEAAaNjMGEwDgYDVR0PAQH/BAQDAgGGMA8GA1UdEwEB/wQF
   MAMBAf8wHQYDVR0OBBYEFLE+w2kD+L9HAdSYJhoIAu9jZCvDMB8GA1UdIwQYMBaA
   FLE+w2kD+L9HAdSYJhoIAu9jZCvDMA0GCSqGSIb3DQEBBQUAA4IBAQAcGgaX3Nec
   nzyIZgYIVyHbIUf4KmeqvxgydkAQV8GK83rZEWWONfqe/EW1ntlMMUu4kehDLI6z
   eM7b41N5cdblIZQB2lWHmiRk9opmzN6cN82oNLFpmyPInngiK3BD41VHMWEZ71jF
   hS9OMPagMRYjyOfiZRYzy78aG6A9+MpeizGLYAiJLQwGXFK3xPkKmNEVX58Svnw2
   Yzi9RKR/5CYrCsSXaQ3pjOLAEFe4yHYSkVXySGnYvCoCWw9E1CAx2/S6cCZdkGCe
   vEsXCS+0yx5DaMkHJ8HSXPfqIbloEpw8nL+e/IBcm2PN7EeqJSdnoDfzAIJ9VNep
   +OkuE6N36B9K
   -----END CERTIFICATE-----
   quit
   

7. Accept the certificate when prompted by typing yes.

   INFO: Certificate has the following attributes:
   Fingerprint:     d474de57 5c39b2d3 9c8583c5 c065498a
   Do you accept this certificate? [yes/no]: yes
   
   Trustpoint CA certificate accepted.
   
   % Certificate successfully imported
   ciscoasa(config)#
   

8. Repeat steps 5-7 to import the DigiCertGlobalRootCA.pem certificate, using a different trustpoint name than the one you used earlier.

9. Verify that the DigiCert CA certificates are present.

   ciscoasa-9x(config)# show crypto ca trustpoints
   
   Trustpoint ASDM_TrustPoint0:
       Configured for self-signed certificate generation.
   
   Trustpoint ASDM_TrustPoint1:
       Subject Name:
       cn=DigiCert High Assurance EV Root CA
       ou=www.digicert.com
       o=DigiCert Inc
       c=US
             Serial Number: 02ac5c266a0b409b8f0b79f2ae462577
       Certificate configured.
   
   Trustpoint ASDM_TrustPoint2:
       Subject Name: 
       cn=DigiCert Global Root CA
       ou=www.digicert.com
       o=DigiCert Inc
       c=US
             Serial Number: 083be056904246b1a1756ac95991c74a
   Certificate configured.
   

Upload the Duo Sign-in Page

1. SSH into your ASA again if no longer connected 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%
   

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

Add the Duo LDAP Server

1. SSH into your ASA again if no longer connected 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. 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
   

3. 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 Secure Client.
   ciscoasa(config-tunnel-general)# exit
   

4. It's a good idea to write your changes to memory when done.

   ciscoasa-9x(config)# write mem
   Building configuration...
   Cryptochecksum: a131c143 0de517bc 23861c2b b1c71cc8
   
   52064 bytes copied in 1.520 secs (52064 bytes/sec)
   [OK]
   

Configure Secure Client

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

1. Download the 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%
   

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

   <AuthenticationTimeout>60</AuthenticationTimeout>
   

   

3. Save the modified 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%