Adding Text, Links and Other Elements to the NetScaler Logon Page - Part 2

As we discussed in Part 1 of this post, there are three categories of NetScaler customizations:

1) Customizations that do not require any rewrite policies/actions (“policies”) or source code modifications (“modifications”),

2) Customizations that can be accomplished using either policies or modification, and

3) Customizations that will most probably need modification of the source code.

In Part 1, we focused on the Default, Green Bubble, and X1 (the "original") themes. In part 2, we will discuss the newest theme - Receiver for Web UI (RfWebUI), which uses a completely new mechanism.

While the logon page looks like the X1 theme:

... if you will be using the RfWebUI theme, you can forget pretty much everything you've learned about customizing the NetScaler logon page.  

Let's begin with the location of the logon page. When using the original themes, the logon page (index.html) was served from the  /netscaler/ns_gui/vpn/ directory. With the RfWebUI theme, the file is now served from /var/netscaler/logon/LogonPoint/. The good news is that since the page is now in the /var partition, any modifications to the page (or copies of the logon page) are automatically persisted across a reboot. No longer do you need to add lines to rc.netscaler to copy modified files into the flash partition.

The next major change is how you modify text. The portal wizard allows you to easily make changes to commonly updated text. Let's say you wanted to change the labels on the logon screen. After clicking OK at the bottom of the wizard, you will then be prompted for the language you wish to use:

After clicking OK, you will see the pages you can modify on the right-hand side of the page.   

Click Login Page. You are presented with the default labels for the page:

Let's modify them as follows:

Click Ok.

Finally, click Done. Now, let's refresh the page (you may need to clear your cache).

If you've had experience customizing the original NetScaler themes, at this point you are probably thinking "Tell me something that I don't already know ... this is no different than modifying any of the other themes"! Not quite ... The portal wizard functions differently depending on which theme has been chosen. For the original themes, the portal wizard would modify the values in the appropriate XML file in the resources directory (e.g. /var/netscaler/logon/themes/<theme>/resources/en.xml). The keys affected are located under the Partition ID of Logon. Now, what if you wished to modify the text of the logon button above, which you can't do from the portal wizard? No problem. In the same file, as few lines down, we find:

<Property id="Log_On" property="value">Log On</Property>

Simply change it to:

<Property id="Log_On" property="value">Click to log on</Property>

... and then save the file.

Try that with a theme based on RfWebUI and you will find that it doesn't work. In fact, if you look at the en.xml file in the resources directory of a theme based on RfWebUI, you will notice that the portal wizard did *not* modify ANY of the keys in that file. What gives??

For RfWebUI-based themes, those text changes are written to /var/netscaler/logon/themes/<theme>/strings.<language code>.json:

The portal wizard writes all the values on a single line. I would suggest placing each override on a separate line for readability and maintainability. Also note that this "key":"value" format differs from the XML format of the other themes. 

In order to change other text elements on the page, you will need to get the key to be placed in the override file. The keys may be found in the file /var/netscaler/logon/LogonPoint/receiver/js/localization/<language code>/ctxs.strings.js. The key for the logon button is nsg_LogOnbutton. Let's add an override for it in the above file:

Then save the file, and refresh the page. In addition to clearing the cache on your PC, it may take 2-3 minutes for the cache to be cleared on the NetScaler.

Now, let's try to add our own custom text fields as we did with the X1 theme in part 1.

Here we come to another major difference. In the original themes, we would:

- Add a <div> with a unique id (either via a rewrite action/policy or a modified gateway_login_form_view.js file),

- Add a string with the <div>'s id to the XML file in the resources directory, and finally 

- Add a CSS selector with the <div>'s id to the custom.css file in the selected theme.

Note that everything is keyed off the id of the <div>.

