Identity Gateway 7.2

Next steps

This section describes some basic options to help you with IG. For information about other installation options, such as setting the default location of the configuration folders, and configuring for HTTPS, see the Installation guide.

Adding 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, see GatewayHttpApplication (config.json), Heap objects, and Router.

Add a Base Configuration for IG

  1. 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, see JwtSession.

  2. Stop and restart IG.

  3. 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

Adding 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.

  1. 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.

  2. 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'

Switching from production mode to development mode

After installation, to prevent unwanted changes to the configuration, IG is by default in production mode. Access is restricted as follows:

  • The /routes endpoint is not exposed.

  • You cannot manage, list, or even read routes through Common REST.

  • Studio is effectively disabled.

  • The /share and api/info endpoints are exposed only to the loopback address.

Switch to development mode in one of the following ways, applied in order of precedence:

  1. Add the following route to IG, and restart IG:

    • Linux

    • Windows

    $HOME/.openig/config/admin.json
    %appdata%\OpenIG\config\admin.json

    • Standalone mode

    • Web container mode

    {
  "mode": "DEVELOPMENT",
  "connectors": [
    { "port" : 8080 }
  ]
}
    {
  "mode": "DEVELOPMENT"
}

    For more information, see AdminHttpApplication (admin.json)

  2. Define an environment variable for the configuration token ig.run.mode, and then start IG in the same terminal.

    If mode is not defined in admin.json, the following example starts a standalone instance of IG in development mode:

    • Linux

    • Windows

    $ IG_RUN_MODE=development /path/to/identity-gateway/bin/start.sh
    C:\IG_RUN_MODE=development
C:\path\to\identity-gateway\bin\start.bat %appdata%\OpenIG

  3. Define a system property for the configuration token ig.run.mode when you start IG.

    If mode is not defined in admin.json, or an IG_RUN_MODE environment variable is not set, the following file starts a standalone instance of IG with the system property ig.run.mode to force development mode:

    • Linux

    • Windows

    $HOME/.openig/env.sh
    %appdata%\OpenIG\env.sh
    export JAVA_OPTS='-Dig.run.mode=development'

For information about restricting access to Studio in development mode, see Restricting access to Studio. For information about switching back to production mode, see Switching from development mode to production mode.

Using IG Studio

IG Studio is a user interface to help you build and deploy your IG configuration. For information about using Studio, see the Studio guide.

Copyright © 2010-2024 ForgeRock, all rights reserved.