Chapter 7. Tutorial With WordPress
Prev |  | Next

# Chapter 7. Tutorial With WordPress

This tutorial gives you hands on experience with the basic features of OpenIG. You install the Gateway in your network and point it to an installation of the WordPress Portal hosted at http://demo.forgerock.com:8080/wordpress. The tutorial progresses through the following steps and explains what is happening by walking you through OpenIG configuration.

- Pure reverse proxy mode to the Portal

- Login with hard coded credentials

- Login with credentials from a flat file

- Login with credentials from MySQL

Before you begin the tutorial, read the chapter on How OpenIG Works.

## 7.1. Detailed Flow

The figure and the steps below detail the flow between the browser, OpenIG and the portal for a basic login sequence to the portal. The key concept to understand is all requests to the application are routed through OpenIG by modifying the DNS entry for the target application. OpenIG can then be configured to intercept specific pages, such as login pages, and create requests to log the user in.

[D]

1. User browses to the Portal, browser host makes a DNS request to get the IP address for `demo.forgerock.com`, DNS returns the IP address of OpenIG.

2. Browser sends the request to OpenIG.

3. OpenIG inspects the request, finds no login page match.

4. OpenIG forwards the original request to the Portal.

5. Portal finds no local application session and redirects to the Portal login page.

6. OpenIG intercepts the redirect, inspects the request, finds a login page match.

7. OpenIG creates the login form.

8. OpenIG POSTs the login form to the Portal.

9. Portal validates the login and redirects to the Portal end user page.

10. OpenIG receives the final redirect and passes it back to the Browser.

## 7.2. Setup Summary

To keep things simple, these instructions assume you are running OpenIG and the Browser on a single host. If they are on separate hosts, make sure the host or DNS changes impact the Browser host. This tutorial also assumes Jetty 7 for the container, but you can use any supported container.

