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.
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.
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.Browser sends the request to OpenIG.
OpenIG inspects the request, finds no login page match.
OpenIG forwards the original request to the Portal.
Portal finds no local application session and redirects to the Portal login page.
OpenIG intercepts the redirect, inspects the request, finds a login page match.
OpenIG creates the login form.
OpenIG POSTs the login form to the Portal.
Portal validates the login and redirects to the Portal end user page.
OpenIG receives the final redirect and passes it back to the Browser.
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/hostspointingdemo.forgerock.comto 10.0.1.1 (substitute your OpenIG's IP address)
See Getting Started for instructions, and have your container listen on port 8080.
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.
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.
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.
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.
where xxx}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}"].
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.