A common scenario would be implementing and deploying a Citrix or Microsoft terminal server in conjunction with a Web site that requires authentication. Once the user authenticates to the Web service, the user's browser initiates a client session with the terminal server. Ordinarily, a port must be left open to all terminal servers so that a user coming from anywhere on the internet can gain accesses to it. The npsProxy will only allow users who have authenticated to NPS to initiate connections to the Citrix or terminal servers.

npsProxy is composed of two pieces: npsProxyAgent and npsProxyGadget. npsProxy is intended to solve the problem of building a web service and having to leave non-authenticated/secured ports open to the world. This proxy will only allow connections from IP addresses known to have users authenticated to NPS. Although this proxy will work fine for basic http, better alternatives exist for http (namely iChain)

npsProxyAgent:
==============
npsProxyAgent is a stand alone Java command line application. It acts as a TCP proxy and will redirect any TCP protocol traffic.

It is known to work with the following protocols:
- ica (Citrix)
- http (Web)
- telnet
- ssh (Secure Telnet)
- rdp (Microsoft Terminal Server)
- pop3 (email)
- imap4 (email)
- smtp (email)
- irc (chat)

It should work with any other TCP protocol that also works through NAT.

The npsProxyAgent can run anywhere Java runs. It does not need to be run on the same machine(s) that run NPS. It will run anywhere any Java application can run. It has been tested on the following platforms, but any 1.4 JVM on any OS should be okay:

- Microsoft Windows 2000 (Sun JVM 1.4.1)
- Microsoft Windows XP Pro (Sun JVM 1.4.1)
- RedHat Linux 8.0 (Sun JVM 1.4.1)
- iChain 2.2 (Novell JVM 1.4)

The proxy agent will not start unless the JVM is at least version 1.4.1.

First, verify that the Java JVM is installed and in the path by typing:

'java -version'

If the output is something other than the version of the installed JVM, please correct the issues before proceeding.

To start the npsProxyAgent, enter the following into a command prompt:

'java -jar npsProxyAgent.jar -help'

If you see a help output, you're on your way.

Next step is setting up the config.xml file. This file controls the settings of the proxy. A sample file with descriptions of each setting is included.

npsProxyAgent has several components:

GadgetListner - listens for communications from the gadget to control who can access the agent.
HttpListener - listens for browser requests and add's the request's ip addresses directly to the agent.
WebStats - A built in web server to display the current condition of the agent.
Conduits - The proxies or "tunnels" configured in the agent (can be multiple).
Logger - Outputs agent events to screen or file.

The npsProxyAgent maintains a list of allowed IP addresses or "permissions". When the proxy first starts up, no permissions exist and thus no connections can be made through the proxy. The gadget periodically will send the npsProxyAgent updates of permissions that are added to the npsProxyAgent's permission table.

Once those permissions are known to the npsProxyAgent, it will allow connections to be made through itself to the destination only if the source IP address of the connection matches a known permission.

npsProxyAgent Features
======================
=== Throttling
Connections can be "throttled" to force the total bandwidth for a given connection to a certain minimum. To enforce, set the "maxbytes" param. When the proxy is in debug mode it will indicate when connections are throttled.

In the interest of keeping the proxy fast, the throttling is not exact, and can be off as much as en entire packet size (1500 to 4096) bytes.

=== Echo
For debugging purposes, an individual conduit can be configured so that all packets are dumped to the console. This should only be used for debugging as it will severely hamper performances.

npsProxyGadget
==============
This is an nps gadget that deploys inside of NPS 1.5 . This gadget's sole purpose is to inform the npsProxyAgent(s) of logged in user's IP addresses. The gadget has no user output, and only prints messages to the nps log.

The gadget should be installed and placed somewhere so that users who should receive access to the service being offered by the proxy will get the gadget. Assignment to a theme works best, other possibilities would be a home page or a page overlay on a home page. A gadget does not get activated until the page (or theme) it is on is viewed by the user, so it can not work effectively other than on a theme or the first page a user views.

