In today's enterprise, more than 30% of web applications are incompatible with web access management (WAM) software. That is, unlike OpenAM with OpenIG, most web access management products lack the agent to protect the web applications, or the application is a legacy solution that does not follow standard protocols for single sign-on. This limits the return on the enterprise WAM investment and constrains what types of web applications can be protected.

ForgeRock's Open Identity Gateway addresses this problem by extending access management to encompass all web applications. With OpenIG, OpenAM deployments can now be extended to be inclusive of those applications that do not integrate with policy agents alone. In addition, ForgeRock Open Identity Gateway interoperates, out-of-the-box, with all management solutions. Most importantly, your organization can on-board any web application without ever modifying or touching the target application again, significantly reducing the development and quality assurance required to protect web applications.

The expertise and cost required to add SAML2 support to web applications is a problem for many businesses. Those businesses not moving to a standard for exposing their applications to their customers see increased cost and maintenance due to the complexity of one-off proprietary integrations. They may also see a loss of business to those customers requiring a Federation standard for authentication. Sometimes, deploying a full access mangaement solution just to federate a few applications is is too complex and costly, and building out their own solution by modifying their applications is just not possible.

OpenIG Federation Gateway allows businesses to add SAML2 support to their applications with little to no knowledge of the standard. In addition, there is no need to modify the application or install any plugin or agent on the application container.

In order to provide SSO, OpenAM policy enforcement points, the policy agents, have traditionally functioned as plugins for each application. The policy agents however use OpenAM specific APIs and protocols. In contrast, you can roll out OpenIG as an independent policy enforcement point that is built on the SAML2 standard.

OpenIG Federation Gateway can replace policy agents with a standards based SAML2 compliant enforcement point.

The underlying core of ForgeRock Open Identity Gateway is based on a reverse proxy architecture. All HTTP traffic to each protected application is routed through OpenIG, enabling close inspection, transformation and filtering of each request. By inspecting the traffic, OpenIG is able to intercept requests that would normally require the user to authenticate, obtain the user's login credentials, and send the necessary HTTP request to the target application, thereby logging in the user without modifying or installing anything on the application. In its simplest form and basic configuration, OpenIG is a Java-based reverse proxy which runs as a web application. Enable the Form-Filter replay module and OpenIG automatically log users in when a timeout or authentication page is detected. Additionally, enable the SAML2 service and OpenIG becomes a SAML2 endpoint. In this mode of operation, OpenIG receives and verifies the SAML2 request and then logs the user directly into the target application.

The following modules make up 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.

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

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.

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 install Tomcat 6 or Tomcat 7.

$TOMCAT_HOME refers to the location where you have installed Tomcat.

Configure Tomcat to listen on the same port and protocol of the application you are protecting with OpenIG. If your application listens on both an HTTP and an HTTPS port you must configure Tomcat to do so as well. If you are installing to run the samples you do not have to modify the Tomcat port configuration since both the Tomcat default and the samples use port 8080.

To configure Tomcat to use a port other than 8080 modify the defaults in $TOMCAT_HOME/conf/server.xml. The quickest way to do this is to search for the default value of 8080 and replace it with the new port number.

<Resource name="jdbc/forgerock" auth="Container" type="javax.sql.DataSource"
 maxActive="100" maxIdle="30" maxWait="10000"
 username="admin" password="11111111" driverClassName="com.mysql.jdbc.Driver"
 url="jdbc:mysql://localhost:3306/databasename"/>

<resource-ref>
    <description>MySQL Connection<description>
    <res-ref-name>jdbc/forgerock<res-ref-name>
    <res-type>javax.sql.DataSource<res-type>
    <res-auth>Container<res-auth>
<resource-ref>

<Context sessionCookieDomain=".forgerock.com" />

<Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    address="10.0.1.6"
    clientAuth="false" sslProtocol="TLS" keystorePass="11111111"/>

$ keytool -genkey -alias tomcat -keyalg RSA

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 install Jetty. The install directory is referred to as $JETTY_HOME from now on.

Configure Jetty to listen on the same port and protocol of the application you are protecting with OpenIG. If you are configuring OpenIG for the samples you do not have to modify the Jetty port configuration since the default for Jetty is 8080 and the samples use port 8080.

To configure Jetty to use a port other than 8080 you must modify the default $JETTY_HOME/etc/jetty.xml. The quickest way to do that is to search for the default value of 8080 and replace it with the new port number. The simplest way to get Jetty running on ports below 1024 is to run the Jetty process as root. This is only appropriate for sample purposes. Do not run Jetty as root in production.