With RfWebUI-based themes, text is keyed off of class names, and the class name must begin with _ctxstxt_. So, to add the "authorized users only" warning (see Part 1), we make a copy of the index.html file (let's call it custom.html), and add our custom <div>:

We then add an entry with the text into strings.en.json:

We also need to add style information, but instead of adding it to custom.css, for RfWebUI-based themes, it must go into theme.css. Here you can either use the <div>'s id (if specified), or the class name, which is required (include the _ctxstxt_ prefix).

We can test by browsing to our custom.html file.

Let's not forget our footer ... add another custom <div>:

Then add the text:

... and then the CSS:

Browsing to our custom page:

Our final step is to create a responder policy and bind it to our AG vServer. This will automatically invoke our custom page when we browse to the AG vServer FQDN:

> add responder action "Logon Page Redirect Action" redirect "\"custom.html\"" -responseStatusCode 302
> add responder policy "Logon Page Redirect Policy" "HTTP.REQ.URL.PATH_AND_QUERY.CONTAINS(\"LogonPoint/index.html\")" "Logon Page Redirect Action"
> bind vpn vserver "AG vServer" -policy "Logon Page Redirect Policy" -priority 100 -gotoPriorityExpression END -type REQUEST
> save config

To remove the customizations, simply unbind the responder policy.

Here’s a handy cheat-sheet summarizing all of the above:

	Original Themes (Default, Green Bubble, X1)	Receiver for Web UI (RfWebUI) Theme
Logon page directory	/netscaler/ns_gui/vpn/	/var/netscaler/logon/LogonPoint/
Updates to text strings	/var/netscaler/logon/themes/<theme>/       resources/<language code>.xml	/var/netscaler/logon/themes/       <theme>/strings/<language code>.json
String format	<String id=”key”>Value</String>    OR <Property id="key"       property="property">Value</Property>	“key” : “value”
Custom text based on	<div> ID	class name (existing keys are in /var/netscaler/    logon/LogonPoint/receiver/js/localization/    <language code>/ctxs.strings.js
CSS file	custom.css	theme.css

Thanks to the NetScaler development team for their help, and especially Bidyut H.

Adding Text, Links and Other Elements to the NetScaler Logon Page - Part 1

There have been a number of posts, discussions, and KB articles on adding text and links to the NetScaler logon page, such as:

• How to Add Links and Verbiage

• How to Customize Footer of NetScaler Gateway Login Page

 In this 2-part post, I will divide such customizations of the login page into three categories:

1) Customizations that do not require any rewrite policies/actions (which we’ll call “policies” for brevity) or source code modifications (“modifications”),

2) Customizations that can be accomplished using either policies or modification, and

3) Customizations that will most probably need modification of the source code (usually gateway_login_view.js and/or gateway_login_form_view.js).

In part 1, we will focus on the Default, Green Bubble, and X1 NetScaler 11 themes. In part 2, we will discuss the newest Receiver for Web UI (RfWebUI) theme, which uses a completely new mechanism, which is more similar to modifications made for StoreFront.

First off, regardless of whether modifications are made via policies or modifications, the policies or modifications should be minimized to whatever extent possible. There should never be style information or text strings in the policy or modification. Style information should be confined to the custom.css file, and strings should be placed into the appropriate XML file(s) in the resources directory of the theme, especially if you need localization (multi-language support).

So, for example, instead of:

<div style=’font-family: arial,helvetica,sans-serif;color:white;font-weight:bold;’>WARNING: Use of this system is limited to authorized users. Activities on this system are monitored, and subject to audit.</div>

 ... the policy or modification itself should only contain:

<div id=’unauthorizedUse’ />

Then, add the following to custom.css:

#unauthorizedUse {
      font-family: arial,helvetica,sans-serif;
      color:white;
      font-weight:bold;
}

... and the following to en.xml (with appropriate entries in other language files):

<String id="unauthorizedUse"> WARNING: Use of this system is limited to authorized users. Activities on this system are monitored, and subject to audit.</String>
Let's take it a step further. As mentioned above, the first category of customizations do not require any policies or modifications at all. Included in this category would be the addition of a few lines of footer text (with or without links), such as the customization above. For example, I can create the following:

 ... by adding the following to the bottom of custom.css:

#logonbelt-bottomshadow,
#logonbelt-bottomshadow a {
   text-align: center;
   color: #FFFFFF;
   font-size:12pt;
}   
#logonbelt-bottomshadow a {
   font-weight: bold;
   text-decoration: underline;
} 

... and adding the following text to en.xml (all on one line):

