Gateway

Customizing the User Portal

Citrix Gateway installations that serve the portal to VPN users include an option to select a portal theme 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 based on their web browsers reported locales.

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

Important: Citrix does not support customization that requires code modifications and does not offer support to resolve issues beyond reverting to a default theme.

Applying a Portal Theme

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

Caxton Theme

Caxton theme

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

Greenbubble Theme

Greenbubble theme

X1 Theme

X1 theme

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, type;

bind vpn vserver <name> -portaltheme <name>
<!--NeedCopy-->

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

  1. On the Configuration tab, Navigate to Citrix 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 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 VPN Virtual Server, you can follow the steps above starting with step 3 while in the VPN Virtual Server edit pane 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, type;

bind vpn global portaltheme <name>
<!--NeedCopy-->

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

  1. On the Configuration tab, Navigate to Citrix Gateway.
  2. In the main details pane, click Citrix Gateway Policy Manager.
  3. Click the ‘+’ icon.
  4. In the Bind Point list, select Resources.
  5. In the Connection Type list, select Portal Theme.
  6. Click Continue.
  7. In the Bind Point screen, click Add Binding.
  8. Click 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.

Tip: 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 Citrix ADC configuration file.

Creating a 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 Portal Theme, you can use the configuration utility or the command line to create the theme entity. However, the detailed customization controls are available only within the configuration utility.

Using the command line to create a portal theme

At the command prompt, type;

add portaltheme <name> basetheme <name>
<!--NeedCopy-->

Using the configuration utility to create a portal theme

  1. On the Configuration tab, Navigate to Citrix 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 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 Citrix Gateway configuration utility, on the Configuration tab, Navigate to Citrix Gateway and click Portal Themes. You can either create a theme as described in Creating a 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.

Portal Theme interface

Portal Theme interface

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

The Color Picker

Color picker

Fonts

Along with font colors, you can modify font sizes for some page attributes. For each of these attributes, a list 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. 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 Citrix ADC entities respectively.

A Note on Older Portal Customizations

For installations with manually modified custom portal design created in Citrix 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 Citrix ADC 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 Citrix Gateway 11.0, you need to modify a copy of an existing portal page, put the customized portal files into the Citrix ADC file system, and select CUSTOM as the UITHEME parameter.

You can use WinSCP or any other secure copy program to transfer files to the Citrix ADC file system.

  1. Log on to the Citrix 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 Citrix ADC 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 Citrix ADC file system, it needs to be applied to the Citrix 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
<!--NeedCopy-->

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

  1. On the Configuration tab, Navigate to Citrix 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 list.
  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 Citrix 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 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 Citrix Gateway > Global Settings > EULA or Citrix 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 Citrix 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 EULA entity

At the command prompt, type;

add vpn eula <name>
<!--NeedCopy-->

Using the configuration utility to create a EULA entity

  1. Navigate to Citrix Gateway > Resources > EULA.
  2. Click Add to create an 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, type;

bind vpn global eula <name>
<!--NeedCopy-->

Using the configuration utility to make a global EULA VPN binding

  1. On the Configuration tab, Navigate to Citrix Gateway > Global Settings.
  2. In the main details pane, click Configure an End User License Agreement.
  3. Click Add Binding.
  4. Click 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>
<!--NeedCopy-->

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

  1. At the Configuration tab browse to Citrix 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 Click to select.
  6. Select a EULA entity and click Select.
  7. Click Bind.
  8. Click Done.