If the application your are protecting is configured on an HTTPS port, you must configure Jetty for HTTPS as well.

If you are managing multiple applications in one domain you will need to 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">example.com<Set>
    <Get>
<Get>

If OpenIG accesses an SQL database you must configure Jetty for JNDI or use the Jetty Hightide distribution, which comes pre-configured for JNDI. Once you have Jetty configured you must add the jar for the database, and set up a JNDI data source and a reference to that data source in your web application. The following steps are for the MySQL Connector/J.

Download the MySQL JDBC Driver Connector/J Add it to the Jetty class path by copying it to $JETTY_HOME/lib/jndi.

Add a JNDI data source for your MySQL server and database in $JETTY_HOME/etc/jetty.xml.

<New id="jdbc/forgerock" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg><Arg>
  <Arg>jdbc/forgerock<Arg>
  <Arg>
    <New class="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
      <Set name="Url">jdbc:mysql://localhost:3306/databasename<Set>
      <Set name="User">mysqladmin<Set>
      <Set name="Password">11111111<Set>
    <New>
  <Arg>
<New>

Add a resource reference to the data source in $JETTY_HOME/etc/webdefault.xml.

<resource-ref>
    <description>My DataSource Reference<description>
    <res-ref-name>jdbc/forgerock<res-ref-name>
    <res-type>javax.sql.DataSource<res-type>
    <res-auth>Container<res-auth>
 <resource-ref>

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 install the community version of JBoss 5.1. $JBOSS_HOME refers to the location you have installed JBoss. The assumption in this chapter is that you run the default server configuration.

Configure JBoss to listen on the same port and protocol of the application you are protecting with OpenIG. If your application listens on both an HTTP and an HTTPS port you must configure JBoss to do so as well. If you are installing to run the samples you do not have to modify the JBoss port configuration since both the Joss default and the samples use port 8080.

To configure JBoss to use a port other than 8080 modify server.xml under your server configuration. For example, if you are using the default server configuration, server.xml is $JBOSS_HOME/server/default/deploy/jbossweb.sar/server.xml. The quickest way to do this is to search for the default value of 8080 and replace it with the new port number.

If OpenIG accesses an SQL database you must configure JBoss for JNDI. Once you have JBOSS configured you must add the jar for the database, and set up a JNDI data source and a reference to that data source in your web application. The following steps are for the MySQL Connector/J.

Download the MySQL JDBC Driver Connector/J Add it to the JBoss class path by copying it to $JBOSS_HOME/server/default/lib.

Add a JNDI data source for your MySQL server and database in $JBOSS_HOME/server/default/deploy/mysql-ds.xml.

<datasources>
  <local-tx-datasource>
    <jndi-name>jdbc/forgerock<jndi-name>
    <connection-url>jdbc:mysql://localhost:3306/databasename<connection-url>
    <driver-class>com.mysql.jdbc.Driver<driver-class>
    <user-name>admin<user-name>
    <password>11111111<password>
    <min-pool-size>5<min-pool-size>
    <max-pool-size>20<max-pool-size>
    <idle-timeout-minutes>5<idle-timeout-minutes>
    <exception-sorter-class-name>
com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
    <exception-sorter-class-name>
    <valid-connection-checker-class-name>
com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
    <valid-connection-checker-class-name>
  <local-tx-datasource>
<datasources>

Add a resource reference to the data source in $JBOSS_HOME/server/default/deployers/jbossweb.deployer/web.xml.

<resource-ref>
    <description>MySQL Connection<description>
    <res-ref-name>jdbc/forgerock<res-ref-name>
    <res-type>javax.sql.DataSource<res-type>
    <res-auth>Container<res-auth>
<resource-ref>

The figure below illustrates a sample flow with a description of each request from the browser to the back end application. This flow is taken from the Tutorial With WordPress. Try the tutorial yourself to learn how OpenIG works. The Flat-File attribute store contains only one set of credentials. OpenIG makes the assumption this user is logging into the sample application. In a real deployment OpenIG would look up the user credentials using its own session, a SAML2 assertion, or a header from an OpenAM policy agent. Use cases that follow show examples of these types of deployments.

