Jul 27 2007
Now that you understand how NFuse works and how it can be configured, we can take a look at the web pages that NFuse uses. When you install NFuse 1.7 on your web server, the default NFuse web site is installed in the \Citrix\NFuse17 folder under the web root. The installation program asks if you want to change the default page to the NFuse page. If you choose to do this, then you can access NFuse directly via your web server's address. If not, then you can access NFuse via http://yourwebserver/Citrix/NFuse17. Similar to most web pages, the default NFuse web pages work no matter how you access the web server, whether by NetBIOS name, DNS name, or IP address.
In order to learn how to work with these NFuse web pages, we'll look at the following items:
- Setting web page options
- Where is the Citrix Web Site Wizard?
- Understanding the default NFuse web site.
- Modifying the default NFuse web site.
- Creating NFuse web sites from scratch.
Configuring Default Web Page Options
The same NFuse.conf file and administrative web pages that you used earlier to configure the settings of the NFuse Java Objects are also used to configure the behavior of the NFuse web pages. You can probably customize the pages as much as you need without ever having to edit any web page source code.
Let's take a look at the specific lines in the NFuse.conf file that can be used to customize the look and feel of the web pages. These lines can be split into two categories:
- Fields that specify the login and authentication options.
- Fields that specify which application options the users see.
Again, remember that if you make any changes to any of these fields, you will have to stop and start your web server service.
Specifying Login and Authentication Options
There are five fields in particular that affect the login options presented to users via NFuse 1.7 web pages. To prevent yourself from having to flip backwards through this book, let's list those specific lines again here:
#ForceLoginDomain=[Place your domain here]
#NDSTreeName=[For NDS logins place NDS Tree name here,
and also change LoginType to NDS]
#SearchContextList=[NDS context1, NDS context2, ...]
(NFuse Admin Web Pages | Authentication | Methods)
This specifies the manner of user authentication that your NFuse web server will support. There are several options, and you can support multiple options by adding multiple entries to the line, separated by commas.
A value of "Explicit" means that users must log in to the NFuse portal with their own usernames and passwords.
A value of "Guest" will cause a radio button to appear on the login page allowing users to choose "guest" access (or the standard "explicit" access). If guest access is chosen, web visitors do not have to enter any user credentials. When they click the "login" button, they are presented with a page containing links to all anonymous applications in the server farm. If "Guest" is listed without the "Explicit" option on this line, no login fields are displayed. Users that connect to the website are forwarded directly to the application list page which shows anonymous applications. In this case the logout feature is also disabled.
A value of "Integrated" enables pass-through authentication. When users access NFuse, the credentials that they used to logon to their local workstations are used, and the user is forward directly to their list of applications. This only works if users' client devices are Windows 2000 or Windows XP.
Usually, this option is used in combination with the "Explicit" option. Then, if pass-through authentication works, users have direct access to their applications. If pass-through authentication does not work, they are still given a chance to login manually.
You can also specify a value of "Certificate" on this line. This is the setting that you need to use if your users authenticate with smart cards. See Chapter 15 for the details of smart card authentication.
(NFuse Admin Web Pages | Authentication | Explicitly login | Use NT authentication | with force login domain)
If all of your users will be logging in from the same Windows domain, you can add the domain name to this field after removing the leading "#." When you do this, the domain box won't appear on the login page.
If you are using NDS authentication, you can force users to type in their full user principal name by leaving this item blank, after removing the leading "#."
(NFuse Admin Web Pages | Authentication | Explicitly login)
A "default" setting means that users will be authenticating to a Microsoft domain or server. You can change this field to "NDS" if your users will be authenticating to an NDS tree. If you use this setting, you need to specify an NDS tree (see the next item). NDS authentication requires Feature Release 1 or 2 on the MetaFrame XP servers that the users will log in to. (See Chapter 8 for details about NDS integration.)
(NFuse Admin Web Pages | Authentication | Explicitly login | Use NDS authentication | with tree name)
Use this line to specify the NDS tree that your users will be using to log in. Remember to remove the leading #, and to set the "LoginType" to "NDS."
(NFuse Admin Web Pages | Authentication | Explicitly login | Use NDS authentication | with search context list)
If you're using NDS authentication, you can add a comma-separated list of contexts to be searched by NDS users when they login. This can speed up your login time if all users are coming from just a few contexts, because the entire NDS tree will not have to be searched. If you specify this option, then only the specified contexts are searched, and if the user is not found there then his login will fail. If you leave this field blank or if you leave it commented out (#), then all of the contexts in the tree will be searched until the user's object is found.
Specifying what Options the Users can Change
You can use the NFuse.conf file to configure which options your users will see when they login to NFuse. Specifically, you can prevent them from being able to override certain default settings that you specify. Any settings that users make are saved locally to their client devices as cookies, unless a user has connected as a guest.
There are seven fields that affect the options that users can change via the web pages. All seven of these fields can be set to "On" or "Off." A value of "On" means that users can change the default application settings via a special NFuse web page, accessible via the little toolbox icon on the main application list page. A value of "Off" means that the setting is not displayed and the published application's default setting as configured in the CMC is used. The seven options fields are as follows:
(NFuse Admin Web Pages | ICA Customization | Window size)
This allows the users to change the default resolution of published applications.
(NFuse Admin Web Pages | ICA Customization | Window color)
This allows the users to change the default color depth of published applications.
(NFuse Admin Web Pages | ICA Customization | Audio quality)
This allows the users to change the default audio quality of published applications.
If this is set to "On," users are able to set the "Remember folder location," "Show current folder location," and "Application detail display options" settings.
If this is set to "Off," users cannot change the options for how their applications are launched. Whatever options you configure via the EmbedApplications and EmbedMethod lines are used.
If you set this line to "On," your users will be able to override your default EmbedApplications and EmbedMethod settings.
This line allows you to specify how users' applications are launched. A value of "off" (which is what most people choose in the real world) means that applications are launched in separate windows. A value of "On" causes applications to be launched within the confines of a browser window.
The EmbedMethod line controls how the ICA client is used with embedded applications. There are many considerations to think about with the ICA client, so this line is discussed again in the "NFuse Web Clients" section of this chapter.
(NFuse Admin Web Pages | Authentication | Methods | Allow user to change password)
When set to "always," a little keychain icon is displayed on the main NFuse applications page. Clicking this pops up a web page where users can change their Windows domain password. In order to use this feature, the Citrix XML service that NFuse communicates with must be running on a MetaFrame XP server with at least Feature Release 2.
A value of "never" disables this functionality via NFuse.
You can also set this to "expired-only." Then, when a user logs into NFuse with an expired password, they are automatically forwarded to the password change webpage.
Code running on the Citrix XML service server performs the actual password change. Therefore, you can still use this functionality if your NFuse server is in a different domain than your Citrix XML server. In fact, it even works if your NFuse server is not in any domain.
How the NFuse.conf File Affects Web Pages
Many people wonder how the NFuse.conf file has the ability to affect the options that are available in NFuse web pages, because the NFuse web pages stay the same regardless of the settings of the NFuse.conf file. When the web server service is started, the NFuse Java Objects read the values of all the fields from the NFuse.conf file into memory. This is why you must stop and start the web server service after you make a change to the NFuse.conf file, because that file is only read once when the service is started.
When a web user requests a web page from the web server, the scripts in the web page check the NFuse Java Objects to find the values of the parameters they need to use. For example, the script code contained in the login page might look something like this (from a logical perspective):
If the LoginType in the NFuse.conf is "default," then I will
draw username, password, and domain boxes.
If the LoginType in the NFuse.conf is "NDS," then I will draw
username, password, context, and tree boxes.
As you can see, the people that wrote the NFuse web pages put in the necessary logic to check the values of the NFuse Java Objects (read from the NFuse.conf file) to see what custom options it should use as each web page is being constructed. In actuality, the fact that the NFuse.conf file can be used to affect web pages is a feature of the web pages themselves, not NFuse. This causes the NFuse web pages to be more complex (and to be harder to write), but it makes it easier for you to configure them.
Where is the Citrix Web Site Wizard?
If you have used any versions of NFuse prior to NFuse 1.6, you probably used the Citrix Web Site Wizard to create your web pages. The Citrix Web Site Wizard was a stand-alone tool to build NFuse web sites for NFuse versions prior to 1.6. It was a GUI program that stepped through the different options available for NFuse web pages and then generated the pages. From there, you could copy the pages into your web server directory.
With NFuse 1.6x and 1.7, there is no need for the Citrix Web Site Wizard because all of the options that you could change with the Web Site Wizard can now be set with the NFuse.conf configuration file or via the NFuse administration web pages.
Some people like to point out that the Citrix Web Site Wizard also allowed you to apply different "themes" to the websites it created. These themes changed the look and colors of the website, similar to the website themes available in Microsoft FrontPage. The Web Site Wizard only came with three themes (all pretty lame), and Citrix never released any more. The fact that these themes do not exist in NFuse 1.7 is not a big loss. If you want to, you can change the themes of the default NFuse 1.7 websites with any web editing tool, including FrontPage. Just be careful that you don't delete any of the web scripting code.
Understanding the Default NFuse Web Site
Before going much farther in our exploration of the NFuse web pages, we need to understand NFuse's default web pages, what they are, and how they work. We'll do that in the next section. Now, let's take a high-level look at web page scripting in general. This will help you understand how the NFuse web pages work. If you're already an expert on website scripting, skip directly to the "NFuse Default Website Flowchart."
An Overview Web Page Scripting
It seems that most MetaFrame XP administrators grew up as network engineers, as opposed to application developers. Because of this, it can be difficult to understand how the NFuse web pages really work. Fortunately, with NFuse 1.7, we can configure most options via the NFuse.conf file or the administrative web pages without needing to worry exactly how the web pages fit together. Still, it's worth taking a look at the basics of web page scripting.
First, let's consider standard HTML. HTML is a "tag-based," document language. This means that HTML documents are viewed as written, except that there are some special sequences of characters or "tags," that the viewing program knows indicate special formatting. For example, consider the following HTML code:
Hello. The current temperature is 14 degrees.
If you viewed this HTML code in an HTML viewer (i.e. web browser), it would look like this:
Hello. The current temperature is 14 degrees.
It looks exactly as it was typed because there are no "tags," or special formatting instructions. However, the next sample HTML code is a bit different:
<p><b>Hello</b>. The current temperature is <i>14 degrees</i>.</p>
This code contains some special instruction tags between the < > symbols (or "tags.") This code will display text with the following formatting applied:
Hello. The current temperature is 14 degrees.
The HTML viewer (web browser) knows that the letters enclosed in the < > brackets are special characters that represent instructions for the browser. In this case, the browser follows the instructions by applying special formatting to the words. <p> means paragraph, <b> means bold, and <i> means italics. The web browser knows what these special tags mean because they are defined in the international HTML standard. Pure HTML works well for static content, but fails if the web page must display information that may change. How do you include information that changes in HTML pages?
The answer is with web page server-side scripting. Web server-side scripting takes HTML a step further. With server-side scripting, regular HTML code is used as the foundation, with special executable instructions (in the form of a scripting language) included, sprinkled throughout the HTML. When a web browser requests a page, the web server knows that special scripts are included within the HTML. The web server scans the page for the scripts, executes the scripts, and replaces the script code with the result of the script execution.
Imagine that you wanted to create a web page containing information that might change often, such as the current temperature. The final web page as viewed in a web browser might look like this:
Hello. The current temperature is 42 degrees.
The HTML source code of the web page has an executable script in it that inserts the current temperature. The source code for this example might look like this:
<p><b>Hello.</b> The current temperature is <i> <%
Here is the script code that goes out and finds the
current temperature %> degrees </i></p>
In this example, the script section <% Here is the script code that goes out and finds the current temperature %> is executed before the page is sent to the client. The results of the script are put in place of the script code, in this case, "42". The final web code that the client browser sees then looks like this:
<p><b>Hello.</b> The current temperature is <i> 42
The web browser's doesn't know that any server side scripting took place-even though the web administrator was able to give each web browser client a custom page.
In the real world, static HTML pages usually have the file extension .HTM or .HTML. Pages that are dynamically generated from scripts usually have an extension that indicates the language of the scripts, such as .ASP (Active Server Pages), .JSP (JavaServer Pages), or .CFM (Cold Fusion Pages).
Undoubtedly, as you surf the web, you probably notice that many of the web pages you view have a script extension, like .ASP, instead of a static extension, like .HTM. However, if you view the source code of these pages (view | source), you will notice that they are standard HTML pages and you won't see any special scripts. The reason for this is that when you view the source code on your web browser, the scripts have already executed on the web server. The scripts generated their content (like the "42" in our temperature example) and produced a standard HTML web page that you view in your browser.
This is how the default NFuse web pages work. Some of the pages are .HTM pages and others are .ASP (or .JSP for iPlanet and Apache servers). With the dynamic server script-enabled web pages, NFuse is able to create standard web pages that are viewable by any web browser-even though each user will see different applications listed.
NFuse Default Website Flowchart
After you install NFuse 1.7, you will notice that several web page files are placed in the web directory. As you begin to use NFuse, you can start to notice the different files used by the address in your web browser's address bar. In order to understand how the default web site is really set up, it's easiest to view it as a flowchart. Figure 11.3 (next page) on follows the process as a user logs into an NFuse Classic 1.7 web portal.
Figure 11.3: The NFuse web portal process
Modifying the Default NFuse Web Site
In order to begin modifying the default NFuse web pages beyond what can be done with the NFuse.conf file and the administrative web pages, you need to understand how the pages work. The flowchart from the previous section detailed how the pages interact. However, even to a seasoned web programmer, the source code of the NFuse web pages looks a bit foreign at first. This is because the NFuse web pages have special methods of interacting with the NFuse Java Objects.
If you haven't figured it out already, the default web pages that are included with NFuse 1.7 are very powerful. If there is any additional functionality that you need, you can usually just modify the existing pages. Modifying the default NFuse pages is legal and encouraged by Citrix.
In this section, we're not going to talk about all of the modifications that could be made-your imagination will take care of that. What we will do is show you enough about the default NFuse website and how it interfaces with the NFuse Java Object that you are able to what to modify and how to modify it.
How Web Pages Interact with the Java Objects
There are three ways in which the NFuse web pages can interface with the NFuse Java Objects
- Session Fields.
- Substitution Tags.
- Via Java functions defined in the Java Objects.
The details of the NFuse Java functions are beyond the scope of this book. Fortunately, you can change all sorts of things without knowing anything about Java. If you would like to explore the functions available for interfacing with the NFuse Java Objects, a full Java Objects reference is available in the Citrix NFuse document titled "Customizing NFuse 1.7," available as part of the NFuse download.
By skipping the Java functions, we now have only two items to look at: session fields and substitution tags. Let's start with session fields.
A session field is a bit of NFuse-specific data as it relates to a user's NFuse session. Session fields hold all types of information, such as the current user name, the MetaFrame XP server name and address, and application settings. The values of session fields are stored in the NFuse Java Objects on the web server, causing a session field to behave like an "NFuse-specific" variable.
For example, when you login to a default NFuse web portal, the default login web page asks for three items: username, password, and domain. After you type each of these in and press "Submit," the value of each is written to an NFuse session field object.
Session field object names always begin with "NFuse_." In the login example mentioned above, the code in the login.asp web page might look something like this:
Username box = SessionField.NFuse_User
Password box = SessionField.NFuse_Password
Domain box = SessionField.NFuse_Domain
After the user "brian" logged in, the three session fields would hold the three following values:
NFuse_User = Brian
NFuse_Password = montypython
NFuse_Domain = bigdomain
Dession fields exist so that multiple web pages can all have the same information. For example, after the user logs in to the login.asp page, he is forwarded to the applist.asp page which is responsible for drawing his list of MetaFrame XP applications. One of the first things that the applist.asp page will do is read the values from these three session fields so that it knows who the user is.
Each user that logs into an NFuse web portal has his own set of session fields so that the session field values between multiple users do not get mixed up. For those of you familiar with web programming, NFuse session fields are similar to web server session variables.
There are many ways that session field values can be set. In addition to a web page setting a value like we saw in the previous example, session field values can be set via URL parameters, web browser cookies, ICA files, or the NFuse.conf file. Because session fields can be set in multiple places, it's possible that a single session field might get set in two places with conflicting values. Whenever there is a conflict, the NFuse Java Objects look to the NFuse.conf file to see what precedence the different methods should take. This is done via the following line:
In addition to specifying the precedence of session field values (values listed from highest to lowest precedence), this line also specifies where session fields can be set. If an entry is not in the line, the Java Objects will ignore session fields set in this manner. For example, if you remove the "Url" entry from the SessionFieldLocations in the NFuse.conf file, you will not be able to set session fields via URL parameters. Let's take a look at what each of these locations means:
PNAgent. Session field values can be set from values in the Program Neighborhood Agent, via the config.xml file. (See the PN Agent section towards the end of this chapter for more details.)
Script. Session field values can be set from a web page server side script, such as an ASP or JSP page. For example, the web page script could have a line that says:
NFuse Session Field Name = Brian
Template. Session field values can be set from an HTML or ICA template file. Such a template file would contain substitution tags (covered in the next section) that are replaced with real data by the NFuse Java Objects when the file is requested by a client. Some of these substitution tags can request that the Java Objects update the value of a session field.
URL. Session field values can be set from parameters passed via an HTTP URL. For example the URL /myfile.asp?name=Brian&state=Ohio would set the session field values "name" equal to "Brian" and "state" equal to "Ohio."
Post. Session field values can be set from the HTTP post method. This method is usually used with HTML forms. For example, a login HTML page might have a text field called "name" where users enter their name. Upon clicking the "submit" button, the web page would forward (post) the inputted text as a "name" value, write the value to the "name" session field, and then open the next web page.
Cookie. Session field values can be set from an HTTP cookie stored on the client web browser's machine.
Properties. Session field values can be set from settings in the NFuse.conf file.
NFuse substitution tags are used to access the information stored in session fields. Substitution tags can be used in standard HTML web pages or in template ICA files. When a client web browser requests a file containing NFuse substitution tags, the NFuse Java Objects template parser scans the file and replaces any substitution tags with the real value stored in the session fields.
Every bit of user-specific NFuse data has an NFuse_xxxxx session field name and substitution tag. The session field is a way for data to be written to and read from the session field, and the substitution tag is a simple way to display the data stored in a session field.
NFuse substitution tags are enclosed in [ ] brackets. Let's look at some simple HTML code that uses substitution tags to access the session fields of the NFuse Java Objects to show the name of the currently logged on user. The HTML source code might look like this:
The current user is [NFuse_Domain]\[NFuse_User].
When this HTML page was sent to a web client, the NFuse Java Objects template parser would replace the substitution tags ([NFuse_Domain] and [NFuse_User]) with the actual session field data, in this case "briansdomain" and "Brian." This would cause the actual HTML code sent to the client to look like this:
The current user is briansdomain\Brian.
Substitution tags can also be used to provide information about applications. For example, consider the following HTML code:
The current application is [NFuse_AppName]. The resolution
is [NFuse_WindowWidth] x [NFuse_WindowHeight].
The substitution tags could be replaced in this HTML code to form the following:
The current application is Word 2000. The resolution is 800 x 600.
There are two ways to use NFuse substitution tags:
- Put them in HTML pages.
- Put them in the template ICA files.
Adding substitution tags to HTML files is very straightforward. All you need to do is to add the tags to your HTML code. We're going to focus on the template ICA files and how they use substitution tags, because understanding how those work is very important in the real world.
ICA Template Files
Remember that whenever a web user clicks a hyperlink to launch an NFuse application, the web server sends an ICA file for that application down to the user. However, there is not a folder full of ICA files that are ready to go. Rather, the ICA file is dynamically built for that particular user as soon as the icon is clicked. In order to build that ICA file, NFuse starts with a preconfigured ICA template. This template is a file stored on the web server as template.ica. This is similar to a regular ICA file, except that the information that would be specific to one user or application is in the form of NFuse substitution tags. When a web user requests an application, the NFuse Java Objects retrieve the template.ica file and replace the NFuse substitution tags with the actual data relevant to that user or application.
Remember that the default NFuse website has two template ICA files: template.ica and guest_template.ica. The default web pages have logic to detect if a user is logged on anonymously or not. If they are, the guest_template.ica file is used. If not, then they are given an ICA file based on the template.ica file. Let's look at the template.ica file now. As you examine it, scan for the following three types of data:
- Substitution Tags, enclosed in the [ ] brackets, that begin with NFuse_.
- Session Fields, enclosed in the <[ ]> brackets.
- Actual, legitimate ICA information.
The two ICA files are compared side-by-side on the following two pages.
As you can see in this sample ICA file, most of the application information from the real ICA file has been replaced by substitution tags in the template ICA file. If for some reason there is any ICA setting that you want to be the same for all of your NFuse users, you can just overwrite the substitution tag with the real data in the template.ica file.
In case you're wondering, the guest_template.ica file only has a few lines that are different from the regular template ICA file. There are two session field declarations at the beginning of the guest template that are not in the regular template:
Additionally, the two lines that contain user credential information in the regular template are not present in the guest template:
Figure 11.4: The template.ica file from the default web site.
Figure 11.5: A real ICA file
Creating NFuse Web Sites from Scratch
Some people choose to build NFuse web sites from scratch. There is nothing technical to prevent this, and all of the NFuse Java Objects and substitution tags can be used. While this method may give the most flexibility, it can be time consuming to build a website from the ground up. Most people end up customizing the default pages.
Advantages of Building NFuse Web Pages from Scratch
- Most flexibility.
- NFuse "nuggets" can be created to integrate with existing pages or portals.
- When you're done, you will really know what you are talking about.
Disadvantages of Building NFuse Web Pages from Scratch
- Time consuming.
- You must know exactly what you are doing.
- You will probably reinvent the wheel a few times along the way.
(Note: You must be logged in to post a comment.)
If you log in and nothing happens, delete your cookies from BrianMadden.com and try again. Sorry about that, but we had to make a one-time change to the cookie path when we migrated web servers.