:orphan: **************************** Cisco ASA RADIUS Integration **************************** Introduction ============ This document describes steps to configure a Cisco ASA with Swivel as the authentication server. Swivel can provide Two Factor authentication with `SMS `__, `Token `__, `Android `__, `iOS `__ and strong Single Channel Authentication `TURing `__, `Pinpad `__ or in the `Taskbar Client `__ using RADIUS. AnyConnect works with Swivel if started in the portal. Swivel integration is made using RADIUS authentication protocol with an option to configure the login page. Depending on your needs, you can modify the default customization object or create a new customization object. There are many ways to configure it to work with Swivel such as: - Username AD Password and Swivel Authentication (The most common method with AD authentication made against the LDAP server and OTC checked against Swivel using RADIUS) - Username AD Password and Swivel Authentication (AD authentication and OTC checked against Swivel using RADIUS) - Username and OTC (OTC checked against Swivel using RADIUS authentication) And various other options including local password. To use the Single Channel Image such as the `TURing `__ Image, the Swivel server must be made accessible. **The client requests the images from the Swivel server, and is usually configured using a NAT** (Network Address Translation), often with a proxy server. The Swivel virtual appliance or hardware appliance is configured with a proxy port to allow an additional layer of protection. For the Cisco IPSEC client Swivel integration see `Cisco IPSEC Client Integration `__ Configuration steps overview ---------------------------- - Configuring the Swivel server - Create a customization object to hold the attached Javascript. - Create an authentication server group with RADIUS protocol. - Create a connection profile (tunnel group) to link login URL, authentication server and custom login page together. Prerequisites ============= * Cisco ASA 8.03 or higher * Cisco documentation * AuthControl Sentry 3.x, 3.5 or higher for RADIUS groups * NAT for Single channel access Login Page customisation prerequisites -------------------------------------- :download:`Download: Cisco ASA 8 Logon Page Customisation Script ` .. note:: Beware if opening this in Wordpad or similar in case the text editor wraps the text onto a new line. This script can be used for `TURing `__, `SMS `__, `Token `__, `Android `__ or `iOS `__ . There is an alternative customisation for `Pinpad `__, available :download:`here `. For Single Channel TURing images some editing of the script is required. .. note:: The AuthControl Sentry server must be accessible by client when using Single Channel Images, such as the Turing Image or Pinpad, and security string number. Typically this external access is usually facilitated by a Firewall NAT rule. Baseline ======== * Cisco ASA version: 8.03, Also tested with 8.21 * AuthControl Sentry version: 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1 Architecture ============ The Cisco ASA makes authentication requests against the Swivel server by RADIUS. The client makes TURing requests against the Swivel server using HTTP/HTTPS. AuthControl Sentry Configuration ================================ Configuring the RADIUS server ----------------------------- On the AuthControl Sentry Administration console configure the RADIUS Server and NAS, see `RADIUS `__. .. _enabling_session_creation_with_username: Enabling Session creation with username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To allow the `TURing `__ image, `Pinpad `__ and other single channel images, under Server/Single Channel set `Allow session request by username `__ to Yes. .. _setting_up_swivel_dual_channel_transports: Setting up Swivel Dual Channel Transports ----------------------------------------- Used for `SMS `__, see `Transport Configuration `__. .. _cisco_asa_configuration: Cisco ASA Configuration ======================= .. _create_a_radius_authentication_server_group: Create a Radius Authentication Server Group ------------------------------------------- Authentication Server Group is used to hold necessary information about the Swivel server. Go to Remote Access VPN -> AAA/Local users -> AAA Server. Click on Add to add an AAA Server Group. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_AAA_Server_Screen.JPG Enter a name for Server Group, select RADIUS for Protocol and click OK. With the newly created server group name selected, click on Add on the right bottom to add a Swivel server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_AAA_Server_Configuration_Screen.JPG Enter Swivel server’s IP, authentication port and server secret key as indicated. Click on OK then Apply to save the AAA server group. .. _optional_create_a_secondary_authentication_server: Optional: Create a Secondary Authentication Server -------------------------------------------------- The login page can be configured to display Swivel as a primary or secondary authentication server. To use multiple authentication servers, they must be configured under Remote Access VPN -> AAA/Local users -> AAA Server. This example shows an AD Server being added. Go to Remote Access VPN -> AAA/Local users -> AAA Server. Click on Add to add an AAA Server Group. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_AAA_Local_Users_AAA_Server_Groups_AD.JPG Enter a name for Server Group, select NT Domain or Kerberos for Protocol and click OK. With the newly created server group name selected, click on Add on the right bottom to add a NT Domain Server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_AAA_Local_Users_AAA_Server_Groups_Add_AD.JPG Enter the AD server’s IP, Server port and Domain Controller hostname. Click on OK then Apply to save the AAA server group. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_AAA_Local_Users_AAA_Server_Groups_AD_Edit_AAA_Server.JPG This secondary authentication server then needs to be linked to the Connection Profile (see below). .. _create_a_connection_profile_tunnel_group: Create a Connection Profile (Tunnel Group) ------------------------------------------ Swivel can be defined as a Primary Authentication server or as a Secondary authentication server. Connection Profile is used to link authentication server group, URL used to access the ASA, and login page customization together. Go to Remote Access VPN -> Clientless SSL VPN Access -> Connection Profiles. Click on Add to add a connection profile. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_Connection_Profiles.JPG In Basic panel, enter a name, alias and select the AAA Server Group created. Swivel can be configured as the Primary authentication server or the secondary authentication server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_Connection_Profiles_New_Profile.JPG Click on Advanced then Clientless SSL VPN. Select the customization object created and add a Group URL used to access the ASA with Swivel authentication. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Selecting_the_Customisation.JPG Click on OK then Apply to save the Connection Profile. .. _optional_create_a_secondary_authentication_for_the_connection_profile_tunnel_group: Optional: Create a Secondary Authentication for the Connection Profile (Tunnel Group) ------------------------------------------------------------------------------------- This option has been configured using the Secondary Authentication server option available in ASA 8.21 Go to Remote Access VPN -> Clientless SSL VPN Access -> Connection Profiles, select the connection profile created above then select Edit. Expand the Advanced option list and select Secondary Authentication. Enter the Secondary server group required and if the username should be reused. Ensure the box *"Use primary username (Hide secondary username on login page)"* is ticked. Click on OK to save the settings. If AD is defined as the Primary authentication server then Swivel can be defined as the secondary AD server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_AAA_Connection_Profile_Secondary_Authentication.JPG .. _test_the_radius_authentication: Test the RADIUS authentication ------------------------------ At this stage it should be possible to authenticate by `SMS `__, hardware `Token `__, `Mobile Phone Client `__ and `Taskbar `__ to verify that the RADIUS authentication is working for users. Browse to the SSL VPN login page, and enter Username and if being used, the password. From the Swivel Administration console select User Administration and the required user then `View Strings `__, and select an appropriate authentication string or OTC for the user. At the SSL VPN login enter the required OTC. Check the Swivel logs for a RADIUS success or rejected message. If no RADIUS message is seen, check that the Swivel RADIUS server is started and that the correct ports are being used. .. _optional_login_page_customisation: Optional: Login Page Customisation ---------------------------------- If the Swivel Single Channel Image is to be used, then the login page needs to be customised. If single channel authentication is not required, or other page modifications such as for SMS on Demand buttons, then this section can be skipped. The login page customization is used to insert necessary Javascript to retrieve Swivel Turing image. In ASDM, go to Remote Access VPN ->Clientless SSL VPN Access -> Portal -> Customization. Click on Add to add a new customization object. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Add_Customisation.JPG Enter a name for the object, click on OK then Apply. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Add_Customisation_selecting_PINsafe.JPG With the new object selected, click on Edit to enter the Customization Editor. Click on the Information Panel menu item. Note: If the information panel has been moved to a different location then the script can be added to the Copyright panel instead. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Customisation_Editor.JPG .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Customisation_Editor_Information_Panel.JPG Change Mode to “Enable”. Modify the pinsafeurl variable in the Cisco ASA 8 customisation Script to reflect your Swivel server’s URL. (The scripts are located at the top of the page under prerequisites). Paste the modified content into the Text box. Click on Save on the top right corner of the Customization Editor to save the object. WARNING: the Panel Position must be set to Right for the script to work. This is so that the customisation script is rendered after the logon form. If you particularly need the information panel to be on the left, put the Swivel customisation script in the Copyright Panel instead, as that is always rendered at the bottom. The following elements need to be modified in the script: .. code-block:: none //Modify the value of primary to reflect the URL of your PINsafe server //if using on-demand SMS, url will need to be DCMessage rather the SCImage //if using an HA pair and you wish the page to try one server then the other to receive a TURING //set standby to be the url of the standby swivel virtual or hardware appliance and set ha to true; var primary='https://demo.swivelsecure.com:8443/proxy/SCImage?username='; var standby='https://demo.swivelsecure.com:8443/proxy/SCImage?username='; var pinsafeurl = primary; var ha = false ; //set HA to true if you want the page to try two servers var loadTimeout = 2500; //how long the page waits (in milliseconds) for the image to be served from the main server before trying the secondary var secondaryAuth = true; // set to true if you want Swivel to be the secondary authentication option var button = true; //set to true if you want to show a button that requests a security string var autoShow = true; // set to true to show the TURing image automatically after entering the username Note that for the Pinpad version, SCImage will be replaced with SCPinPad. The primary and standby should be modified. If a standby is not used then set var secondaryAuth = false For a virtual or hardware appliance: .. code-block:: none var primary='https://demo.swivelsecure.com:8443/proxy/SCImage?username='; To use multiple security strings in an SMS message, this can be modified to show the next security string which should be entered. For a virtual or hardware appliance: .. code-block:: none var pinsafeurl='https://demo.swivelsecure.com:8443/proxy/DCIndexImage?username='; The text can also be changed to reflect the request for a security string index number. See also `Multiple Security Strings How To Guide `__ .. code-block:: none "Please enter your user name and click on Get OTP Index"; The Button to request the Security String Index can also be edited: .. code-block:: none obj[0].value="Get OTP Index"; The Logon Form can be edited to suit the language and secondary authentication password message. Select the Logon Form to display the fields available. AuthControl Sentry as the primary authentication server, AD as the secondary authentication server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_AAA_SSL_VPN_Customization_Logon_Form.JPG AD as the primary authentication server, AuthControl Sentry as the secondary authentication server. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_Logon_Form_Page_modification_Swivel_secondary_auth.jpg Testing ======= Now the configuration is complete. You can use the configured Group URL to access the ASA with AuthControl Sentry authentication. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_OTP_login.JPG If configured, a Domain Password prompt will appear. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Customised_login_form.JPG Before the user name is entered, the OTP (One Time Password) field is grayed out. Enter a user name and click on Get OTP. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_OTP_Turing_login.JPG OTP login with Domain Password .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_803_Customised_login_form_with_Turing.JPG Use your PIN to extract the OTP and enter it in the OTP field. If everything is configured correctly, you will see the portal page after clicking on Login. Please note that the Javascript to retrieve the Turing image is executed at the user’s browser. Therefore, the user’s PC must have access to the AuthControl Sentry URL. It is highly recommended that you configure your AuthControl Sentry server to use SSL/https to protect the session. Also if you are using a AuthControl Sentry virtual or hardware appliance, the image can be requested via the built-in image proxy. The below screen shot shows the use of the Security String Index to tell the user which of their multiple security Strings to use. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_login_multi_sms_OTP_and_Password.JPG The below security screen shows a login screen with Turing and SMS on Demand login options. .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_login_request_sms_OTP_and_Password_blank.JPG .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_login_request_sms_turing_OTP_and_Password.JPG .. image:: images/Integration/RADIUS/CiscoASA/Cisco_ASA_821_login_request_sms_or_swivlet_OTP_and_Password.JPG .. _additional_configuration_options: Additional Configuration Options ================================ The Cisco server can be configured to use multiple authentication servers such as Active Directory. Two Stage and Challenge/Response authentication can also be configured. The integration uses Swivel as the primary authentication server and AD as the secondary authentication server. It would be possible to change this order. If you need to reference the secondary password label or field, the IDs are "secondary_password_field" and "secondary_password_input" respectively. For example, if you want to change the secondary password prompt from within the customised script, use the following: .. code-block:: none obj=document.getElementById("secondary_password_field"); if(obj) { obj.innerHTML="AD password"; } .. _customisation_for_one_touch_push: Customisation for One Touch / Push ---------------------------------- This section describes how to customise the Cisco ASA login page to support Push authentication (previously One Touch). In order to use One Touch with Cisco ASA, you must have the AuthControl Sentry software version 3.11.5 or later. Before applying this customisation, read the `article on One Touch `__ to ensure that the AuthControl Sentry Appliance is prepared. Follow the instructions on customisation `above <#Optional:_Login_Page_Customisation>`__ up to the point where the information panel is enabled. Now insert the following in the information panel: .. code-block:: none Troubleshooting =============== Check the AuthControl Sentry logs for Turing images and RADIUS requests. `Image from PINsafe server absent `__ **Login page modifications absent** This can be caused if the script has been altered with line feeds inserted in a text editor from wrap around text. View the login page source and see if it contains the page modifications, and are not being displayed correctly. **TURing image doesn't change** If you are repeatedly shown the same TURing image for multiple logins, or after refreshing the page, this may be due to page caching settings in your browser. To avoid this problem, change one line in the customisation. Search for the string: .. code-block:: none obj.innerHTML += '

'; and replace it with the following: .. code-block:: none obj.innerHTML += '

'; This results in a different URL every time the TURing image is displayed, thereby avoid problems with caching. .. _known_issues_and_limitations: Known Issues and Limitations ============================ None .. _additional_information: Additional Information ====================== We have a customised AnyConnect VPN client available for testing. Please see `here `__ for more details. For assistance in Swivel installation and configuration please firstly contact your reseller and then email Swivel Secure support at support@swivelsecure.com