The figure below illustrates OpenIG integrated into an OpenAM deployment. In this deployment OpenIG is running in a container that is protected by an OpenAM policy agent. The agent is configured to forward a header, with the subject (user) of the single sign-on session, to OpenIG. OpenIG then uses the subject as the login credentials, or uses the subject as a reference to look up the login credentials in a database or directory. The HR application is integrated into the SSO deployment without an agent or any modification to the application or its deployment configuration.

The figure below illustrates the OpenIG Federation Gateway providing SAML2 endpoint features acting as Service Provider in an SP initiated single sign-on configuration. In this sample, company myHR is an outsourced provider of HR services and has started seeing increased demand for SAML2 support in their core application. The companies to which they outsource are refusing proprietary means of authentication and demanding the widely accepted SAML2 standard. myHR is not in a position to modify their application to support SAML2 nor do they have the time or money to integrate and deploy all of OpenAM. With OpenIG Federation Gateway, myHR deploys OpenIG in front of their HR application, configures it as a SAML2 endpoint for SP initiated SSO, and configures it to log users into the HR application upon successful verification of the SAML2 assertion from their customers.

The figure below illustrates the Federation Gateway providing SAML2 endpoint features acting as a Service Provider in a IDP initiated single sign-on configuration.

The figure below illustrates the Federation Gateway as a standards based replacement for OpenAM policy agents.

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.

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 in the Reference 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 in the Reference accessible through the Expressions in the Reference ${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}"].

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 in the Reference. Once the values are set in the Exchange, the LoginRequestFilter accesses them in the exact same way.

The figure below illustrates the flow of requests for a user logging into OpenAM and then being logged into WordPress with the user name and password from the OpenAM login session.

OpenAM is installed on http://www.idp.com:8888/openam. WordPress hosted on the ForgeRock demo site at http://demo.forgerock.com:8080/wordpress, populated with a sample user george with password costanza. OpenIG is deployed on an instance of Tomcat protected by an OpenAM J2EE agent. The J2EE agent is configured for cross domain SSO, and to add the user name and replay password headers to the HTTP requests.

This section assumes you are familiar with the components involved.

The Federation service is configured by modifying the OpenIG config.json and Federation specific XML files located in the home directory of the effective user running the web application container housing OpenIG. The home directory of this user is referred to as $HOME_DIR in this document. By default, the Federation service looks in $HOME_DIR/.ForgeRock/OpenIG/ for config.json and $HOME_DIR/.ForgeRock/SAML/ for the Federation XML configuration.

The simplest way to configure the OpenIG Federation Gateway is to use the OpenAM task wizard to generate a Fedlet and then use the Fedlet configuration files in the Gateway configuration directory. If you use the Fedlet configuration files, simply unpack Fedlet.war and copy all the files listed above into $HOME_DIR/.ForgeRock/SAML/. You do not have to modify the files to do basic IDP and SP initiated SSO with OpenIG. Note that the sample Federation Gateway config.json templates uses /saml as the URI so your Fedlet endpoint should be specified as protocol://host.domain:port/saml.

If you do not use the Fedlet wizard, then follow the instructions for the unconfigured Fedlet and then copy the Fedlet configuration files to the $HOME_DIR/.ForgeRock/SAML/ directory. You must also export the metadata from the IDP and copy it to idp.xml in the same directory.

The following sample configuration is from the tutorial on federating WordPress. The sample configuration receives a SAML assertion from OpenAM and then logs the user into WordPress using the user name and password from the assertion.

The following excerpt of the Federation Service JSON is from the OpenIG config.json file. All fields are mandatory except logoutURI. The logoutURI is only necessary if your configuration uses the single logout feature.

{
    "name": "FederationServlet",
    "type": "org.forgerock.openig.saml.FederationServlet",
    "config": {
        "assertionMapping": {
            "userName":"uid",
            "password":"userPassword" 
        },
        "subjectMapping":"subjectName",
        "sessionIndexMapping":"sessionIndex",
        "redirectURI":"/login",
        "logoutURI":"/logout"
        "assertionConsumerEndpoint":"fedletapplication",
        "SPinitiatedSSOEndpoint":"SPInitiatedSSO",
        "singleLogoutEndpoint":"fedletSlo"
   }
}

Application myportal requires a form with userName and password for login. The userName for myportal is the mail attribute at the user's Identity Provider. The password for myportal is the mailPassword at the Identity Provider. The incoming SAML2 assertion sent by the Identity Provider contains the mail and mailPassword attributes. The Federation Service validates the incoming assertion, sets the userName and password in the HttpSession to the values of mail and mailPassword from the assertion, and redirects the user to /myportal/login. The LoginRequest Filter then retrieves the login values from the session and creates the form to log the user into myportal.

