Getting Started

In this chapter, you will learn to:

Quickly set up OpenIG on Jetty
Configure OpenIG to protect a sample application
Prepare OpenIG so that you can follow all subsequent tutorials in the documentation

This chapter allows you to quickly see how OpenIG works, and provides hands-on experience with a few key features. For more general installation and configuration instructions, start with Installation in Detail.

Before You Begin

Make sure you have a supported Java Development Kit installed.

This release of OpenIG requires Java Development Kit 8, 11, 17 or 21 LTS version. Open Identity Platform Community recommends the most recent update to ensure you have the latest security fixes.

Install OpenIG

You install OpenIG in the root context of a web application container. In this chapter, you use Jetty server as the web application container.

To perform initial installation, follow these steps:

Download and unzip a supported version of Jetty server.

OpenIG runs in the following web application containers:
- Apache Tomcat 8 or 9
- Jetty 8, 9 or 10
Download the OpenIG.war file.
Deploy OpenIG in the root context.

Copy the OpenIG .war file as root.war to the /path/to/jetty/webapps/:
```
$ cp OpenIG-5.3.0.war /path/to/jetty/webapps/root.war
```
Jetty automatically deploys OpenIG in the root context on startup.

Start Jetty in the background:

$ /path/to/jetty/bin/jetty.sh start

Or start Jetty in the foreground:

$ cd /path/to/jetty/
$ java -jar start.jar

Verify that you can see the OpenIG welcome page at http://localhost:8080.

When you start OpenIG without a configuration, requests to OpenIG default to a welcome page with a link to the documentation.
Stop Jetty in the background:
```
$ /path/to/jetty/bin/jetty.sh stop
```
Or stop Jetty in the foreground by entering Ctrl+C in the terminal where Jetty is running.

Install an Application to Protect

Now that OpenIG is installed, set up a sample application to protect.

Follow these steps:

Download and run the minimal HTTP server .jar to use as the application to protect:

$ java -jar openig-doc-5.3.0-jar-with-dependencies.jar
Preparing to listen for HTTP on port 8081.
Preparing to listen for HTTPS on port 8444.
The server will use a self-signed certificate not known to browsers.
When using HTTPS with curl for example, try --insecure.
Using OpenAM URL: http://openam.example.com:8088/openam/oauth2.
Starting server...
Sep 09, 2015 9:52:56 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8444]
Sep 09, 2015 9:52:56 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8081]
Sep 09, 2015 9:52:56 AM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
Press Ctrl+C to stop the server.

By default, this server listens for HTTP on port 8081, and for HTTPS on port 8444. If one or both of those ports are not free, specify other ports:

$ java -jar openig-doc-5.3.0-jar-with-dependencies.jar 8888 8889
Preparing to listen for HTTP on port 8888.
Preparing to listen for HTTPS on port 8889.
The server will use a self-signed certificate not known to browsers.
When using HTTPS with curl for example, try --insecure.
Using OpenAM URL: http://openam.example.com:8088/openam/oauth2.
Starting server...
Sep 09, 2015 9:55:57 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8889]
Sep 09, 2015 9:55:57 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8888]
Sep 09, 2015 9:55:57 AM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
Press Ctrl+C to stop the server.

If you change the port numbers when starting the server, also account for the differences when using the examples.

Now access the minimal HTTP server through a browser on the appropriate port, such as http://localhost:8081.

Log in with username demo, password changeit. You should see a page that includes the username, demo, and some information about your browser request.

Configure OpenIG

Now that you have installed both OpenIG and a sample application to protect, it is time to configure OpenIG.

Follow these steps to configure OpenIG to proxy traffic to the sample application:

Prepare the OpenIG configuration.

Add the following base configuration file as $HOME/.openig/config/config.json. By default, OpenIG looks for config.json in the $HOME/.openig/config directory:
```
{
  "handler": {
    "type": "Router",
    "audit": "global",
    "baseURI": "http://app.example.com:8081",
    "capture": "all"
  },
  "heap": [
    {
      "name": "LogSink",
      "type": "ConsoleLogSink",
      "config": {
        "level": "DEBUG"
      }
    },
    {
      "name": "JwtSession",
      "type": "JwtSession"
    },
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ]
}
```
```
$ mkdir -p $HOME/.openig/config
$ vi $HOME/.openig/config/config.json
```
On Windows, the configuration files belong in %appdata%\OpenIG\config. To locate the %appdata% folder for your version of Windows, open Windows Explorer, type %appdata% as the file path, and press Enter. You must create the %appdata%\OpenIG\config folder, and then copy the configuration files.

If you adapt this base configuration for production use, make sure to adjust the log level, and to deactivate the CaptureDecorator that generates several log message lines for each request and response. Also consider editing the router based on recommendations described in Locking Down Route Configurations.
Add the following default route configuration file as $HOME/.openig/config/routes/99-default.json. By default, the Router defined in the base configuration file looks for routes in the $HOME/.openig/config/routes directory:
```
{
  "handler": "ClientHandler"
}
```
```
$ mkdir $HOME/.openig/config/routes
$ vi $HOME/.openig/config/routes/99-default.json
```
On Windows, the file name should be %appdata%\OpenIG\config\routes\99-default.json.