<String id="logonbelt-bottomshadow">WARNING: Use of this system is limited to authorized users. This system contains confidential and proprietary information. Any unauthorized trespass into or use of this system is prohibited. Any such unauthorized trespass or use may be referred to law enforcement agencies for criminal prosecution and may subject you to civil penalties. Activities on this system are monitored and recorded, and subject to audit.&lt;br&gt;Please refer to the firm's &lt;a href='#'&gt;Acceptable Use Policy&lt;/a&gt; for additional details.</String>

The only item you need to be aware of, is that all HTML codes must be converted to their HTML-encoded equivalents. For example:

<a>	&lt;a&gt;
</a>	&lt;/a&gt;
<b>	&lt;b&gt;
<br>	&lt;br&gt;

Note that I am not using any policies or modifications for the above. I was able to do this by leveraging the built-in <div> called logonbelt-bottomshadow. There is also a <div> called logonbelt-topshadow that one can use to add text and links above the logon box.

So, when would a policy or modification be called for? When you need to add extra elements to the page. If, for instance, I wanted to add a footer to the previous example:

... I could inject a <div> called footer (following our "Keep It Small" rule, the added code would simply be <div id='footer' />), and then add <String id="footer">myCUGC.org - All Rights Reserved.</String> to en.xml, and the following to custom.css:

#footer {
   position: absolute;
   bottom: 5px;
   height: 30px;
   font-size: 12px;
   color: white;
   font-weight: bold;
   text-align: center;
   width: 100%;
   background-color: black;
   padding-top: 5px;
}

Finally, there will be times where the number of modifications, or their complexity make using policies impractical. In those cases, it makes more sense to use modifications. Consider the following example:

First, there are all the added elements (color bars and the extra text on the bottom of the screen). Then there are the additional buttons which will need to be backed by JavaScript calls. While it is certainly possible to use policies for all the elements, it would be much simpler to use modifications in a case like this.

When you use modifications, do not modify the original .js file. Instead, make a copy of the original, and make your modifications to the copy. You can then use a rewrite action and policy to swap the modified file for the original.  For example:

add rewrite action act_login_form_replace replace_all "HTTP.RES.BODY(120000)" q{"custom_login_form_view.js"} -search q{text("gateway_login_form_view.js")}

add rewrite policy pol_login_form_replace "HTTP.REQ.URL.EQ(\"/vpn/index.html\")" act_login_form_replace

bind vpn vserver "AG vServer" -policy pol_login_form_replace -priority 200 -gotoPriorityExpression NEXT -type RESPONSE 
You also need to make sure your modified file survives a reboot, so you need to also copy your file into /var/vpn/vpn/js.

Configuring Duo Integration With NetScaler

The purpose of this blog post is to explain the two modes of Duo integration with the NetScaler, to point out the pros and cons of each method, and to explain the different configurations needed for NetScaler and StoreFront when using each mode. I will not go into the configuration of the Duo proxy itself, as that is covered quite well (except where noted – see below) in the online Duo documentation (links below).

Having said that, there is one extremely important Duo configuration issue that I must mention. Do NOT use Notepad when editing the authproxy.cfg file! Use either Notepad++ or Wordpad. The impetus in creating this document was caused by wasting a good portion of the day bouncing back and forth between Citrix Tech Support and Duo Tech Support, when the only thing wrong was that Notepad inserted extra line breaks (one right in the middle of the RADIUS secret key!) in the config file.

Mode 1 – ad_client
In this mode, Duo performs ALL authentication. It communicates with Active Directory to validate the AD password, and, once validated, sends the user the push, call, or SMS. Duo configuration for this mode is explained here: https://duo.com/docs/citrix_netscaler.

In this configuration, the NetScaler needs only 2 RADIUS profiles and policies – one for Web access, and the other for Receiver access. Both are defined as PRIMARY - there are no secondary profiles/policies. The above link explains the profiles and policies in detail. Take note that the port for the Receiver authentication server should be different (e.g. 18120) than the standard RADIUS port (1812) used for the Web authentication server, and must match the port defined in the Duo config file.

One important point omitted by the Duo documentation is the configuration of StoreFront. When using ad_client mode, you must ensure that the Logon Type in the StoreFront Gateway Appliance Authentication Settings is set to Domain.

PROS

Users see only a single password field for both web and Receiver, so you do not need to hide the second password field (for the web), and there is much less confusion when using Receiver.

You also only need to define 2 RADIUS policies, making configuration slightly easier.

CONS
Since authentication is not being handled by the NetScaler, users cannot change passwords using this method.