- OpenIG IP address 10.0.1.1 (substitute your OpenIG's IP address)

- Jetty 7 listening on port 8080

- OpenIG deployed under the root context

- DNS or `/etc/hosts` pointing `demo.forgerock.com` to 10.0.1.1 (substitute your OpenIG's IP address)

## 7.3. Installing OpenIG

See Getting Started for instructions, and have your container listen on port 8080.

## 7.4. Configuring the Browser Host

With OpenIG running, configure the browser to go through OpenIG to get to the Portal. To do this we need to modify DNS or `/etc/hosts` so `demo.forgerock.com` points to the IP address of the host running OpenIG. If you are using `/etc/hosts` be sure to check that the naming services for your host check checking files before DNS. On UNIX systems this is configured in `/etc/nsswitch.conf`. Assuming OpenIG is running on 10.0.1.1, the `/etc/hosts` entry should be the following:

    10.0.1.1   demo.forgerock.com

Before continuing please verify your name to IP address changes are working properly. The simplest way to do this is to ping `demo.forgerock.com`. You should see the following if you have properly configured your name to IP mapping:

    $ ping demo.forgerock.com
    ping demo.forgerock.com
    PING demo.forgerock.com (10.0.1.1): 56 data bytes
    64 bytes from 10.0.1.1: icmp_seq=0 ttl=64 time=0.053 ms

If the ping command returns the actual address of `demo.forgerock.com`, you need to recheck your settings.

## 7.5. Configuring OpenIG & Trying It Out

For the remainder of this document, `$HOME` refers to the location where you unzipped your sample configuration files.

Download and unzip the sample configuration files. If you installed through quick start you already have the configuration files downloaded and installed.

Copy `WordPressProxyOnly.json` to `$HOME/.ForgeRock/OpenIG/config.json`. By default, OpenIG looks for `$HOME/.ForgeRock/OpenIG/config.json` for its configuration. You must restart the OpenIG container when making any change to the configuration file.

    $ cp $HOME/forgerock-sample-configs/WordPressProxyOnly.json
     $HOME/.ForgeRock/OpenIG/config.json
    $ jetty.sh restart

To try out the first sample browse to http://demo.forgerock.com:8080/wordpress. You should see the WordPress Portal home page. If you click on the login link you should be prompted to login to the application as if you were accessing it directly. To verify you are actually going through OpenIG, stop the OpenIG container, refresh your browser and try to access the application again. If you still see the application, make sure your DNS or host files are configured to point to OpenIG instead of the Portal. You can login to the Portal with user name `george` and password `costanza`. The next section shows how to configure OpenIG to intercept the login page and automatically log you in when it sees that you have clicked the login link.

To see what is happening behind the scenes, take a look at `$HOME/.ForgeRock/OpenIG/config.json`. Look for the HandlerServlet. This is the servlet entry point to OpenIG. The HandlerServlet passes the request off to another handler which may be a chain of filters and handlers. In the pure proxy case there is no special logic to execute so it hands off to the ClientHandler. The job of the ClientHandler is to send the request on to the target. Since there are no chains called before the ClientHandler, the request passes through to the target untouched.

## 7.6. Login with Hard Coded Credentials

Now that OpenIG can proxy all traffic to and from the application, the next step is to configure OpenIG to intercept the login page, and POST the login form to the Portal.

    $ cp $HOME/forgerock-sample-configs/WordPressLogin.json
     $HOME/.ForgeRock/OpenIG/config.json
    $ jetty.sh restart

As you changed the OpenIG configuration file, you must restart the OpenIG container. After restarting you should be able to go to http://demo.forgerock.com:8080/wordpress, click on the login link, and be logged in as the user george without entering your credentials. OpenIG has intercepted the request for the login page, created the login form, and POSTed the request to the Portal.

To see what is happening behind the scenes, take a look at `$HOME/.ForgeRock/OpenIG/config.json`. This time you notice the HandlerServlet is calling the DispatchHandler. The DispatchHandler has a condition which checks for the presence of `wp-login.php` (the login page) in the URI path. If the condition is false (no login page), the ClientHandler is called sending the request on to the Portal. If the condition is true, OpenIG has found the login page, and calls the LoginChain for further processing. The LoginChain calls its filter, the LoginRequestFilter, which creates the login form, and then calls the ClientHandler to send the form to the Portal. If you look at the LoginRequestFilter, you notice it defines the method, URI, and form parameters for the request which is sent by the ClientHandler. In the form parameters you see the hard coded credentials, which are used to log you in as the user `george`.

## 7.7. Login with Credentials From a Flat File

Hard coding login credentials is great for a sample, but not realistic when it comes to a production deployment. In this next section you see how OpenIG can be configured to fetch the user's credentials from an external source, such as a directory or a database. For this sample, you use a flat file and the FileAttributesFilter. The key to look up the user in the flat file is hard coded, but you can understand how the key could come from something in the incoming request, such as an HTTP header, a session cookie, or even a SAML assertion.

For this sample you must modify the file attribute in the FileAttributesFilter object in `config.json` to reflect the location of the sample flat file. The location of the user file shipped with the samples is `forgerock-sample-configs/userfile`.

    $ cp $HOME/forgerock-sample-configs/WordPressLoginFile.json
     $HOME/.ForgeRock/OpenIG/config.json
    $ jetty.sh restart

After restarting the container, check that you can go to http://demo.forgerock.com:8080/wordpress and be logged in as the user `george` without seeing the login page. To verify the login credentials are being picked up from the flat file, change george's password, restart OpenIG, and try the login page again. You should get a login failed page. If you would like to log in as a different user, look for the value attribute in `config.json`, replace `george@seinfeld.com` with `kramer@seinfeld.com`. Both `george` and `kramer` have accounts on the Portal so you can log in with either.

To see what is happening behind the scenes, take a look at `$HOME/.ForgeRock/OpenIG/config.json`. For this sample, you added one additional filter to the LoginChain and made a slight modification to the LoginRequestFilter. Take a look at the LoginChain and you can see the filters attribute now has the value of `["FileAttributesFilter","LoginRequestFilter" ]`. When the LoginChain is executed the FileAttributesFilter will be called prior to the LoginRequestFilter. The FileAttributesFilter sets the results of its lookup in the Exchange accessible through the Expressions `${exchange.credentials.`xxx`}` where `xxx` is the name of any one of the values from the flat file. Now take a look at the form attribute in the LoginRequestFilter. The hard coded values for log and password have been replaced with `["${exchange.credentials.username}"]` and `["${exchange.credentials.password}"]`.

## 7.8. Login with Credentials From MySQL

This sample fetches the login credentials from MySQL. You must have access to an instance of MySQL in order to execute this sample. If you do not have access or just want to see how the SqlAttributesFilter works, just read the rest of this section.

For this sample you must configure your container for JNDI and MySQL. See the chapter on Configuring Deployment Containers for instructions on configuring containers for use with JNDI and MySQL. You also must create an entry for a user and create a query which returns a result with user name and password attributes. The query in the sample assumes there is a table named `users`, with attributes `username` and `password`. The parameter passed into the prepared statement is `email=george@seinfeld.com`.

    $ cp $HOME/forgerock-sample-configs/WordPressLoginSQL.json
     $HOME/.ForgeRock/OpenIG/config.json
    $ jetty.sh restart

To see what is happening behind the scenes, take a look at `$HOME/.ForgeRock/OpenIG/config.json`. For this sample, you replaced the FileAttributesFilter with the SqlAttributesFilter. The only difference between the filters is how they retrieve the attribute value pairs to set in the Exchange. Once the values are set in the Exchange, the LoginRequestFilter accesses them in the exact same way.

Prev |  | Next
Chapter 6. Detailed Use Cases | Home | Chapter 8. Tutorial On OpenAM Password Capture & Replay