Java Tip 42: Write Java apps that work with proxy-based firewalls

How to use Java to connect with HTTP servers outside your corporate firewall

Almost every company is concerned with protecting its internal network from hackers and thieves. One common security measure is to completely disconnect the corporate network from the Internet. If the bad guys can't connect to any of your machines, they can't hack into them. The unfortunate side effect of this tactic is that internal users can't access external Internet servers, like Yahoo or JavaWorld. To address this problem, network administrators often install something called a "proxy server." Essentially, a proxy is a service that sits between the Internet and the internal network and manages connections between the two worlds. Proxies help reduce outside security threats while still allowing internal users to access Internet services. While Java makes it easy to write Internet clients, these clients are useless unless they can get past your proxy. Fortunately, Java makes it easy to work with proxies -- if you know the magic words, that is.

The secret to combining Java and proxies lies in activating certain system properties in the Java runtime. These properties appear to be undocumented, and are whispered between programmers as part of the Java folklore. In order to work with a proxy, your Java application needs to specify information about the proxy itself as well as specify user information for authentication purposes. In your program, before you begin to work with any Internet protocols, you'll need to add the following lines:

System.getProperties().put( "proxySet", "true" );
System.getProperties().put( "proxyHost", "myProxyMachineName" );
System.getProperties().put( "proxyPort", "85" );

The first line above tells Java that you'll be using a proxy for your connections, the second line specifies the machine that the proxy lives on, and the third line indicates what port the proxy is listening on. Some proxies require a user to type in a username and password before Internet access is granted. You've probably encountered this behavior if you use a Web browser behind a firewall. Here's how to perform the authentication:

URLConnection connection = url.openConnection();
String password = "username:password";
String encodedPassword = base64Encode( password );
connection.setRequestProperty( "Proxy-Authorization", encodedPassword );

The idea behind the above code fragment is that you must adjust your HTTP header to send out your user information. This is achieved with the setRequestProperty() call. This method allows you to manipulate the HTTP headers before the request is sent out. HTTP requires the user name and password to be base64 encoded. Luckily, there are a couple of public domain APIs that will perform the encoding for you (see the Resources section).

As you can see, there's not a whole lot to adding proxy support to your Java application. Given what you now know, and a little research (you'll have to find out how your proxy handles the protocol you're interested in and how to deal with user authentication), you can implement your proxy with other protocols.

Proxying FTP

Scott D. Taylor sent in the magic incantation to deal with proxying the FTP protocol:

defaultProperties.put( "ftpProxySet", "true" );
defaultProperties.put( "ftpProxyHost", "proxy-host-name" );
defaultProperties.put( "ftpProxyPort", "85" );

You can then access the files URLs using the "ftp" protocol via something like:

URL url = new URL("" ); 

If anybody has examples of using a proxy with other Internet protocols, I'd love to see them.

Note: The example code ( has only been tested with JDK 1.1.4.

Ron Kurr has been working as a software engineer at Cabletron Systems for the past eight years, using C++, Unix, and NT. For the past two years he has devoted himself to Java and Internet technologies.

Learn more about this topic

  • java.lang.System
  • HTTP Client API
  • Cabletron Systems
  • CsProxy (a free proxy server)
  • Relevant RFCs