Product Documentation

Customizing the User Portal

Aug 28, 2015

NetScaler Gateway installations that serve the portal to VPN users include an option to select a portal theme in order to create a customized look and feel for the portal pages. You can select from a supplied set of themes, or you can use a theme as a template to build a customized or branded portal. Using the configuration utility, you can modify a theme by adding new logos, background images, custom input box labels, and various other attributes of the CSS based portal design.  The built-in portal themes include content for five languages: English, French, Spanish, German, and Japanese. Different users are served in different languages, depending on the locales reported by their web browsers.

You have the option to create a custom end-user license agreement (EULA) that is presented to VPN users before they are allowed to sign in. The EULA feature supports locale-specific versions of a EULA, which are presented to users on the basis of their web browsers reported locales.

Both portal themes and EULA configurations can be bound independently at the VPN virtual server and VPN global levels. 

Applying a Portal Theme

By default, the VPN portal is configured to use the Caxton theme. The Caxton theme is named Default.

Figure 1: Caxton Theme
localized image

NetScaler Gateway includes two additional themes that can be applied to the portal: The Greenbubble and X1 themes. 

Figure 2: Greenbubble Theme
localized image
Figure 3: X1 Theme
localized image

You can apply any of the supplied themes directly to a VPN virtual server or as a global VPN binding. 

Binding a Portal Theme to a VPN Virtual Server

You can bind a portal theme on an existing virtual server or when creating a new virtual server.

Using the command line to bind a portal theme to an existing VPN virtual server

     At the command prompt enter: bind vpn vserver <name> -portaltheme <name>

Using the configuration utility to bind a portal theme to an existing VPN virtual server

  1. On the Configuration tab, navigate to NetScaler Gateway and click Virtual Servers. 
  2. Select a virtual server, and then click Edit.
  3. If a portal theme has not yet been bound to the virtual server, click Portal Theme under Advanced Settings in the details pane. Otherwise, the Portal Theme option is already expanded in the details pane. 
  4. In the details pane, under Portal Themes, click No Portal Theme to expand the Portal Theme binding window.
  5. Click on Click to select.
  6. In the Portal Themes window, click a theme name, and then click Select.
  7. Click Bind.
  8. Click Done.

If you are creating a new VPN Virtual Server, you can follow the steps above starting with step 3 while in the VPN Virtual Server edit pane in order to bind a Portal Theme.

Binding a Portal Theme to VPN Global

Using the command line to bind a portal theme to the VPN global scope

     At the command prompt enter: bind vpn global portaltheme <name>.

Using the configuration utility to bind a portal theme to the VPN global scope

  1. On the Configuration tab, navigate to NetScaler Gateway. 
  2. In the main details pane, click NetScaler Gateway Policy Manager.
  3. Click the '+' icon.
  4. Under the Bind Point pull-down menu, select Resources.
  5. Under the Connection Type pull-down menu, select Portal Theme.
  6. Click Continue.
  7. In the Bind Point screen, click Add Binding.
  8. Click on Click to select.
  9. In the Portal Themes window, click a theme name, and then click Select.
  10. Click Bind.
  11. Click Close.
  12. Click Done.

ヒント

When you’ve completed a set of changes, use the ‘save ns config’ command on the command line or click the save icon in the configuration utility to ensure your changes are saved to NetScaler configuration file.

Creating a new Portal Theme

To create a custom portal design, you use one of the supplied portal themes as a template. The system makes a copy of the selected template theme with a name that you specify.

Using a stock Portal Theme as a template for a custom Portal Theme

To create a new Portal Theme, you can use the configuration utility or the command line to create the new theme entity. However, the detailed customization controls are available only within the configuration utility. 

Using the command line to create a new portal theme 

     At the command prompt enter: add portaltheme <name> basetheme <name>

Using the configuration utility to create a new portal theme 

  1. On the Configuration tab, navigate to NetScaler Gateway and click Portal Themes.
  2. In the main details pane, click Add.
  3. Enter a name for the theme and select a template from the template pull-down menu, and then click OK.
  4. At this point, you are presented with the first-time view of the portal theme editing window. Click OK to exit.

You can proceed to customize the new portal theme with the first-time view. However, you should read the following Portal Theme Customization section about the interface, and the pop-up descriptions of the customizable portal attributes within the interface before continuing to edit a portal theme.

Once a new theme is created, you can bind it as described in Binding a Portal Theme to a VPN Virtual Server or Binding a Portal Theme to VPN Global. You can bind a new theme immediately after creation or after completing your customizations.

Portal Theme Customization

To customize a Portal Theme, use the Portal Theme interface in the configuration utility. To get the best results, you should understand the various elements of this interface before you use it.

About the Portal Theme Interface

