Configuration Templates

This chapter contains template routes for common configurations.

Before you use one of the templates here, install and configure OpenIG with a router and default route as described in Getting Started.

Next, take one of the templates and then modify it to suit your deployment. Read the summary of each template to find the right match for your application.

When you move to use OpenIG in production, be sure to turn off DEBUG level logging, and to deactivate CaptureDecorator use to avoid filling up disk space. Also consider locking down the Router configuration.

Proxy and Capture

If you installed and configured OpenIG with a router and default route as described in Getting Started, then you already proxy and capture both the application requests coming in and the server responses going out.

The route shown in Proxy and Capture uses a DispatchHandler to change the scheme to HTTPS on login. To use this template change the baseURI settings to match those of the target application.

When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate. If the certificate was signed by a well-known Certificate Authority, then there should be no further configuration to do. Otherwise, use a ClientHandler that references a truststore holding the certificate.

Proxy and Capture

{
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${request.uri.path == '/login'}",
          "handler": "ClientHandler",
          "comment": "Must be able to trust the server cert for HTTPS",
          "baseURI": "https://app.example.com:8444"
        },
        {
          "condition": "${request.uri.scheme == 'http'}",
          "handler": "ClientHandler",
          "baseURI": "http://app.example.com:8081"
        },
        {
          "handler": "ClientHandler",
          "baseURI": "https://app.example.com:8444"
        }
      ]
    }
  },
  "capture": "all",
  "condition": "${matches(request.uri.query, 'demo=capture')}"
}

To try this example with the sample application, save the file as $HOME/.openig/config/routes/20-capture.json, and browse to http://openig.example.com:8080/login?demo=capture.

To use this as a default route with a real application, remove the route-level condition on the handler that specifies a demo query string parameter.

The route in Simple Login Form logs the user into the target application with hard-coded user name and password. The route intercepts the login page request and replaces it with the login form. Adapt the uri, form, and baseURI settings as necessary.

Simple Login Form

{
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler",
      "comment": "Testing only: blindly trust the server cert for HTTPS.",
      "config": {
        "trustManager": {
          "type": "TrustAllManager"
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${request.uri.path == '/login'}",
            "request": {
              "method": "POST",
              "uri": "https://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=simple')}"
}

The parameters in the PasswordReplayFilter form, MY_USERNAME and MY_PASSWORD, can use strings or expressions. When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/21-simple.json, replace MY_USERNAME with demo and MY_PASSWORD with changeit, and browse to http://openig.example.com:8080/login?demo=simple.

To use this as a default route with a real application, use a ClientHandler that does not blindly trust the server certificate, and remove the route-level condition on the handler that specifies a demo query string parameter.

Some applications expect a cookie from the login page to be sent in the login request form. OpenIG can manage the cookies. The route in Login Form With Cookie From Login Page allows the login page request to go through to the target, and manages the cookies set in the response rather than passing the cookie through to the browser.

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${request.uri.path == '/login'}",
            "request": {
              "method": "POST",
              "uri": "https://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ]
              }
            }
          }
        },
        {
          "type": "CookieFilter"
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=cookie')}"
}

The parameters in the PasswordReplayFilter form, MY_USERNAME and MY_PASSWORD, can use strings or expressions. A CookieFilter with no specified configuration manages all cookies that are set by the protected application. When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/22-cookie.json, replace MY_USERNAME with kramer and MY_PASSWORD with newman, and browse to http://openig.example.com:8080/login?demo=cookie.

To use this as a default route with a real application, remove the route-level condition on the handler that specifies a demo query string parameter.

The route in Login Form With Password Replay and Cookie Filters works with an application that returns the login page when the user tries to access a page without a valid session. This route shows how to use a PasswordReplayFilter to find the login page with a pattern that matches a mock OpenAM Classic UI page.

The route uses a CookieFilter to manage cookies, ensuring that cookies from the protected application are included with the appropriate requests. The side effect of OpenIG managing cookies is none of the cookies are sent to the browser, but are managed locally by OpenIG.

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPageContentMarker": "OpenAM\\s\\(Login\\)",
            "request": {
              "comments": [
                "An example based on OpenAM classic UI: ",
                "uri is for the OpenAM login page; ",
                "IDToken1 is the username field; ",
                "IDToken2 is the password field; ",
                "host takes the OpenAM FQDN:port.",
                "The sample app simulates OpenAM."
              ],
              "method": "POST",
              "uri": "http://app.example.com:8081/openam/UI/Login",
              "form": {
                "IDToken0": [
                  ""
                ],
                "IDToken1": [
                  "demo"
                ],
                "IDToken2": [
                  "changeit"
                ],
                "IDButton": [
                  "Log+In"
                ],
                "encoded": [
                  "false"
                ]
              },
              "headers": {
                "host": [
                  "app.example.com:8081"
                ]
              }
            }
          }
        },
        {
          "type": "CookieFilter"
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=classic')}"
}

The parameters in the PasswordReplayFilter form can use strings or expressions.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/23-classic.json, and use the curl command to check that it works as in the following example, which shows that the CookieFilter has removed cookies from the response except for the session cookie added by the container:

$ curl -D- http://openig.example.com:8080/login?demo=classic
HTTP/1.1 200 OK
...
Set-Cookie: JSESSIONID=1gwp5h0ugkciv1g200c9hid4sp;Path=/
Content-Length: 15
Content-Type: text/plain;charset=ISO-8859-1
...

Welcome, demo!

To use this as a default route with a real application, remove the route-level condition on the handler that specifies a demo query string parameter, and adjust the PasswordReplayFilter as necessary.