{
    "name": "FederationServlet",
    "type": "org.forgerock.openig.saml.FederationServlet",
    "config": {
            "assertionMapping": {
                 "userName":"mail",
                 "password":"mailPassword"
            }
            "redirectURI":"/myportal/login",
            "logoutURI":"/myportal/logout" 
    }
}

{
    "name": "LoginRequest",
    "type": "StaticRequestFilter",
    "config": {
        "method": "POST",
        "uri": "https://10.10.0.5/login",
        "form": {
            "userName": [${exchange.session.userName}],
            "password": [${exchange.session.password}],
        }   
    }   
}

The Identity Provider metadata must be in $HOME_DIR/.ForgeRock/SAML/idp.xml directory. See the documentation for your Identity Provider for instructions on how to get the metadata.

To export Identity Provider metadata from OpenAM, run a command such as the following.

$ ssoadm
 export-entity
 -u amadmin
 -f /tmp/pass
 -y http://www.idp.com:8080/openam
 -m /tmp/idp.xml

Follow the Tutorial With WordPress, and make sure you can login to WordPress before continuing this tutorial.

For this sample and the test URIs, OpenAM is configured on http://www.idp.com:8888/openam. You can of course use any configuration, but be sure to substitute the proper values for the test URLs.

Use the OpenAM Console task wizard to create a Fedlet with the Name gateway and the Destination URL http://demo.forgerock.com:8080/saml. Configure the Attributes Mapping to contain the mail and employeenumber attributes.

Create a user with mail attribute george and employeenumber costanza.

Download the Federation to WordPress Sample Config File and copy it to $HOME/.ForgeRock/OpenIG/config.json, overwriting the config.json from the WordPress tutorial.

Assuming Fedlet.zip from the previous step is found in $HOME/openam/myfedlets/Fedlet.zip extract the Fedlet configuration files using the following commands:

$ cd $HOME/openam/myfedlets
$ unzip Fedlet.zip
$ jar xvf Fedlet.war conf

Create a $HOME/.ForgeRock/SAML/ directory, and copy the Fedlet configuration to the new directory.