To open the Portal Theme interface in the NetScaler configuration utility, on the Configuration tab, navigate to NetScaler Gateway and click Portal Themes. You can either create a new theme as described in Creating a New Portal Theme, or select an existing theme in the main details pane and click Edit.

The portal theme customization page has four primary component panes for modifying a portal design: the Portal Theme pane, the Look & Feel pane, the Advanced Settings pane, and the Language pane. 

Figure 4: Portal Theme interface
localized image

The Portal Theme pane at the top of the page reports what theme is loaded for editing and what template theme it is based on. The viewing option here allows you to view your customizations without accessing the VPN with a user connection. Note that using the viewing option requires binding the theme to a VPN virtual server and the binding remains in effect after the viewing window is closed.

With the Look & Feel pane in the center of the page, you configure a theme’s general properties, such as headers, background colors and images, font properties, and logos. When this pane is in edit mode, attribute legends are available for guidance on where the Look & Feel attributes are used on portal pages. 

The Advanced Settings pane contains the onscreen content controls for the individual portal pages. To load a page’s content for editing, click on any one of the pages listed. The page controls then open below the other center panes. A page remains collapsed in the Advanced Settings pane across Portal Theme edits as long as the page has not been modified. 

In the Language pane, you can select which of the languages will be loaded when a page is selected for edit from the Advanced Settings pane. The English language pages are loaded by default. 

Types of Customizable Page Attributes

When customizing a Portal Theme, you can modify a range of attributes in the Portal Theme interface. Along with the text and the supported languages that can be edited, all of the graphical elements of the portal’s layout can be tailored to suit your needs. Each of the page element types has parameters or recommendations to consider before modifying them.

Colors

The portal design specifies the colors for attributes such as page backgrounds, highlights, text for titles and body content, button controls, and hover responses. To customize a color attribute, you can enter a color value directly for a selected item, or you can use the supplied color picker to generate a color value. The interface supports entering valid HTML color values in RGBA format, HTML hexadecimal triplet format, and X11 color names. The color picker can be accessed for any applicable color attribute by clicking on the color box next to the attribute’s input field.

Figure 5: The Color Picker
localized image

Fonts

Along with font colors, you can modify font sizes for some page attributes. For each of these attributes, a pull-down menu offers the sizes available for each attribute, as determined by the portal’s design.

Images

For images, a pop-up description available for each control provides size recommendations and other requirements. The descriptions vary according to an attribute’s location on the page and its function. You can use PNG or JPEG image file formats. You can select an image to upload by selecting the check box beneath an item’s file name and then browsing to where the image resides on your local computer’s drive.

Labels

In the Advanced Settings section, you can select a specific portal page’s text to modify. Note that if you modify the default English text for a page, the text for other languages is not retranslated. The alternative language page content is provided as a convenience but requires manual updates for any customizations. To edit another language version for a page, first collapse the window, if it is open, by clicking the X icon for the open portal page. Then select the language in the Language pane and click OK. All of the portal pages opened from the Advanced Settings pane will then be in that language until you select a different one.

Important

In high availability or clustered deployments, Portal Themes are distributed across the shared configuration only when Portal Theme settings are made on the primary or configuration coordinator NetScaler entities respectively. 

A Note on Older Portal Customizations

For installations with manually modified custom portal designs created in NetScaler Gateway or Access Gateway releases earlier than 11.0, Citrix strongly recommends starting with a new portal theme in the customization interface. If you can't do that, you can apply a customization manually, but direct support for that is not provided.

When using a manually customized portal, you must set the customized portal as a global portal configuration. Doing so though means that an applied global portal configuration cannot be overridden with VPN virtual server level portal theme bindings. Attempting to create a VPN virtual server binding in this case with the configuration utility or the command line returns an error.

Also, in the case of high availability and cluster configurations, any manual customizations must be performed on every node in the deployment as the underlying files on the NetScaler file system are not distributed in the automatically shared configuration.

Manually creating a custom portal configuration 

To manually apply an older customized portal configuration after upgrading to NetScaler Gateway 11.0, you need to modify a copy of an existing portal page, put the customized portal files into the NetScaler file system, and select CUSTOM as the UITHEME parameter. 