Some applications call for extracting a hidden value from the login page and including the value in the login form POSTed to the target application. The route in Login Which Requires a Hidden Value From the Login Page extracts a hidden value from the login page, and posts a static form including the hidden value.

{
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler",
      "comment": "Testing only: blindly trust the server cert for HTTPS.",
      "config": {
        "trustManager": {
          "type": "TrustAllManager"
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${request.uri.path == '/login'}",
            "loginPageExtractions": [
              {
                "name": "hidden",
                "pattern": "loginToken\\s+value=\"(.*)\""
              }
            ],
            "request": {
              "method": "POST",
              "uri": "https://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ],
                "hiddenValue": [
                  "${attributes.extracted.hidden}"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=hidden')}"
}

The parameters in the PasswordReplayFilter form, MY_USERNAME and MY_PASSWORD, can have string values, and they can also use expressions. When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/24-hidden.json, replace MY_USERNAME with scarter and MY_PASSWORD with sprain, and browse to http://openig.example.com:8080/login?demo=hidden.

HTTP and HTTPS Application

The route in HTTP and HTTPS Application proxies traffic to an application with both HTTP and HTTPS ports. The application uses HTTPS for authentication and HTTP for the general application features. Assuming all login requests are made over HTTPS, you must add the login filters and handlers to the chain.

HTTP and HTTPS Application

{
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${request.uri.scheme == 'http'}",
          "handler": "ClientHandler",
          "baseURI": "http://app.example.com:8081"
        },
        {
          "condition": "${request.uri.path == '/login'}",
          "handler": {
            "type": "Chain",
            "config": {
              "comment": "Add one or more filters to handle login.",
              "filters": [],
              "handler": "ClientHandler"
            }
          },
          "baseURI": "https://app.example.com:8444"
        },
        {
          "handler": "ClientHandler",
          "baseURI": "https://app.example.com:8444"
        }
      ]
    }
  },
  "condition": "${matches(request.uri.query, 'demo=https')}"
}

When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/25-https.json, and browse to http://openig.example.com:8080/login?demo=https.

To use this as a default route with a real application, remove the route-level condition on the handler that specifies a demo query string parameter.

OpenAM Integration With Headers

The route in OpenAM Integration With Headers logs the user into the target application using the headers such as those passed in from an OpenAM policy agent. If the header passed in contains only a user name or subject and requires a lookup to an external data source, you must add an attribute filter to the chain to retrieve the credentials.

OpenAM Integration With Headers

{
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler",
      "comment": "Testing only: blindly trust the server cert for HTTPS.",
      "config": {
        "trustManager": {
          "type": "TrustAllManager"
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${request.uri.path == '/login'}",
            "request": {
              "method": "POST",
              "uri": "https://app.example.com:8444/login",
              "form": {
                "username": [
                  "${request.headers['username'][0]}"
                ],
                "password": [
                  "${request.headers['password'][0]}"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=headers')}"
}

When connecting to the protected application over HTTPS, the ClientHandler must be configured to trust the application’s public key server certificate.

To try this example with the sample application, save the file as $HOME/.openig/config/routes/26-headers.json, and use the curl command to simulate the headers being passed in from an OpenAM policy agent as in the following example:

$ curl \
 --header "username: kvaughan" \
 --header "password: bribery" \
 http://openig.example.com:8080/login?demo=headers
...
    <title id="welcome">Howdy, kvaughan</title>
...

Microsoft Online Outlook Web Access

The route in Microsoft Online Outlook Web Access logs the user into Microsoft Online Outlook Web Access (OWA). The example shows how you would use OpenIG and the OpenAM password capture feature to integrate with OWA. Follow the example in Getting Login Credentials From OpenAM, and substitute this template as a replacement for the default route.

Microsoft Online Outlook Web Access

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${request.uri.path == '/owa/auth/logon.aspx'}",
            "headerDecryption": {
              "algorithm": "DES/ECB/NoPadding",
              "key": "DESKEY",
              "keyType": "DES",
              "charSet": "utf-8",
              "headers": [
                "password"
              ]
            },
            "request": {
              "method": "POST",
              "uri": "https://login.microsoftonline.com",
              "headers": {
                "Host": [
                  "login.microsoftonline.com"
                ],
                "Content-Type": [
                  "Content-Type:application/x-www-form-urlencoded"
                ]
              },
              "form": {
                "destination": [
                  "https://login.microsoftonline.com/owa/"
                ],
                "forcedownlevel": [
                  "0"
                ],
                "trusted": [
                  "0"
                ],
                "username": [
                  "${request.headers['username'][0]}"
                ],
                "passwd": [
                  "${request.headers['password'][0]}"
                ],
                "isUtf8": [
                  "1"
                ]
              }
            }
          }
        }
      ],
      "handler": {
        "type": "Chain",
        "config": {
          "filters": [
            {
              "type": "HeaderFilter",
              "config": {
                "messageType": "REQUEST",
                "remove": [
                  "password",
                  "username"
                ]
              }
            }
          ],
          "handler": {
            "type": "ClientHandler"
          },
          "baseURI": "https://login.microsoftonline.com"
        }
      }
    }
  },
  "condition": "${matches(request.uri.query, 'demo=headers')}"
}

To try this example, save the file as $HOME/.openig/config/routes/27-owa.json. Change DESKEY to the actual key value that you generated when following the instructions in Configuring Password Capture.

To use this as a default route with a real application, remove the route-level condition on the handler that specifies a demo query string parameter.