Chapter 3. Getting Started
Prev |  | Next

# Chapter 3. Getting Started

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.

## 3.1. Before You Begin

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.

## 3.2. Installation Steps

1. Download and if necessary unpack the gateway .war file.

2. Download and unzip the OpenIG sample configuration files.

3. Download and unzip Jetty 7.1.6 Hightide.

4. 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

5. 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

6. 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>

7. 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>

8. 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

## 3.3. Configuration Steps

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

### Tip

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`.

## 3.4. Try It Out

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.

Prev |  | Next
Chapter 2. How OpenIG Works | Home | Chapter 4. Installing OpenIG