Note that you can use WinSCP or any other secure copy program to transfer files to the NetScaler file system.

  1. Log on to the NetScaler Gateway command line.
  2. At the command prompt, type shell
  3. At the command prompt, type mkdir /var/ns_gui_custom; cd /netscaler; tar -cvzf /var/ns_gui_custom/customtheme.tar.gz ns_gui/*.
  4. At command prompt, type cd /var/netscaler/logon/themes/
    • If you want to customize the Greenbubble theme, enter cp -r Greenbubble Custom to make a copy of the Greenbubble theme.
    • If you want to customize the Default theme (Caxton), type cp -r Default Custom.
    • To customize the X1 theme, type cp -r X1 Custom.
  5. Make the needed changes to the copied files under /var/netscaler/logon/themes/Custom to customize the theme manually.
    • Make the necessary edits to css/base.css.
    • Copy any custom images to the /var/ns_gui_custom/ns_gui/vpn/media directory.
    • Make changes to labels in the files present in the resources/ directory. These files correspond to the portal supported locales.
    • If changes to HTML pages or javascript files are also needed, you can make the relevant to the files in /var/ns_gui_custom/ns_gui/.
  6. After all customization changes are complete, at the prompt enter: tar –cvzf /var/ns_gui_custom/customtheme.tar.gz /var/ns_gui_custom/ns_gui/*

Important

When copying a theme directory in the preceding steps, the copied folder name must be entered exactly as 'Custom' since directory names are case-sensitive within the NetScaler shell interface. If the directory name is not entered precisely, the folder is not recognized when the UITHEME setting is configured to CUSTOM.

Select the Customized Theme as a VPN Global Parameter

Once the manually customized portal configuration is complete and copied to the NetScaler file system, it needs to be applied to the NetScaler Gateway configuration. This is done by setting the UITHEME parameter to CUSTOM and can be completed with the command line or the configuration utility.

To use the command line, enter the following command to set the UITHEME parameter.

      set vpn parameter UITHEME CUSTOM

To set the UITHEME parameter using the configuration utility, use the following procedure. 

  1. On the Configuration tab, navigate to NetScaler Gateway > Global Settings.
  2. Click Change Global Settings.
  3. Click the Client Experience tab.
  4. Scroll to the bottom of the screen then select CUSTOM from the UI Theme pull-down menu.
  5. Click OK.
Your manually customized portal is now the portal design presented to VPN users.

Creating an End User License Agreement

The VPN portal system provides the option to apply an end-user license agreement (EULA) to a portal configuration. Once a EULA is bound to the NetScaler Gateway configuration, either at the VPN global scope or to a relevant VPN virtual server, VPN users must agree to the EULA as Terms and Conditions before they are allowed to authenticate into the VPN.

As with the portal themes, users are served a language specific EULA based on the locale reported by their web browser. In cases of a locale that doesn't match to any of the supported languages, the default language served is English. For each EULA, you can enter a custom message in each of the supported languages. Pre-translated content is not provided for EULA configurations as it is for the portal themes.  If a user's reported locale matches for a language where no EULA content is entered, the user is returned a blank page when they click on the "Terms & Conditions" link in on the VPN login page.

To create a EULA, you can use either of the controls in the configuration utility on the Configuration tab at NetScaler Gateway > Global Settings > EULA or NetScaler Gateway > Resources > EULA. The controls in the Global Settings pane are used to manage VPN global EULA bindings while the control on the Resources > EULA node is for general operations on EULA configurations. You can manage VPN virtual server EULA bindings by editing a VPN virtual server at NetScaler Gateway > Virtual Servers. Some commands are also available with the command line for managing EULA entities. However, the full EULA management controls are available only in the configuration utility.

Using the command line to create a new EULA entity 

     At the command prompt, type:  add vpn eula <name> 

Using the configuration utility to create a new EULA entity

  1. Navigate to NetScaler Gateway > Resources > EULA.
  2. Click Add to create a new entity.
  3. Enter a name for the entity.
  4. For each of the languages, paste in the content under the relevant tabs. You can use plain text or HTML tags to format the content, including a <br> tag to add line breaks.
  5. Click Create.
Once a EULA entity has been created, it can be globally bound to the VPN configuration, or can be bound to a VPN virtual server.
 

Using the command line to bind a EULA to VPN Global

     At the command prompt enter: bind vpn global eula <name>

Using the configuration utility to make a global EULA VPN binding

  1. On the Configuration tab, navigate to NetScaler Gateway > Global Settings.
  2. In the main details pane, click Configure an End User License Agreement.
  3. Click Add Binding.
  4. Click on Click to select.
  5. Select a EULA entity then click Select.
  6. Click Bind.
  7. Click Close.

Using the command line to bind a EULA to a VPN Virtual Server

     At the command prompt type: bind vpn vserver <name> eula <name>

Using the configuration utility to bind a EULA to a VPN Virtual Server

  1. At the Configuration tab browse to NetScaler Gateway > Virtual Servers.
  2. In the main details pane, select a VPN virtual server and click Edit.
  3. From the Advanced Settings pane on the right side of the page, click EULA.
  4. In the newly-added EULA pane, click No EULA.
  5. Click on Click to select.
  6. Select a EULA entity and click Select.
  7. Click Bind.
  8. Click Done.