Introduction to OpenIG (Part 2: First contact…)

What do I need to start ?

First, you need to install OpenIG in the root context of a web container (Tomcat used for the example):

  1. Download OpenIG
  2. Grab a fresh Apache Tomcat instance (Tomcat 7.0 or 8.0) and unzip it
  3. Remove all war files from the webapps/ directory
  4. Move OpenIG-3.0.0.war to that directory and rename it to ROOT.war (OpenIG needs to be installed in the root context: /)
  5. Start Tomcat (bin/ run from within the tomcat directory).

    Don't worry if you see some warnings about Offending classes during startup: that's because OpenIG web-app provides its own EL implementation (useful when the web container doesn't provide one). This pollutes the startup logs but does not prevent OpenIG to run properly.

If you're curious, you can go to http://localhost:8080 (or whatever port number you're using), you should see the OpenIG's welcome page (admire the ASCII art).

OpenIG 3.0.0 - Welcome Page

If you don't see anything, or an error, make sure that you don't have a previous OpenIG configuration file in $HOME/.openig/config/config.json ($APP_DATAForgeRockOpenIGconfigconfig.json for our windows users).

You might wonder why OpenIG requires to be installed in the root context. The reason is simple: most of the time, when you want to access a web site, you just wanna type a domain name in your browser navbar (like

That gives you a very easy to use and to remember entry point URL as well as the flexibility of mapping incoming requests to any internal URL (really routing requests in fact).

Your first configuration

What would you think of an OpenIG Hello World example? After all that reading, I'm sure you'll be happy to get your hands dirty :)

So, finally some code (let's face it; it's JSON configuration really).

Place that configuration file inside the $HOME/.openig/config/routes/ directory. It will be auto-(re)loaded by OpenIG.

It's quite self-descriptive: if the incoming request's path matches ^/hello (starts with /hello), it is dispatched to this route (a JSON file placed in the routes/ directory is called a route). This route is configured with a single StaticResponseHandler that simply return a Hello World message (we'll see what a Handler is in an upcoming post) to the user-agent.

OpenIG Hello World

At first look, that doesn't seem very fancy, but you've been exposed to multiple core concepts of OpenIG (they'll be covered in more details in subsequent posts):

  • The OpenIG configuration file format (expressed as JSON)
  • The expression language (${} for expressing conditions based the value of some properties)
  • The Exchange HTTP model (exchange.request.uri.path in the expression)
  • The route concept (a simple way to isolate processing chains in different files and to ease setup with auto-(re)loading)

In the next post, we'll have a look at the concepts providing the backbone of OpenIG (Exchange, Handler and Filter).

See you soon.

Introduction to OpenIG (Part 1: Use cases)


You've probably landed here because you want to know something about OpenIG. This is the right place to be :)

This post is the first one of a serie of OpenIG-related articles that would gives you hand-on samples with explanations.

Identity Gateway

OpenIG stands for Open Identity Gateway, it is an identity/security specialized reverse proxy. That means that it control the access to a set of internal services.

By controling the access, I mean that it intercepts all the requests coming to the protected service (be it a RESTful API or a web application) and process them before (and after) forwarding them to the server.

Different kind of processing can be handled:

  • Request authorization
  • Capture and password replay
  • Message logging
  • Transformation

Commons use cases

Ok, that was a bit of a generalist description (transformation is intentionally vague :) ). Having some real-life use cases will help to have a better feeling/understanding of what OpenIG is capable of.

SAML Application Federation

In this use case, OpenIG acts as a SAML-enabled facade to a somehow legacy application that cannot be adapted to support SAML federation. The Identity Provider (could be OpenAM) will consider OpenIG as a standard SAML Service Provider.

SAML CoT with OpenIG used as a facade to a legacy application

Application Authentication

Here, OpenIG acts as an OpenID Connect Relying Party (OIDC terminology for client) and requires the user to authenticate to an OpenID Connect Provider (the identity provider) before giving him/her access to the protected application.

Authenticated user's profile information (such as name, email, address, picture, ...) are available to enrich the user experience, or make further verifications.

OpenID Connect - OpenIG Relying Party

RESTful Services Protection

This simple case shows OpenIG verifying request to a proxified RESTful API: each request must contains a valid OAuth 2.0 Bearer Token to be allowed to reach the service API. In this case, OpenIG acts as an OAuth 2.0 Resource Server.

Very useful if you have an old-fashioned REST API that you cannot easily update to deal with OAuth 2.0 tokens.

OAuth 2.0 - OpenIG ResourceServer

Not enough ?

Well, we're done with the 'marketing' stuff. In the next post, we will start to play with OpenIG.

See you soon!

First round is mine!


... this is my very first blog post for years !!!

I'm usually more a tech reader than a tech writer, but I feel that it is time to start sharing on technology.

The easier for me to start with is using the open source project I'm working on as a source of inspiration :)

I want to begin with some introduction on OpenIG: what is it, picturing some use cases and mostly focusing on tips and tricks.

I hope you'll appreciate.