This chapter provides instructions to get OpenIG up and running on Jetty, configured to execute the WordPress samples at our hosted WordPress deployment. This allows you to quickly see how OpenIG works and provides hands on experience with a few key features. If you are looking for more general installation and configuration instructions for your deployment or would like to use a container other than Jetty, start with the chapter on Installing OpenIG.
For the remainder of this chapter, $HOME is the
location of the home directory of the user running the web application
container, where Jetty, OpenIG and the Samples are unpacked.
Make sure you have the correct Java environment installed. If necessary, download and install Sun Java SE JDK 6 Update 21 or later. At this time these are the only versions of any JDK supported with OpenIG.
Download and if necessary unpack the gateway .war file.
Download and unzip the OpenIG sample configuration files.
Download and unzip Jetty 7.1.6 Hightide.
Copy the OpenIG .war file as root.war to the
webapps/ directory in Jetty.
When copied to this location along with the
root.xml file below, Jetty automatically deploys OpenIG
on startup.
$ cp $HOME/gateway-*.war $HOME/jetty-hightide-7.1.6/webapps/root.war
Copy the WordPressLogin.json gateway
configuration file to
$HOME/.ForgeRock/OpenIG/config.json. By default,
OpenIG looks for config.json in the
$HOME/.ForgeRock/OpenIG/ directory.
$ cp $HOME/forgerock-sample-configs/WordPressLogin.json $HOME/.ForgeRock/OpenIG/config.json
Create
$HOME/jetty-hightide-7.1.6/contexts/root.xml with the
following content. This tells Jetty to deploy OpenIG in the root
context:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
"http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war"><SystemProperty name="jetty.home"
default="."/>/webapps/root.war</Set>
<Set name="extractWAR">true</Set>
<Set name="copyWebDir">false</Set>
<Set name="defaultsDescriptor"><SystemProperty name="jetty.home"
default="."/>/etc/webdefault.xml</Set>
</Configure>If you are managing multiple
applications in one domain you must turn on domain cookies in Jetty. This
can be done by adding the following property to
$JETTY_HOME/contexts/root.xml or to
$JETTY_HOME/etc/jetty.xml. Note that any changes to
jetty.xml impact all web applications running in the
container.
<Get name="sessionHandler">
<Get name="sessionManager">
<Set name="sessionDomain">.forgerock.com<Set>
<Get>
<Get>Start Jetty in the background:
$ $HOME/jetty-hightide-7.1.6/bin/jetty.sh start
Or start Jetty in the foreground:
$ java -jar $HOME/jetty-hightide-7.1.6/start.jar
So far you have deployed the gateway web application in the root
context of Jetty on port 8080. Since the gateway is a reverse proxy you must
make sure all traffic from your browser to
http://demo.forgerock.com:8080/wordpress/ goes through the
gateway. The quickest way to do this is to add an entry to your
/etc/hosts file on UNIX systems or
%SystemRoot%\system32\drivers\etc\hosts on Windows. See
Wikipedia for more information on host files. If you are running
OpenIG and the browser on the same host, add this entry to the hosts file on
the OpenIG host.
127.0.0.1 demo.forgerock.com
If you are running the browser and OpenIG on separate hosts, you must add the IP address of the host running OpenIG. For example, if OpenIG is running on a host with IP Address of 10.0.1.5:
10.0.1.5 demo.forgerock.com
Some browsers cache IP address resolutions, even after clearing all
browsing data. It might be necessary to restart the browser if you are
changing IP addresses of named hosts. The simplest way to make sure you have
configured your DNS or host settings properly is to stop OpenIG and
make sure you cannot reach the target application. If you can still reach
it, you should double check your host settings. You should also make sure
your name resolution is configured to check your host files before DNS.
This configuration can be found in /etc/nsswitch.conf
for most UNIX systems. Make sure files is listed before
dns.
http://demo.forgerock.com:8080/wordpress should take you to the
WordPress portal hosted at ForgeRock. When you click the login link, you are
automatically logged in by OpenIG with the user name
george.
What's happening behind the scenes?
When your browser goes to
http://demo.forgerock.com:8080/wordpress/, it is actually
connecting to OpenIG deployed on Jetty. OpenIG is configured to proxy all
traffic it receives to the target application at
http://demo.forgerock.com:8080/wordpress/. For this
example, OpenIG is watching for the login page from WordPress. When it sees
the login page, it creates and POSTs the login form for WordPress on behalf
of the user. Since this is just a sample, the credentials for the user are
hard coded in the gateway configuration file. In a real deployment, the
credentials may come from a database, directory, flat file, HTTP headers,
SAML assertion,or an OpenAM policy agent.