Guest

Cisco ASA 5500-X Series Next-Generation Firewalls

ASA 8.0 SSLVPN (WebVPN): Advanced Portal Customization

Document ID: 100586

Updated: Feb 14, 2008

   Print

Introduction

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.

Prerequisites

Requirements

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.

Components Used

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.

Configuration Requirements

You must configure the ASA in preparation for the customization steps presented in this document.

Complete these steps:

  1. 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)

    asa5500_portal_customization1.gif

  2. 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)

    asa5500_portal_customization2.gif

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

    asa5500_portal_customization3.gif

    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.

  4. Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Portal > Customization, and add these two customization objects:

    • Custom_Login

    • Custom_Marketing

    Figure 4: Create a New Customization (Custom_Login)

    asa5500_portal_customization4.gif

    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.

Conventions

Refer to Cisco Technical Tips Conventions for more information on document conventions.

Customization Overview

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.

Better Look and Feel

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.

Virtualization

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.

Supported Pages

ASA supports two different types of WebVPN pages that are customizable.

Login Page

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

asa5500_portal_customization5.gif

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:

  1. Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Connection Profiles.

  2. Edit the sslclient connection profile, and associate the Custom_Login customization with this connection profile.

Figure 6: Associate Customization (Custom_Login) with Connection Profile (sslclient)

asa5500_portal_customization6.gif

Portal Page

After the user is authenticated, this default1 web-portal page appears:

Figure 7: Default Portal Page

asa5500_portal_customization7.gif

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:

  1. Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Group Policies.

  2. Edit the Marketing group policy, and associate the Custom_Marketing customization with this group policy.

Figure 8: Associate Customization (Custom_Marketing) with Group Policy (Marketing)

asa5500_portal_customization8.gif

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.

Customize Web Portal

This is a sample customized web portal:

Figure 9: Customized Web Portal Page

asa5500_portal_customization9.gif

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.

Title Panel

Figure 10: Title Panel

asa5500_portal_customization10.gif

In order to configure the title panel, these customization options are enabled:

Figure 11: Customization Editor: Title Panel Configuration

asa5500_portal_customization11.gif

Logo URL

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

asa5500_portal_customization12.gif

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

  2. Enter the /+CSCOU+/marketing.gif logo URL, as shown in Figure 12.

  3. Enter ASA VPN Marketing as the text.

  4. Click the ... button in order to choose the Font Color and Background Color.

  5. Enable the Gradient option in order to create an attractive gradual color pattern.

Toolbar

Figure 13: Customized Toolbar

asa5500_portal_customization13.gif

In order to configure this address/toolbar, edit these customization options:

Figure 14: Customization Editor: Toolbar Configuration

asa5500_portal_customization14.gif

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.

Web-Bookmarks with Thumbnails

Figure 15: Customized Bookmarks with Thumbnails

asa5500_portal_customization15.gif

In order to add thumbnails next to the bookmarks, complete these steps:

  1. Upload the required image to the /+CSCOU+/ directory.

    Figure 16: Upload the thumbnail image to associate with bookmarks

    asa5500_portal_customization16.gif

  2. Associate the thumbnail image with ASA bookmarks.

    1. Choose Portal > Bookmarks.

    2. Click Add. Enter Applications for the Bookmark List Name.

    3. Click Add. Enter ASA Marketing for the Bookmark Title.

    4. Enter http://cisco.com/go/asa as the URL value, and choose Advanced Options.

    5. Click Manage. Choose the previously uploaded /+CSCOU+/5550-1.gif thumbnail, and click OK.

      Figure 17: Associate thumbnails with bookmarks

      asa5500_portal_customization17.gif

  3. Associate the bookmarks with the ASA group policy.

    1. Choose Configuration > Remote Access VPN > Clientless SSL VPN Access > Group Policies, and edit the Marketing policy.

    2. Choose Portal. Uncheck Inherit next to Bookmark List, and select Applications from the drop-down menu.

      Figure 18: Associate Bookmarks with Group Policy (Marketing)

      asa5500_portal_customization18.gif

Custom Panes: RSS Feed

Figure 19: Customized RSS Feed

asa5500_portal_customization19.gif

In order to display a custom RSS Feed, edit these customization elements:

Figure 20: Custom Panes: RSS feed Configuration

asa5500_portal_customization20.gif

Note: RSS feeds for Cisco Security Advisory: http://newsroom.cisco.com/data/syndication/rss2/SecurityAdvisories_20.xml.

Custom Panes: Custom Intranet Page

Figure 21: Customized Intranet Web Page

asa5500_portal_customization21.gif

In order to configure this custom intranet webpage, edit these customization elements:

Figure 22: Customization Editor: Custom Panes Configuration

asa5500_portal_customization22.gif

Note: URL for Cisco CCO page: http://cisco.com/en/US/netsol.

Customized Application Tab Names

Figure 23: Customized Application Tab Names

asa5500_portal_customization23.gif

In order to configure application tab names, edit these customization elements:

Figure 24: Customize Application Tab Names

asa5500_portal_customization24.gif

Note: You selectively enable the applications and also re-arrange them with the Up and Down links.

Customized Application Thumbnails

Figure 25: Customized Application Thumbnails

asa5500_portal_customization25.gif

In order to add your favorite thumbnails next to the application names, such as the icons in the example, complete these steps:

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

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

    asa5500_portal_customization26.gif

Customized Help Pages for Applications

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

asa5500_portal_customization27.gif

In order to customize the help files, complete these steps:

  1. Choose Portal > Help Customization, and click Import.

  2. Select the Language.

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

  4. Choose your custom HTML file.

    Figure 28: Import Customized Help Files for Application Access

    asa5500_portal_customization28.gif

Test the Customization

At this point, log onto the ASA at https://asa.cisco.com/sslclient. After successful authentication, you the customized web-portal appears.

Customize Login Page

This is the default login page:

Figure 29: Default Login Page

asa5500_portal_customization5.gif

This is a fully customized login page:

Figure 30: Fully Customized Login Page

asa5500_portal_customization30.gif

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.

Start with Your Own HTML File

This HTML was obtained from Microsoft FrontPage editor. It includes the title, customized logo, an image and a footer.

asa5500_portal_customization38.gif

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

asa5500_portal_customization31.gif

Modify the Links to Image Location

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

asa5500_portal_customization32.gif

Note: In the first link, login_files/5550.gif is replaced with /+CSCOU+/5550.gif.

Rename the HTML File

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.

Add Code to the login.inc File

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:

asa5500_portal_customization39.gif

Upload the login.inc and the Image Files as Web Content to ASA

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

asa5500_portal_customization33.gif

Select the login.inc to be the File for Full Customization

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

asa5500_portal_customization34.gif

Test the 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

asa5500_portal_customization35.gif

CLI Support

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:

revert webvpn:

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

For example:

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

Backup the Customizations

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

asa5500_portal_customization36.gif

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

asa5500_portal_customization37.gif

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.

Conclusion

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.

Troubleshoot

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.

Related Information

Updated: Feb 14, 2008
Document ID: 100586