Quick install
Use this guide to get a quick, hands-on look at what IG software can do. You will download, install, and use IG on your local computer. For more installation options, refer to Install.
This guide assumes familiarity with the following topics:
-
HTTP, including how clients and servers exchange messages, and the role that a reverse proxy (gateway) plays
-
JSON, the format for IG configuration files
-
Managing services on operating systems and application servers
-
Configuring network connections on operating systems
Download IG
The .zip file unpacks into a /path/to/identity-gateway
directory with the following content:
-
bin
: Start and stop executables -
classes
: Initially empty; used to install patches from ForgeRock support -
docker/Dockerfile
: Dockerfile and README to build an IG Docker image -
legal-notices
: Licenses and copyrights -
lib
: IG and third-party libraries
-
Create a local installation directory for IG. The examples in this section use
/path/to
.The installation directory should be a new, empty directory. Installing IG into an existing installation directory can cause errors. -
Download
IG-2023.11.0.zip
from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:$ cp IG-2023.11.0.zip /path/to/IG-2023.11.0.zip
-
Unzip the file:
$ unzip IG-2023.11.0.zip
The directory
/path/to/identity-gateway
is created.
Start and stop IG
Start IG with default settings
Use the following step to start the instance of IG, specifying the configuration directory where IG looks for configuration files.
-
Start IG:
-
Linux
-
Windows
$ /path/to/identity-gateway-2023.11.0/bin/start.sh ... ... started in 1234ms on ports : [8080 8443]
C:\path\to\identity-gateway-2023.11.0\bin\start.bat
By default, IG configuration files are located under
$HOME/.openig
(on Windows%appdata%\OpenIG
). For information about how to use a different location, refer to Configuration location. -
-
Check that IG is running in one of the following ways:
-
Ping IG at
http://ig.example.com:8080/openig/ping
, and make sure anHTTP 200
is returned. -
Access the IG welcome page at
http://ig.example.com:8080
. -
When IG is running in development mode, display the product version and build information at
http://ig.example.com:8080/openig/api/info
.
-
Start IG with custom settings
By default, IG runs on HTTP, on port 8080
, from the instance
directory $HOME/.openig
.
To start IG with custom settings, add the configuration file
admin.json
with the following properties, and restart IG:
-
vertx
: Finely tune Vert.x instances. -
connectors
: Customize server port, TLS, and Vert.x-specific configurations. Eachconnectors
object represents the configuration of an individual port. -
prefix
: Set the instance directory, and therefore, the base of the route for administration requests.
The following example starts IG on non-default ports, and configures Vert.x-specific options for the connection on port 9091:
{
"connectors": [{
"port": 9090
},
{
"port": 9091,
"vertx": {
"maxWebSocketFrameSize": 128000,
"maxWebSocketMessageSize": 256000,
"compressionLevel": 4
}
}]
}
For more information, refer to AdminHttpApplication (admin.json).
Allow startup when there is an existing PID file
By default, if there is an existing PID file during startup the startup fails. Use one of the following ways to allow startup when there is an existing PID file. IG then removes the existing PID file and creates a new one during startup.
-
Add the following configuration to
admin.json
and restart IG:{ "pidFileMode": "override" }
-
Define an environment variable for the configuration token
ig.pid.file.mode
, and then start IG in the same terminal:-
Linux
-
Windows
$ IG_PID_FILE_MODE=override /path/to/identity-gateway/bin/start.sh
C:\IG_PID_FILE_MODE=override C:\path\to\identity-gateway-2023.11.0\bin\start.bat %appdata%\OpenIG
-
-
Define a system property for the configuration token
ig.pid.file.mode
when you start IG:-
Linux
-
Windows
$HOME/.openig/env.sh
%appdata%\OpenIG\env.sh
export "IG_OPTS=-Dig.pid.file.mode=override"
-
Stop IG
Use the stop.sh
script to stop an instance of IG, specifying the
instance directory as an argument. If the instance directory is not specified,
IG uses the default instance directory:
-
Linux
-
Windows
$ /path/to/identity-gateway-2023.11.0/bin/stop.sh $HOME/.openig
C:\path\to\identity-gateway-2023.11.0\bin\stop.bat %appdata%\OpenIG
Use the sample application
ForgeRock provides a mockup web application for testing IG configurations. The sample application is used in the examples in this guide and the Gateway guide.
Prepare the network
Configure the network to include hosts for IG, AM, and the sample application. For more information about host files, refer to the Wikipedia entry, Hosts (file).
-
Add the following entry to your host file:
-
Linux
-
Windows
/etc/hosts
%SystemRoot%\system32\drivers\etc\hosts
127.0.0.1 localhost ig.example.com app.example.com am.example.com
-
Download the sample application
-
Download
IG-sample-application-2023.11.0.jar
, from the ForgeRock BackStage download site.
Start the sample application
-
Start the sample application:
$ java -jar IG-sample-application-2023.11.0.jar [...] [INFO ] All 8 verticles started on ports : [8081, 8444] [...] [INFO ] Using session timeout of: 60s [...] [INFO ] Using AM base for OpenID Discovery URL: http://am.example.com:8088/openam/oauth2 [...] [INFO ] 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 IG-sample-application-2023.11.0.jar 8888 8889
-
Check that the sample application is running in one of the following ways:
-
Go to http://localhost:8081/home to access the home page of the sample application. Information about the browser request is displayed.
-
Go to http://localhost:8081/login to access the login page of the sample application, and then log in with username
demo
and passwordCh4ng31t
. The username and some information about the browser request is displayed.
-
Stop the sample application
-
In the terminal where the sample application is running, select CTRL+C to stop the app.
Serve static resources
When the sample application is used with IG in examples, it must serve static resources, such as the .css. Similarly, browser requests often serve resources that don’t need protection, such as icons and .gif files.
Add the following route to IG to serve the sample application .css and other static resources:
-
Linux
-
Windows
$HOME/.openig/config/routes/00-static-resources.json
%appdata%\OpenIG\config\routes\00-static-resources.json
{
"name" : "00-static-resources",
"baseURI" : "http://app.example.com:8081",
"condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}",
"handler": "ReverseProxyHandler"
}
Configuration options
To view the command-line options for the sample application, start it with the
-h
option:
$ java -jar IG-sample-application-2023.11.0.jar -h
Usage: <main class> [options]
Options:
--http
The HTTP port number.
Default: 8081
--https
The HTTPS port number.
Default: 8444
--session
The session timeout in seconds.
Default: 60
--am-discovery-url
The AM URL base for OpenID Provider Configuration.
Default: http://am.example.com:8088/openam/oauth2
-h, --help
Default: false
Protect an application with IG
This section gives a simple example of how to use IG to protect an application. For many more examples of how to protect applications with IG, refer to the Gateway guide.
In the following example, a browser requests access to the sample application, and IG intercepts the request to log the user into the application. The following image shows the flow of data in the example:
-
The browser sends an HTTP GET request to the HTTP server on
ig.example.com
. -
IG replaces the HTTP GET request with an HTTP POST login request containing credentials to authenticate.
-
The sample application validates the credentials, and returns the page for the user
demo
.If IG did not provide the credentials, or if the sample application couldn’t validate the credentials, the sample application returns the login page.
-
IG returns this response to the browser.
-
Set up IG and the sample application as described in this guide.
-
Add the following route to IG to serve the sample application .css and other static resources:
-
Linux
-
Windows
$HOME/.openig/config/routes/00-static-resources.json
%appdata%\OpenIG\config\routes\00-static-resources.json
{ "name" : "00-static-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}", "handler": "ReverseProxyHandler" }
-
-
Add the following route to IG:
-
Linux
-
Windows
$HOME/.openig/config/routes/01-static.json
%appdata%\OpenIG\config\routes\01-static.json
{ "handler": { "type": "Chain", "config": { "filters": [ { "type": "StaticRequestFilter", "config": { "method": "POST", "uri": "http://app.example.com:8081/login", "form": { "username": [ "demo" ], "password": [ "Ch4ng31t" ] } } } ], "handler": "ReverseProxyHandler" } }, "condition": "${find(request.uri.path, '^/static')}" }
Notice the following features of the route:
-
The route matches requests to
/static
. -
The StaticRequestFilter replaces the request with an HTTP POST, specifying the resource to post the request to, and a form to include in the request. The form includes credentials for the username
demo
. -
The ReverseProxyHandler replays the request to the sample application.
-
-
Check that the route system log includes a message that the new files are loaded into the config:
INFO o.f.o.handler.router.RouterHandler - Loaded the route with id '00-static-resources' registered with the name '00-static-resources' INFO o.f.o.handler.router.RouterHandler - Loaded the route with id '01-static' registered with the name '01-static'
-
Go to http://ig.example.com:8080/static.
You are directed to the sample application, and logged in automatically with the username
demo
.
Next steps
This section describes some basic options to help you with IG. For information about other installation options, refer to the Installation guide.
Add a base configuration file
The entry point for requests coming in to IG is a JSON-encoded configuration file, expected by default at:
-
Linux
-
Windows
$HOME/.openig/config/config.json
%appdata%\OpenIG\config\config.json
The base configuration file initializes a heap of objects and provides the main handler to receive incoming requests. Configuration in the file is inherited by all applicable objects in the configuration.
At startup, if IG doesn’t find a base configuration file, it provides a default version, given in Default configuration. The default looks for routes in:
-
Linux
-
Windows
$HOME/.openig/config/routes
%appdata%\OpenIG\config\routes
Consider adding a custom config.json
for these reasons:
-
To prevent using the default
config.json
, whose configuration might not be appropriate in your deployment. -
To define an object once in
config.json
, and then use it multiple times in your configuration.
After adding or editing config.json
, stop and restart IG
to take the changes into effect.
For more information, refer to GatewayHttpApplication (config.json), Heap objects, and Router.
-
Add the following file to IG:
-
Linux
-
Windows
$HOME/.openig/config/config.json
%appdata%\OpenIG\config\config.json
{ "handler": { "type": "Router", "name": "_router", "baseURI": "http://app.example.com:8081", "capture": "all" }, "heap": [ { "name": "JwtSession", "type": "JwtSession" }, { "name": "capture", "type": "CaptureDecorator", "config": { "captureEntity": true, "_captureContext": true } } ] }
Notice the following features of the file:
-
The handler contains a main router named
_router
. When IG receives an incoming request,_router
routes the request to the first route in the configuration whose condition is satisfied. -
The
baseURI
changes the request URI to point the request to the sample application. -
The
capture
captures the body of the HTTP request and response. -
The JwtSession object in the heap can be used in routes to store the session information as JSON Web Tokens (JWT) in a cookie. For more information, refer to JwtSession.
-
-
Stop and restart IG.
-
Check that the route system log includes a message that the file is loaded into the config:
INFO o.f.openig.web.Initializer - Reading the configuration from ...config.json
Add a default route
When there are multiple routes in the IG configuration, they are
ordered lexicographically, by route name. For example,
01-static.json
is ordered before zz-default.json
.
When IG processes a request, the request traverses the routes in
the configuration. If the request matches the condition for
01-static.json
it is processed by that route. Otherwise, it passes to
the next route in the configuration. If a route has no condition, it can
process any request.
A default route is the last route in a configuration to which a request is routed. If a request matches no other route in the configuration, it is processed by the default route.
Add a default route to prevent errors described in No handler to dispatch to.
-
Add the following route to IG:
-
Linux
-
Windows
$HOME/.openig/config/routes/zz-default.json
%appdata%\OpenIG\config\routes\zz-default.json
{ "handler": "ReverseProxyHandler" }
Notice the following features of the route:
-
The route name starts with
zz
, so it is the last route that is loaded into the configuration. -
There is no
condition
property, so the route processes all requests. -
The route calls a ReverseProxyHandler with the default configuration, which proxies the request to the application and returns the response, without changing either the request or the response.
-
-
Check that the route system log includes a message that the file is loaded into the config:
INFO o.f.o.handler.router.RouterHandler - Loaded the route with id 'zz-default' registered with the name 'zz-default'
Switch from production mode to development mode
To prevent unwanted changes to the configuration, IG is by default in production mode after installation. For a description of the modes and information about switching between modes, refer to Operating modes.
Use IG Studio
IG Studio is a user interface to help you build and deploy your IG configuration. For more information, refer to the Studio guide.