OpenIG 3.0 Migration CLI

This blog post was first published @ sauthieg.github.io, included here with permission.

ForgeRock OpenIG 3.1 has been recently released (12th of December, on time ;) ) and
it’s time for you to give it a try! Already done that ? Great! But wait a minute,
what are all theses deprecation warning messages you see on the logs ?

WED DEC 17 16:46:03 CET 2014 (WARNING) file:/.../config/config.json
The configuration field heap/objects has been deprecated. Heap objects should now be listed directly in the top level "heap" field, e.g. { "heap" : [ objects... ] }.
------------------------------
WED DEC 17 16:46:03 CET 2014 (WARNING) file:/.../config/config.json
[/] The 'handlerObject' attribute is deprecated, please use 'handler' instead
------------------------------

Don’t worry, this messages are only warnings, your old configurations are still parseable
by OpenIG 3.1: everything is backward compatible, we just warn you that, in the next
major release, theses elements are likely to be unsupported (in other words, they
would probably be ignored).

Hopefully, in order to reduce the burden of migrating your config files manually,
which is always an error-prone operation, I wrote a small toolkit that will massage
your existing JSON configuration and produce a 3.1 compatible JSON.

At time of writing, the openig-migration toolkit supports the following migration actions:

  • heap/objects array has been simplified to just heap
  • Heap object declaration inline (when possible)
  • Remove "config": {} (empty element)
  • Rename RedirectFilter to LocationHeaderFilter
  • Rename handlerObject to handler
  • Rename OAuth2ResourceServerFilter deprecated attributes to new names

Usage

As there is still no binary available, you have to build the binary yourself (make
sure you use a JDK 8 at both compile and runtime):

git clone https://github.com/sauthieg/openig-migration.git
cd openig-migration
mvn clean install

Then, you have to execute it: it expects a path to the JSON document to migrate:

java -jar target/openig-migration-1.0-SNAPSHOT-jar-with-dependencies.jar .../config.json

This command line outputs the transformed JSON on System.out.

Example

This example is extracted from OpenIG 3.0 documentation:

{
  "heap": {
    "objects": [
      {
        "name": "DispatchHandler",
        "type": "DispatchHandler",
        "config": {
          "bindings": [
            {
              "condition": "${exchange.request.uri.path == '/login'}",
              "handler": "LoginChain",
              "baseURI": "http://TARGETIP"
            },
            {
              "handler": "OutgoingChain",
              "baseURI": "http://TARGETIP"
            }
          ]
        }
      },
      {
        "name": "LoginChain",
        "type": "Chain",
        "config": {
          "filters": [
            "LoginRequest"
          ],
          "handler": "OutgoingChain"
        }
      },
      {
        "name": "LoginRequest",
        "type": "StaticRequestFilter",
        "config": {
          "method": "POST",
          "uri": "https://TARGETIP/login",
          "form": {
            "USER": [
              "myusername"
            ],
            "PASSWORD": [
              "mypassword"
            ]
          }
        }
      },
      {
        "name": "OutgoingChain",
        "type": "Chain",
        "config": {
          "filters": [
            "CaptureFilter"
          ],
          "handler": "ClientHandler"
        }
      },
      {
        "name": "CaptureFilter",
        "type": "CaptureFilter",
        "config": {
          "captureEntity": false,
          "file": "/tmp/gateway.log"
        }
      },
      {
        "name": "ClientHandler",
        "comment": "Responsible for sending all requests to remote servers.",
        "type": "ClientHandler",
        "config": {}
      }
    ]
  },
  "handlerObject": "DispatchHandler"
}

… and is migrated to:

{
  "heap": [
    {
      "name": "DispatchHandler",
      "type": "DispatchHandler",
      "config": {
        "bindings": [
          {
            "condition": "${exchange.request.uri.path == '/login'}",
            "handler": {
              "name": "LoginChain",
              "type": "Chain",
              "config": {
                "filters": [
                  {
                    "name": "LoginRequest",
                    "type": "StaticRequestFilter",
                    "config": {
                      "method": "POST",
                      "uri": "https://TARGETIP/login",
                      "form": {
                        "USER": [
                          "myusername"
                        ],
                        "PASSWORD": [
                          "mypassword"
                        ]
                      }
                    }
                  }
                ],
                "handler": "OutgoingChain"
              }
            },
            "baseURI": "http://TARGETIP"
          },
          {
            "handler": "OutgoingChain",
            "baseURI": "http://TARGETIP"
          }
        ]
      }
    },
    {
      "name": "OutgoingChain",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "name": "CaptureFilter",
            "type": "CaptureFilter",
            "config": {
              "captureEntity": false,
              "file": "/tmp/gateway.log"
            }
          }
        ],
        "handler": {
          "name": "ClientHandler",
          "comment": "Responsible for sending all requests to remote servers.",
          "type": "ClientHandler"
        }
      }
    }
  ],
  "handler": "DispatchHandler"
}

Notice the now inlined object declaration that make it easier to follow the execution
flow and understand what happen to your request. The empty un-necessary elements
have been removed too.

Limitations

At time of writing, some old JSON files may be incorrectly handled by the migration CLI:

  • Incorrectly escaped regular expressions (in EntitytExtractFilter)
  • Multi-line Strings (without a line ending )

Contributions

Feel free to open issues, and/or fork the repository for any
improvements you can think of.

I’ll be happy to consider all pull requests.

Happy hacking !

©2019 ForgeRock - we provide an identity and access platform to secure every online relationship for the enterprise market, educational sector and even entire countries. Click to view our privacy policy and terms of use.

Log in with your credentials

Forgot your details?