Document ID: 100586
Cisco Adaptive Security Appliance (ASA) 5500 series software version 8.0 introduces advanced customization features which enable the development of attractive web portals for clientless users. This document details the many options available to customize the login page, or welcome screen, and the web-portal page.
Cisco recommends that you have knowledge of how to use the Cisco Adaptive Security Device Manager (ASDM) in order to configure group-policies and connection profiles on ASA.
Refer to these documents for general information:
Prior to setting up a customized web-portal, you must complete some basic ASA configuration steps. See the Configuration Requirements section of this document for more information.
The information in this document is based on these software and hardware versions:
Cisco ASA version 8.x
Cisco ASDM version 6.x
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.
You must configure the ASA in preparation for the customization steps presented in this document.
Complete these steps:
In ASDM, choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Group Policies in order to create a group policy, Marketing for example, and check the Clientless SSL VPN check box under tunneling protocol.Figure 1: Create a New Group Policy (Marketing)
Choose Configuration > Remote Access VPN > Clientless SSL VPN > Connection Profiles in order to create a connection profile, such as sslclient, along with the required authentication server details, AAA server for example, and assign the Marketing group policy.Figure 2: Create a New Connection Profile (sslclient)
In order to continue the connection profile configuration, click Advanced and configure a group-url for the connection profile.Figure 3: Configure Group-URLs for the Connection Profile
Note: In this example, the group-url is configured in three different formats. The user can enter any one of them in order to connect to the ASA through the sslclient connection profile.
Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Portal > Customization, and add these two customization objects:
Note: Figure 4 illustrates how to create the Custom_Login object. Repeat the same steps in order to add the Custom_Marketing customization object. However, do not edit these customization objects at this time. Various configuration options are discussed in subsequent sections of this document.
Refer to Cisco Technical Tips Conventions for more information on document conventions.
In a typical clientless scenario, a remote user enters the FQDN of the ASA into a browser in order to log onto it. From there, a login page, or welcome screen, appears. After successful authentication, the user views a web-portal with all the authorized applications.
In versions earlier than 8.0, the web-portal supports limited customization, which means that all the ASA users experience the same web pages. These web pages, with limited graphics, are very much deviant from typical intranet pages.
ASA introduces a full customization feature, which enables the integration of the “login” functionality with your existing web pages. In addition, there are significant improvements to the customization of the web-portal. The examples in this document enable you to customize ASA pages to have a look and feel similar to your existing intranet pages, which provides a more consistent user experience when ASA pages are browsed.
The various customization options strengthens the ability of ASA to provide virtualization during the user experience. For example, a Marketing group can be presented with a login-page and web-portal which have a completely different look and feel than the pages presented to Sales or Engineering groups.
ASA supports two different types of WebVPN pages that are customizable.
When a user enters the https://asa.cisco.com/sslclient group-url into a browser in order to connect to the ASA, this default login page appears:Figure 5: Default Login Page
In order to modify this login page, you edit the customization associated with the connection profile. The steps required to modify this customization appear in the Customize Login Page section of this document. For now, complete these steps:
Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Connection Profiles.
Edit the sslclient connection profile, and associate the Custom_Login customization with this connection profile.
After the user is authenticated, this default1 web-portal page appears:Figure 7: Default Portal Page
1. This assumes all the plug-ins (VNC, ICA, SSH and RDP) are enabled. If the plug-ins are not enabled, you would not notice their tabs.
In order to modify this web-portal, you edit the customization associated with the group policy. The steps required to modify this customization appear in the Customize Web Portal of this document. For now, complete these steps:
Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Group Policies.
Edit the Marketing group policy, and associate the Custom_Marketing customization with this group policy.
Note: Multiple connection profiles, each with their own authentication scheme, such as RADIUS, LDAP, or Certificates, can be associated with a single group policy. Therefore, you have the option to create multiple login pages, for example one login customization for each connection profile, and they can all be associated with the same web-portal customization that is associated with the Marketing group policy.
This is a sample customized web portal:Figure 9: Customized Web Portal Page
Notice that the page has a title with a gradient color scheme, a logo for Marketing, a few web bookmarks with thumbnails, an RSS Feed and a custom intranet page. The custom intranet page allows the end-user to navigate their intranet page and simultaneously use the other tabs on the web-portal.
Note: You still need to retain the web-page lay-out with top and left frames, which means that, strictly speaking, this page is not fully customizable. You can change many small components to get as close a look as possible to your intranet portals.
This section covers how to configure each individual component in the web-portal with the customization editor in ASDM.Figure 10: Title Panel
In order to configure the title panel, these customization options are enabled:Figure 11: Customization Editor: Title Panel Configuration
In order to customize the logo in the title panel, upload the logo image to ASA.Figure 12: Upload Logo File marketing.gif as Webcontent to ASA
Choose Clientless SSL VPN Access > Portal > Web Contents, click Import, and provide the path to the logo file on your local computer. Upload it as web content in the /+CSCOU+/ directory.
Enter the /+CSCOU+/marketing.gif logo URL, as shown in Figure 12.
Enter ASA VPN Marketing as the text.
Click the ... button in order to choose the Font Color and Background Color.
Enable the Gradient option in order to create an attractive gradual color pattern.
In order to configure this address/toolbar, edit these customization options:Figure 14: Customization Editor: Toolbar Configuration
Note: By default the Toolbar is enabled. In this example, the remaining fields, such as Prompt Box Title, Browse button text, and Logout Prompt are renamed, as shown.Figure 15: Customized Bookmarks with Thumbnails
In order to add thumbnails next to the bookmarks, complete these steps:
Upload the required image to the /+CSCOU+/ directory.Figure 16: Upload the thumbnail image to associate with bookmarks
Associate the thumbnail image with ASA bookmarks.
Choose Portal > Bookmarks.
Click Add. Enter Applications for the Bookmark List Name.
Click Add. Enter ASA Marketing for the Bookmark Title.
Enter http://cisco.com/go/asa as the URL value, and choose Advanced Options.
Click Manage. Choose the previously uploaded /+CSCOU+/5550-1.gif thumbnail, and click OK.Figure 17: Associate thumbnails with bookmarks
Associate the bookmarks with the ASA group policy.
Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Group Policies, and edit the Marketing policy.
Choose Portal. Uncheck Inherit next to Bookmark List, and select Applications from the drop-down menu.Figure 18: Associate Bookmarks with Group Policy (Marketing)
In order to display a custom RSS Feed, edit these customization elements:Figure 20: Custom Panes: RSS feed Configuration
Note: RSS feeds for Cisco Security Advisory: http://newsroom.cisco.com/data/syndication/rss2/SecurityAdvisories_20.xml.Figure 21: Customized Intranet Web Page
In order to configure this custom intranet webpage, edit these customization elements:Figure 22: Customization Editor: Custom Panes Configuration
Note: URL for Cisco CCO page: http://cisco.com/en/US/netsol.Figure 23: Customized Application Tab Names
In order to configure application tab names, edit these customization elements:Figure 24: Customize Application Tab Names
Note: You selectively enable the applications and also re-arrange them with the Up and Down links.Figure 25: Customized Application Thumbnails
In order to add your favorite thumbnails next to the application names, such as the icons in the example, complete these steps:
From the portal page, right click the default thumbnail image to find its name and location.
For the Home tab, the thumbnail image location is /+CSCOU+/nv-home.gif.
For the Web Applications tab, the thumbnail location is /+CSCOU+/nv-web-access.gif.
Import the desired image as web content to ASA with the name captured in step one.
For example, if you want to associate the disney.gif with the Web Applications tab, import it as nv-web-access.gif.Figure 26: Import Thumbnails for Application Tabs
By default, Cisco provides help files for application usage. These pages can be replaced by your own custom HTML pages. For example, in Figure 27, you can add a custom picture to the help page.Figure 27: Customized Help Page
In order to customize the help files, complete these steps:
Choose Portal > Help Customization, and click Import.
Select the Language.
Select the .inc file. For example, if you want to edit the help page that corresponds to the Web Application access tab, select the web-access-hlp.inc file.
Choose your custom HTML file.Figure 28: Import Customized Help Files for Application Access
At this point, log onto the ASA at https://asa.cisco.com/sslclient. After successful authentication, you the customized web-portal appears.
This is the default login page:Figure 29: Default Login Page
This is a fully customized login page:Figure 30: Fully Customized Login Page
The new log-in page includes a customized logo, title, and image along with the login/password dialog box. The login page is fully customizable, which means you can build any HTML page and insert the login/password dialog box at the desired location.
Note: While the entire login page is customizable, the specific login/password dialog box that ASA loads to the end-user is not fully customizable.
With full customization, you can provide HTML for your own login screen, and then insert Cisco HTML code that calls functions on the security appliance that create the Login form and the Language Selector drop-down list.
The next sections of this document describe the modifications required in the HTML code and the tasks required to configure the security appliance to use the new code.
This HTML was obtained from Microsoft FrontPage editor. It includes the title, customized logo, an image and a footer.
Note: The images 5550.gif and asa.gif are saved in the directory login_files. The blank spaces are intentional, and are replaced with the login/password dialog box in later steps.
At this point, the page looks like Figure 31. Notice how it includes blank space to allow insertion of the dialog box in future steps.Figure 31: Initial Web Page
For all the images, replace the path with the keyword /+CSCOU+/, which is an internal directory in ASA. When you upload an image to ASA, the image is saved in the /+CSCOU+/ internal directory in the ASA file system. Later, when ASA loads this modified HTML, it loads the image files correctly.Figure 32: Modified HTML Code
Note: In the first link, login_files/5550.gif is replaced with /+CSCOU+/5550.gif.
The next step is to rename this login.html file to login.inc.
The .inc extension is required so that ASA recognizes this as a special type of file and includes the necessary java script to support the login/password dialog box.
This HTML code must be added at the location where you want to display the login/password dialog box.
<body onload="csco_ShowLoginForm('lform'); csco_ShowLanguageSelector('selector')" bgcolor="white"> <table> <tr><td colspan=3 height=20 align=right> <div id="selector" style="width: 300px"></div> </td></tr> <tr> <td align=middle valign=middle> <div id=lform> Loading... </div> </td> </tr> </table>
Note: The first two functions csco_ShowLoginForm(lform) and csco_ShowLanguageSelector(selector) are two java script functions whose definition is imported by ASA when it renders the .inc file. In this code, you simply invoke the function in order to display the login/password dialog box along with the language selector.
Note: The dialog-box is represented as a table element. This can be wrapped around other images or text or aligned as you see fit for your HTML page.
In this scenario, the login/password dialog box appears above the asa.gif image in the center. When you insert the code, the final HTML page looks like this:
The next step is to upload the final login.inc file and the image files as webcontents to the ASA. You need to make sure to select the bottom option in order to save the files in the /+CSCOU+/ directory.Figure 33: Import the Image Files as Webcontent to ASA
Finally, in the customization editor, select the Full Customization tab, and provide a link to the login.inc file that you uploaded. When the end-user connects from a connection profile which is associated with this customization, such as sslclient, the user sees the fully customized login page.Figure 34: Associate the login.inc to be the File for Full Customization
When you connect to the ASA through https://asa.cisco.com/sslclient, the fully customized login page appears.Figure 35: Final Fully Customized Login Page
As explained, all of the customizations are edited with the ASDM. However, you can still use these CLI commands in order to delete the customizations and other WebVPN content:
all Revert all webvpn related data customization Revert customization file plug-in Revert plug-in options translation-table Revert translation table url-list Revert a list of URLs for use with WebVPN webcontent Revert webcontent
In order to delete a customization, issue the revert webvpn customization Custom_Marketing CLI command.
In order to delete the logo file, issue the revert webvpn webcontent /+CSCOU+/marketing.gif command.
In order to delete the bookmarks, issue the revert webvpn url-list Marketing_URL_List command.
In order to delete all of the customizations, webcontents, plug-ins, and bookmarks, issue the revert webvpn all command.
Note: Since the WebVPN customizations are not saved in the running configuration, a typical write erase, reload sequence does not erase customizations or webcontents from the ASA. You must explicitly issue revert webvpn commands or manually delete the customizations from the ASDM.
Unlike the other CLI commands, the customizations are not saved in the running configuration. Instead, you need to explicitly export the customizations, and they are saved in XML format to the host computer.Figure 36: Export Customization to Backup or Replicate to Another ASA
In order to restore the customizations, import them with the XML file obtained in the previous step.Figure 37: Import a Customization from a Previously Exported XML file
Note: In addition to exporting/importing the customization, you also need to manually backup/restore the webcontent, which includes the image files, help files, and thumbnail images, explicitly. Otherwise, the customization are not fully functional.
The advanced customization features introduced in ASA version 8.0 enable the development of attractive web-portal pages. You can achieve virtualization by creating different customized web portals for different groups. In addition, the login-page can be fully customized to match the regular intranet web portals which provides a consistent user experience.
You might receive this error message after the WebVPN customization is enabled:
%ERROR: csco_config.lua:36: csco_config.lua:552: copying 'disk0:/csco_config/locale/ja/LC_MESSAGES/PortForwarder.po' to a temporary ramfs file failed %ERROR: csco_config.lua:36: csco_config.lua:552: copying 'disk0:/csco_config/locale/ja/LC_MESSAGES/webvpn.po' to a temporary ramfs file failed %ERROR: csco_config.lua:36: csco_config.lua:552: copying 'disk0:/csco_config/locale/fr/LC_MESSAGES/customization.po' to a temporary ramfs file failed.
In order to resolve this issue, run the revert webvpn all command, and reload ASA.
- Cisco 5500 Series Adaptive Security Appliance Support Page
- Customizing Clientless SSL VPN Pages
- ASA 8.0: How to Change the WebVPN Logo
- Technical Support & Documentation - Cisco Systems
|Updated: Feb 14, 2008||Document ID: 100586|