Monday, November 28, 2016

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:


 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.