Chapter 2. How OpenIG Works
Prev |  | Next

# Chapter 2. How OpenIG Works

This chapter provides a detailed look at OpenIG's components and how they work together.

## 2.1. How It Works In A Nutshell

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.

## 2.2. How It Works In Detail

The following modules make up OpenIG.

### 2.2.1. OpenIG Core (Reverse Proxy)

OpenIG core is a standard Java EE servlet implementation of a reverse proxy. The main function of OpenIG core is to act as a reverse proxy to the target application. When deployed in its base configuration, OpenIG can be used as a pure reverse proxy. The power of the OpenIG core comes in its ability to search, transform, and process HTTP traffic to and from the target application. This enables OpenIG to recognize login pages, submit login forms, transform or filter content, and even function as a Federation endpoint for the application. All these features are possible without making any changes to the application's deployment container or the application itself.

### 2.2.2. Exchange

The Exchange is a wrapper around the HTTP request and response objects that pass through OpenIG. Every request or response being processed in OpenIG can be accessed or modified through the Exchange object. In addition, arbitrary data can be set in the Exchange to facilitate the passing of data and state between filters and handlers.

### 2.2.3. Dispatcher

The Dispatcher may be thought of as the internal router of OpenIG. Every request that comes into OpenIG is analyzed and forwarded on to the configured processing chain of filters and handlers. A request may be forwarded based on the target host, URL, URL parameters, headers, cookies, or any other component of the request.

### 2.2.4. Chain

A Chain is a combination of one or more Filters and a handler that process an incoming request from the Dispatcher. For example, the Dispatcher can process an incoming request with a URL parameter of `action=login` and forward the request to the Login Chain. The Login Chain executes a list of Filters and then calls a Handler. The Handler sends the request on to the target application or to another Chain for further processing.

### 2.2.5. Handlers

The final processing of every Chain ends in a call to a Handler. A Handler can simply call another Chain or it can send the request on to the target application. The following Handlers are shipped with OpenIG:

- ClientHandler: Sends the final request to the target application.

- StaticResponseHandler: Used to send a response, such as a redirect, to a client during request processing.

- SequenceHandler: Links together multiple handlers or chains during request processing.

### 2.2.6. Filters

Filters are responsible for processing HTTP requests in OpenIG. Filters can be chained together to act on the input stream coming from the browser, or the output stream returned back from the target application. A filter can do something as simple as logging the input and output stream or something more complex, such as processing login pages, fetching user attributes, or transforming content. There are multiple Filters shipped with OpenIG that can be combined in chains to provide very extensible request and response processing features. Custom filters can also be written using the Java SPIs. The following is a list of Filters shipped with OpenIG:

- CookieFilter: The default behavior of OpenIG is to accept and forward all cookies. Since this is not always the desirable behavior, the CookieFilter, when configured, allows you to suppress, manage, and relay cookies.

- CaptureFilter: Captures the HTTP requests being processed by OpenIG. Capture can be used for audit purposes and may also be very useful when analyzing an application or troubleshooting a misbehaving OpenIG. Logs are written to a flat file on the OpenIG host.

- HeaderFilter: The default behavior of OpenIG is to accept and forward all headers. The HeaderFilter can be configured to add additional headers or remove headers on both the HTTP request and the response. It can also be configured to parse and set header values in OpenIG context to allow filters access to the header attributes. This feature is used most commonly when OpenIG is integrated with OpenAM and being fronted by a policy agent.

- AssignmentFilter: Sets values in the HTTP request and response.

- StaticRequestFilter: Creates and sends HTTP GET and POST requests. The request can be formed using parameters from previous processing or statically configured values.

- EntityExtractFilter: Searches for specific content with the body of the requests. For example, it can be used to extract hidden form parameters in a login page, which are needed in the login request.

- ExceptionFilter: Sends users to configured URLs when errors or exceptions occur during request processing or user interactions.

- SwitchFilter: Conditionally diverts the exchange to another handler.

- HttpBasicAuthFilter: Performs HTTP basic authentication to the target application per RFC 2617.

- FileAttributesFilter: Looks up attributes in a flat file with the specified key. The attributes are added to the exchange to be used by subsequent filters or handlers.

- SqlAttributesFilter: Executes an SQL prepared statement with configured parameters. The result is added to the exchange to be used by subsequent filters or handlers.

### 2.2.7. Configuration

The configuration of OpenIG was designed to be very modular and self-contained. Each module within OpenIG stores its configuration in JSON representation, which is stored in flat files. The features of OpenIG can be configured by directly manipulating the JSON flat files.

### 2.2.8. Heaplets

Every OpenIG module which has JSON configuration also has a Heaplet associated with it. Each module's Heaplet is responsible for reading the JSON configuration and creating that module's configuration in OpenIG's runtime heap. Each module can then read its configuration from the heap as well as make shared configuration information available to other modules.

### 2.2.9. Services

The Services model was designed to allow the integration of value added features, such as Federation, without requiring them to be tightly bound to the OpenIG implementation. SAML2 is the add on service shipping with OpenIG today.

### 2.2.10. Federation Service (Federation Gateway)

When the Federation Service is enabled, OpenIG acts as the Service Provider in a Circle of Trust with a SAML2 compliant Identity Provider. The Federation service supports both IDP and SP initiated SAML2 profiles. The Federation Gateway may be a Service Provider in the classic Federation use case where the IDP and SP are different companies or domains. The OpenIG SP can also be a standards based alternative to an OpenAM policy agent for internal enterprise applications that want to move away from installing agents with web and web application servers.

Prev |  | Next
Chapter 1. Solutions Overview | Home | Chapter 3. Getting Started