$ mkdir $HOME/.ForgeRock/SAML
$ cp conf/* $HOME/.ForgeRock/SAML
$ ls $HOME/.ForgeRock/SAML
FederationConfig.properties    idp-extended.xml        sp-extended.xml
fedlet.cot                     idp.xml                 sp.xm

For IDP initiated SSO click this link

For SP initiated SSO either browse to http://demo.forgerock.com:8080/wordpress/ and click the login link, or click this link

To understand what is happening behind the scenes, take a look at $HOME/.ForgeRock/OpenIG/config.json. The HandlerServlet is no longer the entry point to OpenIG processing. If you look for the servletObject at the end of the file you see the HandlerServlet has been replaced by the DispatchServlet. The DispatchServlet provides an internal routing mechanism based on the incoming URI. The DispatchServlet looks at the incoming URI and dispatches to the FederationServlet when the SAML URI is found, otherwise it dispatches to the HandlerServlet as in the previous sample. This allows the FederationServlet to process the incoming assertion, set the attributes from the assertion in the HTTPSession, which then allows the normal chain of filter processing, through the HandlerServlet, to pick up the credentials and log the user into the target application.

Proxies all requests and captures them in a flat file. Use this template if you need to analyze the traffic for your application. Simply change the baseURI to be that of the target application, restart OpenIG, and login to the application. The entire sequence is logged to the flat file.

{
    "heap": {
        "objects": [
            {
                "name": "HandlerServlet",
                "comment": "Transforms Servlet request to handler request.",
                "type": "HandlerServlet",
                "config": {
                    "handler": "DispatchHandler"
                }
            },
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "condition": "${exchange.request.uri.scheme == 'http'}",
                            "handler": "OutgoingChain",
                            "baseURI": "http://TARGETIP"
                        },
                        {
                            "condition": "${exchange.request.uri.path == '/login'}",
                            "handler": "LoginChain",
                            "baseURI": "https://TARGETIP"
                        },
                        {
                            "handler": "OutgoingChain",
                            "baseURI": "https://TARGETIP"
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": [],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "CaptureFilter"
                    ],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": false,
                    "file": "/tmp/gateway.log"
                }
            },
            {
                "name": "ClientHandler",
                "comment": "Sends all requests to remote servers.",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "servletObject": "HandlerServlet"
}

Logs the user into the target application with hard-coded user name and password. This template intercepts the login page request and replaces it with the login form.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler",
            "baseURI":"http://TARGETIP"
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": "LoginChain",
                }, 
                {                       
                    "handler": "OutgoingChain",
                }, 
            ]   
        }   
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": ["LoginRequest"],
            "handler": "OutgoingChain" 
        }   
    },
    {   
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
            "method": "POST",
            "uri": "https://TARGETIP/login",
            "form": {
                "USER": ["myusername"],
                "PASSWORD": ["mypassword"],
            }   
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log",
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

For applications that expect a cookie from the login page to be sent in the login request form. This templates allows the login page request to go through to the target, intercepts the response, then creates the login form and adds the intercepted cookie to the POST.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler",
            "baseURI":"http://TARGETIP"
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.path == '/eum/login'}",
                    "handler": "LoginChain",
                }, 
                {                       
                    "handler": "OutgoingChain",
                }, 
            ]   
        }   
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": ["SwitchFilter"],
            "handler": "OutgoingChain" 
        }   
    },
    {
        "name": "SwitchFilter",
        "type": "SwitchFilter",
        "config": {
            "onResponse": [
                {
                    "handler": "LoginRequestHandler"
                }
            ]
        }
    },
    {
        "name": "LoginRequestHandler",
        "type": "Chain",
        "config": {
            "filters": ["LoginRequest"],
            "handler": "OutgoingChain" 
        }   
    },
    {   
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
            "method": "POST",
            "uri": "https://TARGETIP/login",
            "form": {
                "USER": ["myusername"],
                "PASSWORD": ["mypassword"],
            }   
            "headers": {
                "cookie": ["${exchange.response.headers['Set-Cookie'][0]}"],
            }   
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log",
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

For applications that return the login page when the user tries to access a page without a valid session. This template shows how to use the ExtractFilter to find the login page on the response and use the CookieFilter to ensure the cookies from the application are replayed on each request. The sample application in this template is OpenAM. If you change the TARGETIP:PORT to be the IP address of OpenAM, the TARGETDN:PORT to be the fully qualified name and port of OpenAM and modify USERNAME and PASSWORD in the LoginRequest you automatically log USERNAME into OpenAM.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "FindLoginPageChain",
            "baseURI":"http://TARGETIP:PORT"
        }
    },
    {
        "name": "FindLoginPageChain",
        "type": "Chain",
        "config": {
            "filters": ["IsLoginPage","FindLoginPage"],
            "handler": "OutgoingChain" 
        }   
    },
    {
        "name": "FindLoginPage",
        "type": "EntityExtractFilter",
        "config": {
            "messageType": "response",
            "target": "${exchange.isLoginPage}",
            "bindings": [
                 {
                     "key": "found",
                     "pattern": "OpenAM\s\(Login\)",
                     "template": "true"
                 }
             ]
          }
    },
    {
        "name": "IsLoginPage",
        "type": "SwitchFilter",
        "config": {
            "onResponse": [
                 {
                    "condition": "${exchange.isLoginPage.found == 'true'}",
                     "handler": "LoginChain"
                 }
             ]
          }
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": ["LoginRequest"],
            "handler": "OutgoingChain"
        }
    },
    {   
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
            "method": "POST",
            "uri": "http://TARGETIP:PORT/openam/UI/Login"
            "form": {
                "IDToken0":[""]
                "IDToken1":["USERNAME"]
                "IDToken2":["PASSWORD"]
                "IDButton":["Log+In"]
                "encoded":["false"]
            },   
            "headers": {
                "host":["TARGETFQDN:PORT"]
            }   
            
        }   
    },
   {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CookieFilter","CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
            {
                "name": "CookieFilter",
                "type": "CookieFilter",
                "config": {
                }
         },

    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": true,
            "file": "/tmp/gateway.log",
        }       
    },
    {
    "name": "LogSink",
    "comment": "Default sink for logging information.",
    "type": "ConsoleLogSink",
    "config": {
        "level": "DEBUG",
    }
}
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

Extracts a hidden value from the login page and includes it in the login form POSTed to the target application.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler",
            "baseURI":"http://TARGETIP"
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": "LoginChain",
                }, 
                {                       
                    "handler": "OutgoingChain",
                }, 
            ]   
        }   
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": ["HiddenValueExtract","LoginRequest"],
            "handler": "OutgoingChain" 
        }   
    },
    {
	"name": "HiddenValueExtract",
	"type": "EntityExtractFilter",
	"config": {
	    "messageType": "response",
	    "target": "${exchange.hiddenValue}",
	    "bindings": [
		{
		    "key": "value",
		    "pattern": "wpLoginToken\"\s.*value=\"(.*)\"",
		    "template": "$1"
		}
	    ]
	}
    },
    {   
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
            "method": "POST",
            "uri": "https://TARGETIP/login",
            "form": {
                "USER": ["myusername"],
                "PASSWORD": ["mypassword"],
                "hiddenValue": ["${exchange.hiddenValue.value}"],
            }   
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log",
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

Proxies traffic to an application listening on ports 80 and 443. The assumption is the application uses HTTPS for authentication and HTTP for the general application features. Assuming the login will all take place on port 443, you will need to add the login filters and handlers to the LoginChain. To get started quickly, modify the baseURI to be the IPAddress of your target application. This should allow you to proxy all traffic to the application. Then add the logic for the LoginChain using the flow from one of the login templates.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler",
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.scheme == 'http'}",
                    "handler": "OutgoingChain",
                    "baseURI":"http://TARGETIP"
                },  
                {                       
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": "LoginChain",
                    "baseURI":"https://TARGETIP"
                }, 
                {                       
                    "handler": "OutgoingChain",
                    "baseURI":"https://TARGETIP"
                }, 
            ]   
        }   
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": [],
            "handler": "OutgoingChain" 
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log",
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

Shows how a single OpenIG configuration can proxy to multiple applications on different IPs and ports. This template is setup to proxy to both the WordPress and MediaWiki hosted samples. OpenIG must be setup to listen on both ports 8080 and 8181. The DispatchHandler is used to route each incoming request to either the WordPress chain or the MediaWiki chain.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler"
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.host == 'demo.forgerock.com'}",
                    "handler": "WordPressLoginChain",
                    "baseURI":"http://109.73.67.52:8080",
                },  
                {                       
                    "condition": "${exchange.request.uri.host == 'demo.forgerock.com'}",
                    "handler": "MediaWikiLoginChain",
                    "baseURI":"http://109.73.67.52:8181"
                }
            ]   
        }   
    },
    {
        "name": "WordPressLoginChain",
        "type": "Chain",
        "config": {
            "filters": [],
            "handler": "OutgoingChain"
        }   
    },
    {
        "name": "MediaWikiLoginChain",
        "type": "Chain",
        "config": {
            "filters": [],
            "handler": "OutgoingChain"
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler"
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log"
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
        }
    }
  ]
},
  "servletObject": "HandlerServlet",
}

Logs the user into the target application using the headers passed down from an OpenAM policy agent. This template assumes the user name and password are passed down by the OpenAM policy agent as headers. If the header passed in contains only a user name or subject and requires a lookup to an external data source, you must add an attribute filter to the chain to retrieve the credentials.

{
  "heap": {
    "objects": [
    {
        "name": "HandlerServlet",
        "comment": "Entry point that transforms Servlet request to handler request.",
        "type": "HandlerServlet",
        "config": {
            "handler": "DispatchHandler",
            "baseURI":"http://TARGETIP"
        }
    },
    {       
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
            "bindings": [   
                {                       
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": "LoginChain",
                }, 
                {                       
                    "handler": "OutgoingChain",
                }, 
            ]   
        }   
    },
    {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
            "filters": ["LoginRequest"],
            "handler": "OutgoingChain" 
        }   
    },
    {   
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
            "method": "POST",
            "uri": "https://TARGETIP/login",
            "form": {
                "USER": ["${exchange.request.headers['username'][0]}"],
                "PASSWORD": ["${exchange.request.headers['password'][0]}"],
            }   
        }   
    },
    {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
            "filters": ["CaptureFilter"],
            "handler": "ClientHandler" 
        }   
    },
    {   
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
            "captureEntity": false,
            "file": "/tmp/gateway.log",
        }       
    },
    {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {
            }
        }
    ]
  },
  "servletObject": "HandlerServlet",
}

A sample template used to log a user into Microsoft Online Outlook Web Access. This template shows how you would use the Gateway and the OpenAM password capture feature to integrate with OWA. You can follow the Tutorial On Password Capture & Replay tutorial and substitute this template.

{
    "heap": {
        "objects": [
            {
                "name": "LogSink",
                "comment": "Default sink for logging information.",
                "type": "ConsoleLogSink",
                "config": {
                    "level": "DEBUG",
                }
            },
            {
                "name": "HandlerServlet",
                "type": "HandlerServlet",
                "config": {
                    "handler": "DispatchHandler",
                    "baseURI":"https://65.55.171.158"
                }
            },
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "condition": "${exchange.request.uri.path == '/owa/auth/logon.aspx'}",
                            "handler": "LoginChain",
                        },
                        {
                            "handler": "OutgoingChain",
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": ["CryptoHeaderFilter","LoginRequest"],
                    "handler": "OutgoingChain"
                }
            },
            {   
                "name": "CryptoHeaderFilter",
                "type": "CryptoHeaderFilter",
                "config": {
                    "messageType":"REQUEST",
                    "operation":"DECRYPT",
                    "algorithm":"DES/ECB/NoPadding",
                    "key":"DESKEY",
                    "keyType":"DES",
                    "charSet":"utf-8",
                    "headers": ["password"],
                },
            },
            {  
                "name": "LoginRequest",
                "type": "StaticRequestFilter",
                "config": {
                    "method": "POST",
                    "uri": "https://65.55.171.158/owa/auth/owaauth.dll",
                    "headers" : {
                        "Host": ["red001.mail.microsoftonline.com"],
                        "Content-Type": ["Content-Type:application/x-www-form-urlencoded"],
                    }
                    "form": {
                        "destination": ["https://red001.mail.microsoftonline.com/owa/"],
                        "forcedownlevel": ["0"],
                        "trusted": ["0"],
                        "username": ["${exchange.request.headers['username'][0]}"],
                        "password": ["${exchange.request.headers['password'][0]}"],
                        "isUtf8": ["1"],
                    }
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": ["HeaderFilter","CaptureFilter"],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "HeaderFilter",
                "type": "HeaderFilter",
                "config": {
                    "messageType":"REQUEST",
                    "remove": ["password","username"],
                 }
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": false,
                    "file": "/tmp/gateway.log",
                }
            },
            {
                "name": "ClientHandler",
                "type": "ClientHandler",
                "config": {
                }
            },
        ]
    },
    "servletObject": "HandlerServlet",
}

The two primary extension points are the interfaces: Filter (for processing a request and/or response en route) and Handler (for generating responses from requests). These interfaces are similar to the Java Enterprise Edition Filter and Servlet interfaces, with some differences in the semantics of messages. While you can simply implement these interfaces, there are also included convenience classes: GenericFilter and GenericHandler that you can use if you intend to make your extensions configurable through the OpenIG configuration resource.

OpenIG also allows standard Java Enterprise Edition servlets and servlet filters to be embedded in the gateway, with initialization parameters supplied through through the OpenIG configuration resource.

The Filter interface exposes a filter method, which takes an Exchange object and the Chain of remaining filters and handler to dispatch to. Initially, exchange.request contains the request to be filtered. To pass the request to the next filter or handler in the chain, the filter calls chain.handle(exchange). After this call, exchange.response contains the response that can be filtered.

A filter might elect not to pass the request to the next filter or handler, and instead handle the request itself. It can achieve this by merely avoiding a call to chain.handle(exchange) and creating its own response object in the exchange. The filter is also at liberty to replace a response with another of its own. A filter can exist in more than one chain, therefore should make no assumptions or correlations using the chain it is supplied. The only valid use of a chain by a filter is to call its handle method to dispatch the exchange to the rest of the chain.

The Handler interface exposes a handle method, which takes an Exchange object. It processes the request in exchange.request and produces a response in exchange.response. A handler can elect to dispatch the exchange to another handler or chain.

Objects are added to the heap and supplied with configuration artifacts at initialization time. To be integrated with the configuration, a class must have an accompanying implementation of the Heaplet interface. The easiest and most common way of exposing the heaplet is to extend the NestedHeaplet class in a nested class in the class you want to create and initialize and implementing its create method.

Within the create method, you can access the object's configuration through the config field.

A servlet or servlet filter can be added as a heap object by including it in the classpath, and identifying it in the OpenIG heap configuration as an javax.servlet.http.HttpServlet in the Reference or javax.servlet.Filter in the Reference type, providing any appropriate initialization parameters. A servlet can be dispatched directly by the gateway servlet, and servlets and filters can be flexibly dispatched to through a DispatchServlet.

The following sample filter sets an arbitrary header in the incoming request and outgoing response.

package com.example.filter;

// Java Standard Edition
import java.io.IOException;

// OpenIG Core Library
import org.forgerock.openig.filter.Chain;
import org.forgerock.openig.filter.GenericFilter;
import org.forgerock.openig.handler.HandlerException;
import org.forgerock.openig.heap.HeapException;
import org.forgerock.openig.heap.NestedHeaplet;
import org.forgerock.openig.http.Exchange;
import org.forgerock.openig.model.ModelException;

public class HelloWorldFilter extends GenericFilter {

    public String name;
    public String value;

    @Override
    public void filter(Exchange exchange, Chain chain)
            throws HandlerException, IOException {
        exchange.request.headers.put(name, value); // set header in request
        chain.handle(exchange); // pass to remaining filters & handler in chain
        exchange.response.headers.put(name, value); // set header in response
    }

    public static class Heaplet extends NestedHeaplet {

        @Override
        public Object create() throws HeapException, ModelException {
            HelloWorldFilter filter = new HelloWorldFilter();
            filter.name = config.get("name").required().asString(); // required
            filter.value = config.get("value").required().asString(); // req'd
            return filter;
        }
    }
}

The corresponding heap object configuration is as follows.

{
     "name": "HelloWorldFilter",
     "type": "com.example.filter.HelloWorldFilter",
     "config": {
         "name": "X-Hello",
         "value": "World" 
     }
}

HTTP ERROR 500
org.forgerock.openig.model.NodeException:
 ['file:/Users/george/.ForgeRock/OpenIG/config.json'].heap.objects[2]
  .config.filterObjects[0]: object not found in heap
at org.forgerock.openig.heaplet.HeapUtil.getRequiredObject(HeapUtil.java:54)
at org.forgerock.openig.filter.Chain$Heaplet.create(Chain.java:49)

You have a filter specified in the filterObjects list in the Chain object that is not in config.json. Make sure you have added an entry for the Filter and have correctly spelled its name in the filterObjects list.

HTTP ERROR 500
Problem accessing /. Reason:

 could not find local configuration file at
 /var/root/.ForgeRock/OpenIG/config.json or bootstrap file at
 /var/root/.ForgeRock/OpenIG/_private_var_folders_...webinf.json

OpenIG could not find its configuration file in the home directory of the user running the container where OpenIG is deployed, in this case /var/root/.ForgeRock/OpenIG/config.json. As you can see from the error message, OpenIG looks in a secondary location determined at runtime by the container. The secondary location is only necessary if you are running more than one OpenIG on a single host and your instances do not share a single configuration.

HTTP ERROR 500
Problem accessing /. Reason:

Unexpected character (x) at position 1103

This error usually means a missing double quote or a missing bracket in the configuration file. Use a JSON editor or JSON validation tool such as JSONLint to make sure your JSON is valid.

Ensure the flat file is readable by the user running the container for OpenIG. Values are all characters, including space and tabs, between the separator, so make sure the values are not padded with spaces.

HTTP ERROR 500

Problem accessing /myURL . Reason:

java.lang.String cannot be cast to java.util.List
Caused by:
java.lang.ClassCastException: java.lang.String cannot be cast to java.util.List
at org.forgerock.openig.filter.LoggingFilter.writeHeaders(LoggingFilter.java:132
at org.forgerock.openig.filter.LoggingFilter.logResponse(LoggingFilter.java:119)
at org.forgerock.openig.filter.LoggingFilter.filter(LoggingFilter.java:86)
at org.forgerock.openig.filter.Chain.handle(Chain.java:54)

This error is typically encountered when using the AssignmentFilter in the Reference and setting a string value for one of the Headers. All headers are stored in Lists so the header must be addressed with a subscript. For example, if you try to set exchange.request.headers['Location'] for a redirect in the response object, you should instead set exchange.request.headers['Location'][0]. A header without a subscript leads to the error above.

You must define an entity for the response. For example:

{
    "name": "AccessDeniedHandler",
    "type": "org.forgerock.openig.handler.StaticResponseHandler",
    "config": {
        "status": 403,
        "reason": "Forbidden",
        "entity": "<html><h2>User does not have permission<h2>html>"
    }
}

If you are proxying to more than one application in multiple DNS domains, you must make sure your container is enabled for domain cookies. See the chapter on Configuring Deployment Containers for details on your specific container.