When first configuring the gadget, a good place is on the home page in a column. The gadget outline will appear to the user (and the administrator). Once the behavior is as desired, then the administrator can turn off the gadget frame (under advanced settings for the gadget assignment) and the gadget will become invisible but will still be activated.

The gadget has four configuration parameters:

Agents: The ip address:host (This must include both parts, and look something line '192.168.1.1:9292'. This must be the same address(s) as the Agent's -gadget listener option. Several of these can be configured.

AgentDelay: How often the gadget sends Agents the list of current permissions. The default is 120 seconds.

AgentKey: A common shared key (text string) shared between the Agent and the Gadget. The default is "proxykey".

DebugLevel: what level of the nps debug log to send its output to.

Use Source IP: use the source IP address of the connection to nps.

Use X-Forwarded-For: use the IP address in the X-Forwarded-For parameter of http requests.

The gadget will watch for user logins. When a user login occurs, the gadget will request the user's client IP address from NPS. It will use this information to build a table of user's IP addresses. When a new unique address is added to the table, the npsProxyGadget will forward the address to the npsProxyAgent. Additionally, the npsProxyGadget will forward its entire current list to each npsProxyAgent at the interval set by "AgentDelay".

Other notes
===========
-- The gadget/proxy are designed so that multiple agents and multiple nps heads work fine. You can have as many of each as you want in your configuration. However, do NOT assign the gadget multiple times for each agent. Only one instance of the gadget should ever be assigned. Instead, configure multiple agents on one assignment.

-- If the user is behind a NATed address on their side of the network, the address that reaches NPS will be that of the NAT server, not the user's end address. In this case however, it is very likely that any other type of communication from that user will come through the same NATed address, so things should work out just fine. The downside here is that the npsProxyAgent will let in every machine behind that NATed address, but this is still a small problem compared to letting the entirety of the internet through to the destination.

-- If NPS is sitting behind iChain, the accelerator for NPS must have the "Forward browser IP address in Request Header [X-Forwarded-For]" setting enabled for this to work.

-- Other security issues: The npsProxyAgent has not been extensively tested for security issues. In particular, if access can be gained to the gadgetlistner port, it is a simple matter to add permissions to the proxy, rendering it ineffective. The proxy itself should be run behind a firewall and on a protected network. Every care and consideration was made during the development to keep it as secure as possible.

Deployment Tips
===============
- Things work fine if you have multiple portal heads (servers), both the gadget and agent were built with multiple portal servers in mind.

- If you need to have multiple agents for whatever reason, do NOT assign more instances of the gadget, instead, just add more values to the Agents configuration setting on the single gadget assignment.

- Want to run the agent as a service on NT/2000? There are many great programs around for doing just that with any command line application. The author has used http://www.firedaemon.com/ with good success, there are many others.

- If deploying to a farm of Citrix (or other servers), two possible deployment strategies are to either place the agent on a stand alone box in the DMZ, or to run the agent on each Citrix server itself.

Version History
===============
====1.9.0c (April 21, 2003)
Fixed a bug in the agent that would some times cause addresses to not be "local" when they really are.

====1.9.0 (April 21, 2003)
Added queuing system to gadget to increase performance and decrease nps load
Added "delete" permissions functionality to gadget
Switched to XML based config
permissions now cleaned when nps session is cleaned (no more waiting for cleaner/purger processes)
Major refactoring to improve performance and support new features
Added statistical tracking to all agent components
Added support for multiple conduits (proxies) in one instance of the agent
Added web server features
Added connection throttling

> This release breaks compatibility with earlier agents/proxies.

====1.1.1 (December 30, 2002)
Added -idle switch
Scalability improvements in the Agent
Added a helper bat file for starting on Win32

====1.1.0 (November 20, 2002)
Added support for X-Forwarded for headers (support for iChain)

====0.0.9 (Unreleased)
Speeded up the gadget cache

====0.0.8 (August 29, 2002)
Fixed a bug in the npg file presenting it from installing correctly
Improved the communications between the gadget & proxy
Fixed several log level related bugs in the proxy
Improved the gadget code to use less resources
Updated this document and added a diagram in jpg and Visio format

====0.0.7
First Release