Mode 2 – duo_only_client (referred to in Duo documentation as the Alternate Configuration)

In this mode, the NetScaler performs Active Directory authentication, with Duo handling only the 2nd factor (RADIUS) authentication – hence the name duo_only_client. This mode is a bit more complicated to set up on the NetScaler. While the Duo documentation of this mode (https://duo.com/docs/citrix_netscaler-alt) explains the Duo portion of the setup well, do NOT use this document to set up your NetScaler policies. This document describes setting up two SECONDARY RADIUS policies, which will NOT work if you are using Receiver. Instead, refer to the following Duo article: https://duo.com/docs/citrix_netscaler-faq (see the section: Why might mobile Receiver clients have issues authenticating with Duo?). This will refer you to the following Citrix KB article: http://support.citrix.com/article/CTX125364, which explains how and why you need to set up 2 LDAP and 2 RADIUS policies and profiles. Note that the session profile for the Receiver must have the Credential Index set to SECONDARY.

Again, the Duo documentation omits the setup of StoreFront. When using duo_only_client mode, you must ensure that the Logon Type in the StoreFront Gateway Appliance Authentication Settings is set to Domain and security token.

If you leave the Logon Type at the default Domain setting, logon via the web will work (since this setting is not used by the NetScaler), but Receiver (which does use this setting) will not work.

PROS

Since the NetScaler is performing Active Directory authentication, users may change their password (as long as the LDAP authentication server is using either TLS or SSL – not PLAINTEXT).

CONS

Using this mode, users will see two password prompts for web and Receiver:

While the unused second password field may be hidden for the web (see the Duo alternate configuration link above), this requires modification of the NetScaler source files - unsupported by Citrix, and, if not done carefully, may corrupt your NetScaler configuration.  The second password field for the Receiver may NOT be hidden, and the user must enter a valid Duo factor name (push – recommended, or phone) into that field. This can get quite confusing for users. The NetScaler configuration for this mode is also a bit more complicated.

Synergy 2016 CTP Swag

It's hard to believe that Citrix Synergy 2016 is now behind us! It seems like it was only a few weeks ago that I was submitting my abstracts. It was an amazing event, and it seemed like there were quite a bit more new/updated product announcements than usual.

 NetScaler MAS

One of the most exciting announcements for me was NetScaler MAS (Management and Analytics System). If you haven't yet heard about NetScaler MAS, check out this excerpt from the Day Two General Session by CTO Abishek Chauhan.


HDX Ready Raspberry Pi

Another announcement that's shaking up the thin client world was the introduction of the HDX Ready Raspberry Pi. At $70 (plus the cost of a keyboard, mouse, and monitor), you don't need staff to maintain these devices. Should one fail, simply dump it, and replace it with another! Look at how small the device is - it's barely longer than a room key card:  

Networking

As impressive as the announcements were, I enjoy Synergy mostly for the networking. As a CTP, I get to spend two precious days prior to Synergy networking with 50 of the most Citrix-savvy individuals, as well as Citrix product managers, discussing technologies and product updates. Check out this link for more information on the Citrix Technology Professionals program. Recognizing that there are other individuals who may wish to contribute to the community, this year at Synergy, Citrix launched another tier of professionals - Citrix Technology Advocates.

Match.Geek

I also enjoyed participation in the Match.Geek program at Synergy, during which I was able to connect with 4-6 attendees in 30-minute discussions (much along the lines of technology speed-dating!) . Although my areas of expertise are gateway products (NetScaler, StoreFront, Web Interface) and development, any and all questions were still welcomed.


Breakout Session

I was also honored to present a breakout session this year on NetScaler Debugging and Troubleshooting Best Practices. If you missed it in person, have no fear. You can still view the event on SynergyTV, or via YouTube. The SynergyTV recordings this year have swappable picture-in-picture technology, which you can control. I hope you filled out your survey if you were at the session, as I take all feedback to heart (yep, even the constructive criticism). As promised during the session, here is some swag from Synergy - CTP style - a ShareFile link containing my full session presentation (including speaker notes), as well as the NSBackup utility (for backing up critical NetScaler files) discussed during the session:

SYN317 - NetScaler Debugging and Troubleshooting Best Practices - Full Presentation and NSBackup Utility. (please refer to the package contents document contained within).

Welcome Citrix Technology Professional (CTP) Class of 2016!

Wow! It's hard to believe that a whole year has passed since I was honored by being elected to the CTP Class of 2015. I am also thrilled to have been re-accepted to the program for 2016. It’s been a fantastic year!

What is the CTP Program?

For those who may not be aware, the CTP Program is a group of only 50 individuals worldwide who have invested a significant amount of time and resources to become experts in Citrix products and solutions. The wealth of knowledge they have developed - and more importantly, openly shared - has proven invaluable to the Citrix technology community.  They have consistently demonstrated their real-world knowledge by:

• Sharing insights (blogging) on web sites and contributing to online discussions (e.g. Citrix forums, Citrix Developer Network)
• Sharing ideas and code with the Citrix developer community
• Creating or fostering communities of Citrix users (e.g. CUGC)
• Publishing technical documentation, articles, or books
• Offering technical expertise in the field
• Speaking at IT conferences

CTP members engage with Citrix product teams via in-person meetings and private webinars for detailed discussions on current technologies and product roadmaps. They help shape the future of Citrix technologies by providing valuable input on business needs and feedback on product strategy.

We are proud to welcome the CTP Class of 2016 to the group:

By their continued contributions to the Citrix community, each of the above has proven that they are deserving of the CTP designation. 

Congratulations to the new awardees, as well as to all the CTP members.

You can see the full list of CTP awardees here: CTP Awardees.

CTP accomplishments are reviewed annually, and are evaluated based on recent community contributions. If you have what it takes, I encourage you to apply for the program. You can review benefits and eligibility here: 
Citrix Technology Professionals Program.

Thanks

I would like to thank the following, whose invaluable support has enabled me to continue giving back to the community: 

• My family
• The management team and my colleagues at IPM
• Current and previous CTP members
• Perrine Crampton and Brad Nunn, CTP Program Managers
• Citrix 

How to Change the Page Title in Citrix Receiver 3.x

During my consulting engagements, I'm always coming across little tips and tricks, which might benefit others in similar situations. Over the course of the coming months, as time allows, I hope to share some of those tips with the community. Feedback is always welcomed.

My first tip is rather a simple one, yet was something that was quite a bit frustrating. In earlier versions of StoreFront, you could change the page title by adding the following code snippet into the JavaScript override file (custom.script.js in the contrib directory):

$(document).ready(function() {
 document.title = "My page title";
});

For StoreFront 3.x, the above script would be placed in the file script.js in the custom directory. If you attempt to do the same thing in StoreFront 3.x, however, you will see your updated title for a fraction of a second, and then it gets replaced by the default text of Citrix Receiver. Obviously, something was being called after script.js.

My next step was to check ctxs.wrstrings.js in <store>web\scripts\<lang code>. This is the template file that you would use to override text string within StoreFront. For example, I would frequently change the StoreFront dropdown from:

to:

To do so, I simply copy the following line from <store>web\scripts\en\ctxs.wrstrings.js:

ActivateReceiver: "Activate ...",

... and copy it to <store>web\custom\strings.en.js, changing the line to read:

ActivateReceiver: "Configure Receiver ...",

Before I continue, I must stress that you do not want to change the template file itself for two reasons. First of all, a StoreFront upgrade would wipe out your changes, and secondly, changes to the template file would not propagate to other servers in the StoreFront server group.
I was hoping to find a line that could be overridden for the page title, but unfortunately, could not find one that fit. Not ready to give up, I searched through the Receiver Customization Extensions and APIs to see if there was something that could help. I came across the afterDisplayHomeScreen() function. So, I added the following to the script.js file in the custom directory:

CTXS.Extensions.afterDisplayHomeScreen = function () {
    document.title = 'My page title';
}

Voila! It worked... sort of. While it did work for the StoreFront applications screen, the logon screen still reverted back to Citrix Receiver. At this point, I reached out to one of my StoreFront gurus, Feng Huang, who graciously provided me with the correct answer. While I was correct in assuming that I would need to add an override string, it wasn't a string that already existed in ctxs.wrstrings.js. I simply needed to add the following into strings.en.js:

AppStore: "My page title",

Problem solved! (and the afterDisplayHomeScreen() function was no longer needed)