Start Jetty in the background:

$ /path/to/jetty/bin/jetty.sh start

Or start Jetty in the foreground:

$ cd /path/to/jetty/
$ java -jar start.jar

Configure the Network

So far you have deployed OpenIG in the root context of Jetty on port 8080. Since OpenIG is a reverse proxy you must make sure that all traffic from your browser to the protected application goes through OpenIG. In other words, the network must be configured so that the browser goes to OpenIG instead of going directly to the protected application.

If you followed the installation steps, you are running both OpenIG and the minimal HTTP server on the same host as your browser (probably your laptop or desktop). Keep in mind that network configuration is an important deployment step. To encourage you to keep this in mind, the sample configuration for this chapter expects the minimal HTTP server to be running on app.example.com, rather than localhost.

The quickest way to configure the network locally is to add an entry to your /etc/hosts file on UNIX systems or %SystemRoot%\system32\drivers\etc\hosts on Windows. See the Wikipedia entry, Hosts (file), for more information on host files. If you are indeed running all servers in this chapter on the same host, add the following entry to the hosts file:

127.0.0.1    openig.example.com app.example.com

If you are running the browser and OpenIG on separate hosts, add the IP address of the host running OpenIG to the hosts file on the system running the browser, where the host name matches that of protected application. For example, if OpenIG is running on a host with IP address 192.168.0.15:

192.168.0.15    openig.example.com app.example.com

If OpenIG is on a different host from the protected application, also make sure that the host name of the protected application resolves correctly for requests from OpenIG to the application.

Restart Jetty to take the configuration changes into account.

Some browsers cache IP address resolutions, even after clearing all browsing data. Restart the browser after changing the IP addresses of named hosts.

The simplest way to make sure you have configured your DNS or host settings properly for remote systems is to stop OpenIG and then to make sure you cannot reach the target application with the host name and port number of OpenIG. If you can still reach it, double check your host settings.

Also make sure name resolution is configured to check host files before DNS. This configuration can be found in /etc/nsswitch.conf for most UNIX systems. Make sure files is listed before dns.

Try the Installation

http://openig.example.com:8080/ should take you to the home page of the minimal HTTP server.

What just happened?

When your browser goes to http://openig.example.com:8080/, it is actually connecting to OpenIG deployed in Jetty. OpenIG proxies all traffic it receives to the protected application at http://app.example.com:8081/, and returns responses from the application to your browser. It does this based on the configuration that you set up.

Consider the base configuration file first, config.json. The base configuration file specifies a router handler named Router. OpenIG calls this handler when it receives an incoming request. In addition, it uses the ConsoleLogSink to log debug messages to the console. Alternatively, you can use a FileLogSink or Slf4jLogSink as described in Logging Framework in the Configuration Reference.

The baseURI decoration in turn changes the request URI to point the request to the sample application to protect. The Router captures the request on the way in, and captures the response on the way out.

The Router routes processing to separate route configurations.

For now the only route available is the the default route you added, 99-default.json. The default route calls a ClientHandler with the default configuration. This ClientHandler simply proxies the request to and the response from the sample application to protect without changing either the request or the response. Therefore, the browser request is sent unchanged to the sample application and the response from the sample application is returned unchanged to your browser. Now change the OpenIG configuration to log you in automatically with hard-coded credentials:

Add a route to automatically log you in as username demo, password changeit.

Add the following route configuration file as $HOME/.openig/config/routes/01-static.json:

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "StaticRequestFilter",
          "config": {
            "method": "POST",
            "uri": "http://app.example.com:8081",
            "form": {
              "username": [
                "demo"
              ],
              "password": [
                "changeit"
              ]
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.path, '^/static')}"
}

On Windows, the file name should be %appdata%\OpenIG\config\routes\01-static.json.

Access the new route, http://openig.example.com:8080/static.

This time, OpenIG logs you in automatically.

Also view the information logged about requests and responses, which shows up in the Jetty log.

What’s happening behind the scenes?

With the original configuration, OpenIG does not change requests or responses, but only proxies requests and responses, and captures request and response information.

After you change the configuration, OpenIG continues to capture request and response data. When your request does not go to the default route, but instead goes to /static, then the condition on the new route you added matches the request. OpenIG therefore uses the new route you added.

Using the route configuration in 01-static.json, OpenIG replaces your browser’s original HTTP GET request with an HTTP POST login request containing credentials to authenticate. As a result, instead of the home page with a login form, OpenIG logs you in directly, and the application responds with the page you see after logging in. OpenIG then returns this response to your browser.

The browser host makes a DNS request for the IP address of the HTTP server host, app.example.com.
DNS responds with the address for OpenIG.
Browser sends a request to the HTTP server.
OpenIG replaces the request with an HTTP POST request, including the login form with hard-coded credentials.
HTTP server validates the credentials, and responds with the profile page.
OpenIG passes the response back to the browser.