Most organizations have valuable existing services that they cannot easily integrate into newer architectures. Often, however, they also cannot change the existing services. Without a gateway to bridge the gap, some client applications cannot communicate with these existing services.

Figure 1.1. Missing Gateway

OpenIG works as an HTTP gateway, also known as a reverse proxy. You deploy OpenIG on the network so that it intercepts both client requests and also server responses.

Figure 1.2. OpenIG Deployed

Clients then exchange with protected servers through OpenIG. This means that without touching either clients or servers, you can configure OpenIG to add new capabilities to existing services.

OpenIG supports these capabilities as out-of-the-box configuration options. Once you understand the essential concepts covered in this chapter, try the demonstrations in this guide to see for yourself how to add these features by using OpenIG.

OpenIG handles HTTP requests and responses with a wrapper called the exchange.

The OpenIG exchange encapsulates HTTP requests and responses that pass through OpenIG, as well as the principal associated with the request, the session context associated with the client, and any other state information needed. OpenIG makes it easy to access arbitrary state information through the exchange so that you can use it throughout the duration of the exchange, even when the exchange calls for interaction with additional services.

In addition, OpenIG includes information in the exchange about the client that made the incoming request, such as the client host, port, and IP address, and also the user-agent description, the login of the user making the request, and the X.509 certificates presented by the client when these are available as part of the request.

OpenIG represents its configuration in JSON format, which is store in flat files.^[1] You configure OpenIG by editing the JSON flat files.

After installation, you add at least one configuration file. Each configuration file holds a JSON object. At minimum, the JSON object specifies a "handler" to deal with the exchange.

The following very simple configuration routes exchanges to be handled according to separate route configurations.

{
    "handler": {
        "type": "Router"
    }
}
  

The "handler" indicates which object OpenIG invokes first. A handler is an object responsible for producing a response to a request, therefore every route must call a handler.

Notice in this case that the "handler" field takes an object as its value. This is an inline declaration. If you only use the object once where it is declared, then it makes sense to use an inline declaration.

To change the definition of an object defined by default or when you need to declare an object once and use it multiple times, you declare object definitions in the "heap", and then reference the objects by "name". You can also use this technique instead of inline declarations.

The following example declares an identical "Router" object as above and references it by its name.

{
    "handler": "My Router",
    "heap": [
        {
            "name": "My Router",
            "type": "Router"
        }
    ]
}
  

Notice that the "heap" takes an array. As the "heap" holds configuration objects all at the same level, you can impose any hierarchy or order that you like when referencing objects. Yet, when you declare all objects in the "heap" and reference them by name, neither hierarchy nor ordering are obvious from the structure of the configuration file alone.

The configuration can specify additional objects as well. For example, you can configure an "HttpClient" that OpenIG uses to connect to servers. The following "HttpClient" configuration uses defaults for all settings, except "hostnameVerifier", which it configures to verify host names in SSL certificates in the same way as most browsers.

{
    "name": "HttpClient",
    "type": "HttpClient",
    "config": {
        "hostnameVerifier": "BROWSER_COMPATIBLE"
    }
}
  

Decorators are additional heap objects that let you extend what another object can do. For example, a "CaptureDecorator" enables filters and handlers to log requests and responses. A "TimerDecorator" logs processing times. You decorate the configuration of other objects with the names of decorators as field names. OpenIG defines both a "CaptureDecorator" named "capture" and also a "TimerDecorator" named "timer" by default. You can therefore log requests, responses, and processing times by adding decorations as shown in the following example.

{
    "handler": {
        "type": "Router",
        "capture": [ "request", "response" ],
        "timer": true
    }
}
  

In addition to decorators, OpenIG also creates other utility objects with default settings, including "HttpClient", "LogSink", and "TemporaryStorage". You can reference these objects by name without configuring them unless you need to override the default configurations.

Routes, mentioned here and described in more detail in Section 1.4, "Routing", inherit settings from their parent configurations. This means that you can configure global objects in the "heap" of the base configuration for example, and then reference the objects by name in any other OpenIG configuration.

OpenIG routing lets you use multiple configuration files. Routing also lets OpenIG reload configurations that you change at runtime without restarting OpenIG.

You can use routing where OpenIG protects multiple services, or multiple different endpoints of the same service. You can also use routing when handling an exchange involves multiple steps, for example because you must redirect the client to authenticate with an identity provider before accessing the service.

A router, as shown in Section 1.3, "The Configuration", takes responsibility for managing the routes used, periodically reloading changed routes unless configured to load them only at startup.

Notice in the example that the router does not specify any routes. Instead, routes optionally specify their own "condition". If a route "condition" is true, then the route handles the exchange.

The following example specifies a condition that is true when the incoming request path is /login.

"condition": "${matches(exchange.request.uri.path, '^/login')}"
  

If the route has no "condition", or if the value of the condition is null, then the route matches any exchange. Furthermore, OpenIG orders routes lexicographically by name.

You can use these features to have both optional and default routes. For example, you could name your routes to check conditions in order: 01-login.json, 02-protected.json, 99-default.json. Alternatively, you can name routes using the "name" property on the route.

A router configuration can specify where to look for route files. As a "Router" is a kind of "handler", routes can have routers, too.

Routing only delegates exchange handling. It does not actually deal with exchanges. To deal with an exchange, you chain together filters and handlers.

The following diagram shows the flow inside a chain that has a request filter transforming the request, a response filter transforming the response, and a handler sending a request to a service to get a response. Notice how the flow traverses the filters in reverse order when the outgoing exchange comes back from the handler.

Figure 1.3. Flow Inside a Chain

The following route configuration demonstrates the flow, but without an external service.

{
    "handler": {
        "type": "Chain",
        "comment": "Base configuration defines the capture decorator",
        "config": {
            "filters": [
                {
                    "type": "HeaderFilter",
                    "comment": "Same header on all requests",
                    "config": {
                        "messageType": "REQUEST",
                        "add": {
                            "X-MyHeaderFilter": [
                                "Added by HeaderFilter to request"
                            ]
                        }
                    }
                },
                {
                    "type": "HeaderFilter",
                    "comment": "Remove X-Powered-By from response",
                    "capture": "response",
                    "config": {
                        "messageType": "RESPONSE",
                        "remove": [
                            "X-Powered-By"
                        ]
                    }
                }
            ],
            "handler": {
                "type": "StaticResponseHandler",
                "comment": "Same response to all requests",
                "capture": "request",
                "config": {
                    "status": 200,
                    "reason": "OK",
                    "headers": {
                        "X-Powered-By": [
                            "OpenIG"
                        ]
                    },
                    "entity": "<html><p>Hello, World!</p></html>"
                }
            }
        }
    }
}
  

Suppose this chain configuration is the only route active for the request. In that case, the flow produces the following.

### Original request from user-agent
GET / HTTP/1.1
Host: www.example.com:8080
Accept: */*

### Captured incoming request (inside OpenIG exchange)
GET / HTTP/1.1
X-MyHeaderFilter: Added by HeaderFilter to request
Accept: */*
Host: www.example.com:8080

### Captured outgoing response (inside OpenIG exchange)
HTTP/1.1 200 OK
Content-Length: 33
X-Powered-By: OpenIG

<html><p>Hello, World!</p></html>

### Final response to user-agent
HTTP/1.1 200 OK
Content-Length: 33

<html><p>Hello, World!</p></html>
  

JSON does not specify a notation for comments.

However, when OpenIG does not recognize a JSON field name, it ignores the field. This makes it possible to use comments in configuration files.

Now that you understand the essential concepts, start using OpenIG with the help of the following chapters.

ForgeRock can also help you succeed in your projects involving OpenIG. You can purchase OpenIG support subscriptions and training courses from ForgeRock and from consulting partners around the world and in your area. To contact ForgeRock, send mail to info@forgerock.com. To find a partner in your area, see http://forgerock.com/partners/find-a-partner/.

Make sure you have a supported Java Development Kit installed. For details, see the Release Notes section, JDK Version in the Release Notes.

You install OpenIG in the root context of a web application container. In this chapter, you use Jetty server as the web application container.

Now that OpenIG is installed, set up a sample application to protect.

Now that you have installed both OpenIG and also a sample application to protect, and configure OpenIG.

So far you have deployed OpenIG in the root context of Jetty on port 8080. Since OpenIG is a reverse proxy you must make sure that all traffic from your browser to the protected application goes through OpenIG. In other words, the network must be configured so that the browser goes to OpenIG instead of going directly to the protected application.

Although if you followed the installation steps you are running both OpenIG and the minimal HTTP server on the same host as your browser (probably your laptop or desktop), keep in mind that network configuration is an important deployment step. To encourage you to keep this in mind, the sample configuration for this chapter expects the minimal HTTP server to be running on www.example.com, rather than localhost.

The quickest way to configure the network locally is to add an entry to your /etc/hosts file on UNIX systems or %SystemRoot%\system32\drivers\etc\hosts on Windows. See the Wikipedia entry, Hosts (file), for more information on host files. If you are indeed running all servers in this chapter on the same host, add the following entry to the hosts file.

127.0.0.1    www.example.com

If you are running the browser and OpenIG on separate hosts, add the IP address of the host running OpenIG to the hosts file on the system running the browser, where the host name matches that of protected application. For example, if OpenIG is running on a host with IP address 192.168.0.15:

192.168.0.15    www.example.com

If OpenIG is on a different host from the protected application, also make sure that the host name of the protected application resolves correctly for requests from OpenIG to the application.

http://www.example.com:8080/ should take you to the home page of the minimal HTTP server.

What just happened?

When your browser goes to http://www.example.com:8080/, it is actually connecting to OpenIG deployed in Jetty. OpenIG proxies all traffic it receives to the protected application at http://www.example.com:8080/, and returns responses from the application to your browser. It does this based on the configuration that you set up.

Consider the base configuration file first, config.json. The base configuration file specifies a router handler named "Router". OpenIG calls this handler when it receives an incoming request. In addition, it uses the "LogSink" to log debug messages to the console. Alternatively, to send log messages to a file you can use a "FileLogSink" in the Reference, rather than a "ConsoleLogSink".

The "baseURI" setting in turn changes the request URI to point the request to the sample application to protect. The "Router" captures the request on the way in, and captures the response on the way out.

The "Router" routes processing to separate route configurations.

For now the only route available is the the default route you added, 99-default.json. The default route calls a "ClientHandler" with the default configuration. This "ClientHandler" simply proxies the request to and the response from the sample application to protect without changing either the request or the response. Therefore, the browser request is sent unchanged to the sample application and the response from the sample application is returned unchanged to your browser.

Also view the information logged about requests and responses, which shows up in the Jetty log.

What's happening behind the scenes?

With the original configuration, OpenIG does not change requests or responses, but only proxies requests and responses, and captures request and response information.

After you change the configuration, OpenIG continues to capture request and response data. When your request does not goes to the default route, but instead goes to /static, then the condition on the new route you added matches the request. OpenIG therefore uses the new route you added.

Using the route configuration in 01-static.json, OpenIG replaces your browser's original HTTP GET request with an HTTP POST login request containing credentials to authenticate. As a result, instead of the home page with a login form, OpenIG logs you in directly, and the application responds with the page you see after logging in. OpenIG then returns this response to your browser.

The following sequence diagram shows the steps.

Figure 2.1. 

This section provides installation and configuration tips that you need to run OpenIG in supported containers.

For the full list of supported containers, see the Release Notes section, Web Application Containers in the Release Notes.

For further information on advanced configuration for a particular container, see the container documentation.

<Context sessionCookieDomain=".example.com" />

    

<Connector
 port="8443"
 protocol="HTTP/1.1"
 SSLEnabled="true"
 maxThreads="150"
 scheme="https"
 secure="true"
 address="127.0.0.1"
 clientAuth="false"
 sslProtocol="TLS"
 keystoreFile="/path/to/tomcat/conf/keystore"
 keystorePass="password"
/>

    

$ keytool \
 -genkey \
 -alias tomcat \
 -keyalg RSA \
 -keystore /path/to/tomcat/conf/keystore \
 -storepass password \
 -keypass password \
 -dname "CN=openig.example.com,O=Example Corp,C=FR"
    

<Get name="sessionHandler">
    <Get name="sessionManager">
        <Set name="sessionDomain">.example.com</Set>
    </Get>
</Get>

    

In order for OpenIG to function as a reverse proxy, browsers attempting to access the protected application must go through OpenIG instead.

Modify DNS or host file settings so that the host name of the protected application resolves to the IP address of OpenIG on the system where the browser runs.

Restart the browser after making this change.

For a high scale or highly available deployment, you can prepare a pool of OpenIG servers with nearly identical configurations, and then load balance requests across the pool, routing around any servers that become unavailable. Load balancing allows the service to handle more load.

Before you spread requests across multiple servers, however, you must determine what to do with state information that OpenIG saves in the exchange, or retrieves locally from the OpenIG server system. If information is retrieved locally, then also consider setting up failover so that if one server becomes unavailable, another server in the pool can take its place. The benefit of failover is that a server failure can be invisible to client applications.

By default the exchange data resides in memory in the container where OpenIG runs. This includes the default session implementation, which is backed by the HttpSession that the container handles. You can opt to store session data on the user-agent instead, however. For details and to consider whether your data fits, see JwtSession in the Reference. When you use the JwtSession implementation, be sure to share the encryption keys across all servers, so that any server can read session cookies from any other.

If your data does not fit in an HTTP cookie, for example because when encrypted it is larger than 4 KB, consider storing a reference in the cookie, and then retrieve the data by using another filter. OpenIG logs warning messages if the JwtSession cookie is too large. Using a reference can also work when a server becomes unavailable, and the load balancer must fail requests over to another server in the pool.

If some data attached to an exchange must be stored on the server side, then you have additional configuration steps to perform for session stickiness and for session replication. Session stickiness means that the load balancer sends all requests from the same client session to the same server. Session stickiness helps to ensure that a client request goes to the server holding the original session data. Session replication involves writing session data either to other servers or to a data store, so that if one server goes down, other servers can read the session data and continue processing. Session replication helps when one server fails, allowing another server to take its place without having to start the session over again. If you set up session stickiness but not session replication, when a server crashes the client session information for that server is lost, and the client must start again with a new session.

How you configure session stickiness and session replication depends on your load balancer and on your container.

For OpenIG to connect to a server securely over HTTPS, OpenIG must be able to trust the server. The default settings rely on the Java environment trust store to trust server certificates. The Java environment default trust store includes public key signing certificates from many well-known Certificate Authorities (CAs). If all servers present certificates signed by these CAs, then you have nothing to configure.

If however the server certificates are self-signed or signed by a CA whose certificate is not trusted out of the box, then you can configure a KeyStore in the Reference, TrustManager in the Reference, and optionally a KeyManager in the Reference to reference when configuring an HttpClient in the Reference to enable OpenIG to trust servers when acting as a client.

The KeyStore holds the servers' certificates or the CA signing certificate. The TrustManager allows OpenIG to handle the certificates in the KeyStore when deciding whether to trust a server certificate. The optional KeyManager allows OpenIG to present its certificate from the key store when the server must authenticate OpenIG as client. The HttpClient references whatever TrustManager and KeyManager you configure.

You can configure each of these either globally for the OpenIG server, of locally for a particular ClientHandler configuration.

The Java KeyStore holds the peer servers' public key certificates (and optionally the OpenIG certificate and private key). For example, suppose you have a certificate file, ca.crt, that holds the trusted signer's certificate of the CA who signed the server certificates of the servers in your deployment. In that case, you could import the certificate into a Java Key Store file, /path/to/keystore.jks.

$ keytool \
 -import \
 -trustcacerts \
 -keystore /path/to/keystore \
 -file ca.crt \
 -alias ca-cert \
 -storepass changeit
  

You could then configure the following "KeyStore" for OpenIG that holds the trusted certificate. Notice that the "url" field takes an expression that evaluates to a URL, starting with a scheme such as file://.

{
    "name": "MyKeyStore",
    "type": "KeyStore",
    "config": {
        "url": "file:///path/to/keystore",
        "password": "changeit"
    }
}
  

The TrustManager handles the certificates in the KeyStore when deciding whether to trust the server certificate. The TrustManager references your KeyStore.

{
    "name": "MyTrustManager",
    "type": "TrustManager",
    "config": {
        "keystore": "MyKeyStore"
    }
}
  

The following HttpClient configuration references "MyTrustManager" and sets browser-compatible host name verification.

{
    "name": "HttpClient",
    "type": "HttpClient",
    "config": {
        "hostnameVerifier": "BROWSER_COMPATIBLE",
        "trustManager": "MyTrustManager"
    }
}
  

You can use JwtSession in the Reference to configure OpenIG to store session information in JWT cookies on the user-agent, rather than storing the information in the container where OpenIG runs.

In order to encrypt the JWTs, OpenIG needs cryptographic keys. OpenIG can generate its own key pair in memory, but that key pair disappears on restart and cannot be shared across OpenIG servers.

Alternatively, OpenIG can use keys from a key store. The following steps describe how to prepare the key store for JWT encryption.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as you did for the chapter on Getting Started.

OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

This sample shows you how to configure OpenIG to get credentials from a file.

The sample uses a comma-separated value file, userfile.

username,password,fullname,email
george,costanza,George Costanza,george@example.com
kramer,newman,Kramer,kramer@example.com
bjensen,hifalutin,Babs Jensen,bjensen@example.com
demo,changeit,Demo User,demo@example.com
kvaughan,bribery,Kirsten Vaughan,kvaughan@example.com
scarter,sprain,Sam Carter,scarter@example.com

  

OpenIG looks up the user credentials based on the user's email address. OpenIG relies for this on a FileAttributesFilter configuration object.

Now browse to http://www.example.com:8080/file.

If everything is configured correctly, OpenIG logs you in as George.

What's happening behind the scenes?

Figure 4.1. 

OpenIG intercepts your browser's HTTP GET request. The request matches the new route configuration. The OpenIG "FileAttributesFilter" looks up credentials in a file, and stores the credentials it finds in the exchange. OpenIG then calls the next filter in the chain, "StaticRequestFilter", passing the exchange object that now holds the credentials. The "StaticRequestFilter" filter pulls the credentials out of the exchange, builds the login form, and performs the HTTP POST request to the HTTP server. The HTTP server validates the credentials, and responds with a profile page. OpenIG then passes the response from the HTTP server to your browser.

This sample shows you how to configure OpenIG to get credentials from H2. This sample was developed with Jetty and with H2 1.4.178.

Although this sample uses H2, OpenIG also works with other database software. OpenIG relies on the application server where it runs to connect to the database. Configuring OpenIG to retrieve data from a database is therefore a question of configuring the application server to connect to the database, and configuring OpenIG to choose the appropriate data source, and to send the appropriate SQL request to the database. As a result, the OpenIG configuration depends more on the data structure than on any particular database drivers or connection configuration.

What's happening behind the scenes?

Figure 4.2. 

OpenIG intercepts your browser's HTTP GET request. The request matches the new route configuration. The OpenIG "SqlAttributesFilter" looks up credentials in H2, and stores the credentials it finds in the exchange. OpenIG then calls the next filter in the chain, "StaticRequestFilter", passing the exchange object that now holds the credentials. The "StaticRequestFilter" filter pulls the credentials out of the exchange, builds the login form, and performs the HTTP POST request to the HTTP server. The HTTP server validates the credentials, and responds with a profile page. OpenIG then passes the response from the HTTP server to your browser.

The figure below illustrates the flow of requests for a user who is not yet logged in to OpenAM accessing a protected application. After successful authentication, the user is logged into the application with the username and password from the OpenAM login session.

This tutorial calls for you to set up several different software components.

In this section, it is assumed that you are familiar with the components involved. For OpenAM documentation, see https://backstage.forgerock.com/docs/am.

{
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "CryptoHeaderFilter",
                    "config": {
                        "messageType": "REQUEST",
                        "operation": "DECRYPT",
                        "algorithm": "DES/ECB/NoPadding",
                        "key": "DESKEY",
                        "keyType": "DES",
                        "charSet": "utf-8",
                        "headers": [
                            "password"
                        ]
                    }
                },
                {
                    "type": "StaticRequestFilter",
                    "config": {
                        "method": "POST",
                        "uri": "http://www.example.com:8081",
                        "form": {
                            "username": [
                                "${exchange.request.headers['username'][0]}"
                            ],
                            "password": [
                                "${exchange.request.headers['password'][0]}"
                            ]
                        }
                    }
                },
                {
                    "type": "HeaderFilter",
                    "config": {
                        "messageType": "REQUEST",
                        "remove": [
                            "password",
                            "username"
                        ]
                    }
                }
            ],
            "handler": "ClientHandler"
        }
    },
    "condition": "${matches(exchange.request.uri.path, '^/replay')}"
}

   

Log out of OpenAM if you are logged in already.

Access the new route, http://www.example.com:8080/replay.

If you are not already logged into OpenAM you should be redirected to the OpenAM login page. Login with username george, password costanza. After login you should be redirected back to the application.

The Federation component of OpenIG is a standards based authentication service used by OpenIG to validate a user and retrieve key attributes of the user in order to log them in to applications that OpenIG protects. The Federation component implements Security Assertion Markup Language 2.0.

Security Assertion Markup Language (SAML) 2.0 is a standard for exchanging security information across organizational boundaries. SAML 2.0 enables web single sign-on (SSO), for example, where the service managing the user's identity does not necessarily belong to the same organization and does not necessarily use the same software as the service that the user wants to access.

In SAML 2.0, the service managing the user's identity is called the Identity Provider (IDP). The service that the user wants to access is called the Service Provider (SP). Provider organizations agree on the security information they want to exchange, and then they mutually configure access to each others' services, so that the SAML 2.0 federation capability is ready for use. The group of providers sets up a circle of trust, which is a list of services participating in the federation. In order to be able to configure access to services in the circle of trust, the providers share SAML 2.0 metadata describing their services in an XML format defined by the SAML 2.0 standard.

OpenIG plays the role of SAML 2.0 SP. You must therefore configure OpenIG as SP to access IDP services in order for the Federation component to be operational.

For SAML 2.0 web SSO, the user authenticates with the IDP. This can start either with the user visiting the IDP site and logging in, or with the user visiting the SP site and being directed to the IDP to log in. On successful authentication, the IDP sends an assertion statement about the authentication to the SP. This assertion statement attests which user the IDP authenticated, when the authentication succeeded, how long the assertion is valid, and so forth. It can optionally contain attribute values for the user who authenticated. (OpenIG can then, for example, use the attribute values to log a user into a protected application.) The assertion can optionally be signed and encrypted.

In both cases, the job of the Federation component is to validate the user and to pass the required attributes to OpenIG so that it can log the user into protected applications.

If you intend to protect multiple service provider applications first read this chapter and work through the samples. Then consider the explanation in the appendix, SAML 2.0 & Multiple Applications.

You configure the Federation component by modifying both the OpenIG config.json file and also by including Federation-specific XML files with the configuration.

The simplest way to configure the Federation component is to use the OpenAM task wizard to generate a Fedlet, and then copy the Fedlet configuration files to the correct locations. If you use the Fedlet configuration files, simply unpack Fedlet.war and copy all the files listed above into $HOME/.openig/SAML. You do not have to modify the files to do basic IDP and SP initiated SSO with OpenIG. When generating a Fedlet, know that the sample config.json templates uses /saml as the URI so your Fedlet end point should be specified as protocol://host.domain:port/saml.

If you do not use the Fedlet wizard, edit the configuration files for the unconfigured Fedlet, and then copy the Fedlet configuration files to the $HOME/.openig/SAML directory. You must still nevertheless get the metadata from the IDP, and then copy it to idp.xml in the same directory.

Once you have the Fedlet configuration files set up, add the SamlFederationHandler in the Reference object to the OpenIG configuration.

Application myportal requires a form with username and password for login. The username for myportal is the mail attribute at the user's Identity Provider. The password for myportal is the mailPassword attribute at the Identity Provider.

The incoming SAML2 assertion sent by the Identity Provider contains the mail and mailPassword attributes. The Federation component validates the incoming assertion, sets the session attributes username and password to the values of mail and mailPassword from the assertion attributes, and redirects the user to /myportal/login. A "LoginRequest" filter then retrieves the credentials and creates the form to log the user in to myportal.

The "SamlFederationHandler" configuration object looks like this:

{
    "name": "SamlFederationHandler",
    "type": "org.forgerock.openig.saml.SamlFederationHandler",
    "config": {
        "assertionMapping": {
            "username": "mail",
            "password": "mailPassword"
        },
        "redirectURI": "/myportal/login",
        "logoutURI": "/myportal/logout"
    }
}
  

The "LoginRequest" configuration object looks like this:

{
    "name": "LoginRequest",
    "type": "StaticRequestFilter",
    "config": {
        "method": "POST",
        "uri": "https://www.myportal.com/myportal/login",
        "form": {
            "username": [
                "${exchange.session.username}"
            ],
            "password": [
                "${exchange.session.password}"
            ]
        }
    }
}
  

The Identity Provider metadata must be copied to the $HOME/.openig/SAML/idp.xml directory. See the documentation for your Identity Provider for instructions on how to get the metadata.

To export Identity Provider metadata from OpenAM, either save the response from the appropriate end point, such as http://openam.example.com:8088/openam/saml2/jsp/exportmetadata.jsp, or run an ssoadm command such as the following:

$ ssoadm \
 export-entity \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --entityid http://openam.example.com:8088/openam \
 --meta-data-file /tmp/idp.xml
  

The following sections in this chapter are a tutorial on setting up OpenAM to send a SAML 2.0 assertion to OpenIG containing user credentials, and OpenIG to validate the assertion and use the credentials to log the user in to the protected application.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as you did for the chapter on Getting Started.

OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

The initial OpenIG configuration file should look like the one used to proxy requests through to the HTTP server and to capture request and response data, as you used in the chapter on Getting Started.

To test your setup, access the HTTP server home page through OpenIG at http://www.example.com:8080. Login as username george, password costanza. You should see a page showing the username and some information about the request.

In this tutorial, it is assumed that you are familiar with SAML 2.0 federation and with the components involved, including OpenAM. For OpenAM documentation, see https://backstage.forgerock.com/docs/am.

Install and configure OpenAM on http://openam.example.com:8088/openam with the default configuration. If you use a different configuration, make sure you substitute in the tutorial accordingly.

Login to the OpenAM console as administrator, and use the common task wizard to create a hosted Identity Provider. This tutorial does not address PKI configuration for validation and encryption, though OpenIG is capable of handling both when properly configured, just as any OpenAM Fedlet can handle both. Configure the Attribute Mapping to map the the mail attribute to mail and the employeenumber attribute to employeenumber. You can use the test certificate in the Identity Provider configuration for signing in this example.

Then use the common task wizard to create a Fedlet. Set the Name to OpenIG. Set the Destination URL to http://www.example.com:8080/saml. Also configure the Attribute Mapping for the Fedlet to map the the mail attribute to mail and the employeenumber attribute to employeenumber.

Why map these attributes? The SAML 2.0 attribute mapping indicates that the SP, OpenIG, wants the IDP, OpenAM in this case, to get the values of these attributes from the user profile and then send them to the SP, OpenIG. OpenIG can then use the values of the attributes, in this case mail and employeenumber, to log the user in to the application it protects.

This tutorial uses mail and employeenumber for the sake of simplicity. Both of those attributes are part of a user's profile out of the box with the default OpenAM configuration. Neither of the attributes are needed for anything else in this tutorial. So this tutorial uses mail to hold the username, and employeenumber to hold the password. In a real deployment, you would no doubt use other attributes that depend on how the real user profiles are configured.

Use the OpenAM console to create a user subject in the top level realm with Email Address george and Employee Number costanza.

Unpack the configuration files from the Fedlet you created in Section 6.8, "Configuring OpenAM". The Fedlet is packaged as a .zip file that contains a war file that in turn contains the configuration files to unpack. OpenAM displays the location of the .zip file upon successful creation of the Fedlet. If you followed the instructions above, the .zip is $HOME/openam/myfedlets/OpenIG/Fedlet.zip on the system where OpenAM runs.

$ cd $HOME/openam/myfedlets/OpenIG
$ unzip Fedlet.zip fedlet.war
$ unzip fedlet.war conf/*
$ mkdir $HOME/.openig/SAML
$ cp conf/* $HOME/.openig/SAML
$ ls -1 $HOME/.openig/SAML
FederationConfig.properties
fedlet.cot
idp-extended.xml
idp.xml
sp-extended.xml
sp.xml
  

On Windows, the SAML configuration files belong in %appdata%\OpenIG\SAML. To locate the %appdata% folder for your version of Windows, open Windows Explorer, type %appdata% as the file path, and press Enter.

Restart Jetty after preparing the SAML configuration files.

However you initiate single sign-on, you should wind up viewing the page you normally see after logging in.

What is happening behind the scenes?

The initial incoming requests matches the /federate route. As the user is not yet authenticated, the "SPInitiatedSSORedirectHandler" sends a redirect to initiate SSO.

The user authenticates with the Identity Provider for SAML 2.0 single sign-on. After authentication, the Identity Provider redirects the user-agent back to the SAML URI on the Service Provider (OpenIG), which you configured for the Fedlet as /saml. The "SamlFederationHandler" gets the request to this route. The request holds the SAML 2.0 assertion whose attributes contain credentials.

The "SamlFederationHandler" processes an incoming SAML 2.0 assertion, injecting credentials values from the assertion into the exchange session. The "SamlFederationHandler" then redirects to the /federate route.

On the /federate route, once the attributes from the assertion are set in the session, OpenIG dispatches the exchange to the "Chain". The "StaticRequestFilter" in the "Chain" uses the attribute values to replace the request with an HTTP POST of login form data to log the user in to the protected application.

OpenIG returns the response page showing that the user has logged in.

The OAuth 2.0 Authorization Framework describes a way of allowing a third-party application to access a user's resources without having the user's credentials. When resources are protected with OAuth 2.0, users can use their credentials with an OAuth 2.0-compliant identity provider, such as OpenAM, Facebook, Google and others to access the resources, rather than setting up an account with yet another third-party application.

In OAuth 2.0, there are different grant mechanisms whereby the client can obtain authorization. One grant mechanism involves the client redirecting the resource owner's browser to the authorization server to complete authentication and authorization. You might have experienced this grant mechanism yourself when logging in with your identity provider account to access a web service, rather than creating a new account directly with the web service. Whatever the grant mechanism, the client's aim is to get an OAuth 2.0 access token from the authorization server.

Access tokens are the credentials used to access protected resources. An access token is just a string that represents the authorization to access protected resources given by the authorization server. An access token, like cash, is a bearer token. This means that anyone who has the access token can use it to get the resources. Access tokens therefore must be protected, so requests involving them must go over HTTPS. The advantage of access tokens over passwords or other credentials is that access tokens can be granted and revoked without exposing the user's credentials.

When the client requests access to protected resources, it supplies the access token to the resource server housing the resources. The resource server must then validate the access token. If the access token is found to be valid, then the resource server can let the client have access to the resources.

When OpenIG acts therefore as an OAuth 2.0 resource server, its role is to validate access tokens. How an access token is validated is technically not covered in the specifications for OAuth 2.0. Typically the resource server validates an access token by submitting the token to a token information endpoint. The token information endpoint typically returns the access token, when it expires, and the OAuth 2.0 scopes associated with the token, potentially with other information. In OAuth 2.0, the token scopes are strings that can identify the scope of access authorized to the client, but can also be used for other purposes. For example, OpenAM maps them to user profile attribute values by default, and also allows custom scope handling plugins.

In the tutorial that follows, you configure OpenIG as a resource server, and use OpenAM as the OAuth 2.0 authorization server.

In the chapter on Getting Started, you learned how to configure OpenIG to proxy traffic and capture request and response data. You also learned how to configure OpenIG to use a static request to log in with hard-coded credentials.

This tutorial shows you how OpenIG can act as an OAuth 2.0 resource server, validating OAuth 2.0 access tokens and including token info in the exchange.

This tutorial relies on OpenAM as an OAuth 2.0 authorization server. As an OAuth 2.0 client of OpenAM, you get an access token. You then submit the access token to OpenIG, and OpenIG acts as the resource server.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as you did for the chapter on Getting Started.

OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

Install and configure OpenAM on http://openam.example.com:8088/openam with the default configuration. If you use a different configuration, make sure you substitute in the tutorial accordingly. Although this tutorial does not use HTTPS, you must use HTTPS to protect access tokens in production environments.

Login to the OpenAM console as administrator, and use the common task wizard, Configure OAuth2, to configure an OAuth 2.0 authorization server in / (Top Level Realm).

Also create an OAuth 2.0 Client profile in / (Top Level Realm). This allows you to request an OAuth 2.0 access token on behalf of the client. In OpenAM console, browse to Access Control > / (Top Level Realm) > Agents > OAuth 2.0 Client, and then click New in the Agent table.

Create an OAuth 2.0 client profile with name OpenIG and password password. The name is the OAuth 2.0 client_id, and the password is the client_secret.

Edit the OpenIG client profile to add mail and employeenumber scopes to the Scope(s) list, and then save your work. In this tutorial, you overload these profile settings to pass credentials to OpenIG. This tutorial uses mail and employeenumber for the sake of simplicity. Both of those attributes are part of a user's profile out of the box with the default OpenAM configuration. Neither of the attributes are needed for anything else in this tutorial. So this tutorial uses mail to hold the username, and employeenumber to hold the password. In a real deployment, you would no doubt use other attributes that depend on how the real user profiles are configured.

To configure OpenIG as an OAuth 2.0 resource server, you use an OAuth2ResourceServerFilter in the Reference.

The filter expects an OAuth 2.0 access token in an incoming Authorization request header, such as the following.

Authorization: Bearer 7af41ddd-47a4-40dc-b530-a9aa9f7ceda9
  

The filter then uses the access token to validate the token and to retrieve token information from the authorization server. On successful validation, the filter injects the response from the authorization server into the location set by the "target" in the configuration.

If no access token is present in the request, or token validation does not complete successfully, the filter returns an HTTP error status to the user-agent, and OpenIG does not continue processing the exchange. This is done as specified in the RFC, OAuth 2.0 Bearer Token Usage.

You can therefore add additional filters and handlers to the chain directly after the OAuth2ResourceServerFilter, and expect to have the access token if the filter completes successfully.

To configure OpenIG as an OAuth 2.0 resource server, add a new route to the OpenIG configuration, by including the following route configuration file as $HOME/.openig/config/routes/06-rs.json.

{
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "OAuth2ResourceServerFilter",
                    "config": {
                        "providerHandler": "ClientHandler",
                        "scopes": [
                            "mail",
                            "employeenumber"
                        ],
                        "tokenInfoEndpoint":
                            "http://openam.example.com:8088/openam/oauth2/tokeninfo",
                        "requireHttps": false,
                        "target": "${exchange.token}"
                    },
                    "timer": true
                },
                {
                    "type": "ScriptableFilter",
                    "config": {
                        "type": "application/x-groovy",
                        "source":
                            "import org.forgerock.json.fluent.JsonValue;
                             logger.info(exchange.token.asJsonValue() as String);
                             exchange.username = exchange.token.info.mail;
                             exchange.password = exchange.token.info.employeenumber;
                             next.handle(exchange)"
                    },
                    "timer": true
                },
                {
                    "type": "StaticRequestFilter",
                    "config": {
                        "method": "POST",
                        "uri": "http://www.example.com:8081",
                        "form": {
                            "username": [
                                "${exchange.username}"
                            ],
                            "password": [
                                "${exchange.password}"
                            ]
                        }
                    },
                    "timer": true
                }
            ],
            "handler": "ClientHandler"
        }
    },
    "condition": "${matches(exchange.request.uri.path, '^/rs')}",
    "timer": true
}

   

On Windows, the file name should be %appdata%\OpenIG\config\routes\06-rs.json.

To try your configuration, you need an access token. Get an access token from OpenAM and use it to access OpenIG as in the following example, which uses the OAuth 2.0 resource owner password credentials authorization grant.

$ curl \
 --user "OpenIG:password" \
 --data "grant_type=password&username=george&password=costanza&scope=mail%20employeenumber" \
 http://openam.example.com:8088/openam/oauth2/access_token
{
    "scope": "mail employeenumber",
    "expires_in": 60,
    "token_type": "Bearer",
    "refresh_token": "80963b0e-8283-434b-ba11-ce01ef0e93b6",
    "access_token": "ddf31dac-e23a-446c-bd21-db60cf19b9f3"
}

$ curl \
 --header "Authorization: Bearer ddf31dac-e23a-446c-bd21-db60cf19b9f3" \
 http://www.example.com:8080/rs
...
    <h1>User Information</h1>

    <dl>
        <dt>Username</dt>
        <dd>george</dd>
    </dl>

    <h1>Request Information</h1>

    <dl>
        <dt>Method</dt>
        <dd>POST</dd>

        <dt>URI</dt>
        <dd>/</dd>

        <dt>Headers</dt>
        <dd style="font-family: monospace; font-size: small;">...</dd>
    </dl>

  

Also look in the Jetty server output to see the access token information. The access token information looks something like the following.

TUE DEC 02 17:14:28 CET 2014 (INFO) {ScriptableFilter}/handler/config/filters/1
{
    "mail": "george",
    "employeenumber": "costanza",
    "scope": [
        "mail",
        "employeenumber"
    ],
    "grant_type": "password",
    "realm": "/",
    "token_type": "Bearer",
    "expires_in": 41,
    "access_token": "e362515f-ecf2-47b7-b1a7-c6480e705129"
}
  

What is happening behind the scenes?

After OpenIG gets the curl request, the resource server filter validates the access token with OpenAM, and injects the token information into the exchange. (If the access token was missing or invalid, then the resource server filter would have returned an error status to the user-agent. The OAuth 2.0 client would then have had to deal with the error.)

The "ScriptableFilter" logs the token information, and also extracts the credentials to inject them into the exchange. Finally the "StaticRequestFilter" uses the credentials to log the user in to the minimal HTTP server, which responds with the User Information page.

As described in the chapter, OpenIG as an OAuth 2.0 Resource Server, an OAuth 2.0 client is the third-party application that needs access to a user's protected resources. The client application therefore has the user (the OAuth 2.0 resource owner) delegate authorization by authenticating with an identity provider (the OAuth 2.0 authorization server) using an existing account, and then consenting to authorize access to protected resources (on an OAuth 2.0 resource server).

OpenIG can act as an OAuth 2.0 client when you configure an OAuth2ClientFilter in the Reference. The filter handles the process of allowing the user to select a provider, and redirecting the user through the authentication and authorization steps of an OAuth 2.0 authorization code grant, which results in the authorization server returning an access token to the filter. At the outcome of a successful authorization grant, the filter injects the access token data into a configurable target field of the exchange so that subsequent filters and handlers have access to the access token. Subsequent requests can use the access token without re-authentication.

If the protected application is an OAuth 2.0 resource server, then OpenIG can send the access token with the resource request.

The specifications available through the OpenID Connect site describe an authentication layer built on OAuth 2.0, which is OpenID Connect 1.0.

OpenID Connect 1.0 is a specific implementation of OAuth 2.0 where the identity provider holds the protected resource that the third-party application aims to access. This resource is the UserInfo, information about the authenticated end-user expressed in a standard format.

When OpenIG acts therefore as an OpenID Connect 1.0 relying party, its ultimate role is to retrieve user information from the OpenID provider, and then to inject that information into the exchange for use by subsequent filters and handlers.

In the tutorial that follows, you configure OpenIG as a relying party, and use OpenAM as the OpenID Provider.

In the chapter on Getting Started, you learned how to configure OpenIG to proxy traffic and capture request and response data. You also learned how to configure OpenIG to use a static request to log in with hard-coded credentials.

This tutorial shows you how OpenIG can act as an OpenID Connect 1.0 relying party.

This tutorial relies on OpenAM as an OpenID Provider. As a relying party, OpenIG takes the end user to OpenAM for authorization and an access token. It then uses the access token to get end user information from OpenAM.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as you did for the chapter on Getting Started.

OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

Install and configure OpenAM on http://openam.example.com:8088/openam with the default configuration. If you use a different configuration, make sure you substitute in the tutorial accordingly. Although this tutorial does not use HTTPS, you must use HTTPS to protect access tokens and user information in production environments.

Login to the OpenAM console as administrator, and use the common task wizard, Configure OAuth2, to configure an OAuth 2.0 authorization server in / (Top Level Realm). This also configures OpenAM as an OpenID Provider.

Also create an OAuth 2.0 Client profile in / (Top Level Realm). This allows OpenIG to communicate with OpenAM as an OAuth 2.0 client. In OpenAM console, browse to Access Control > / (Top Level Realm) > Agents > OAuth 2.0 Client, and then click New in the Agent table.

Create an OAuth 2.0 client profile with name OpenIG and password password. The name is the "clientId" value, and the password is the "clientSecret" value that you use in the provider configuration in OpenIG.

Edit the OpenIG client profile to add the Redirection URI http://www.example.com:8080/openid/callback. Also add openid and profile scopes to the Scope(s) list, and then save your work.

In this tutorial, you overload the profile settings to pass credentials to OpenIG. This tutorial uses Full Name and Last Name for the sake of simplicity. Both of those attributes are part of a user's profile out of the box with the default OpenAM configuration. Neither of the attributes are needed for anything else in this tutorial. So this tutorial uses Last Name to hold the username, and Full Name to hold the password. In a real deployment, you would no doubt use other attributes, depending upon the user profiles and on your requirements.

To configure OpenIG as an OpenID Connect 1.0 relying party, add a new route to the OpenIG configuration, by including the following route configuration file as $HOME/.openig/config/routes/07-openid.json.

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "OAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/openid",
            "requireHttps": false,
            "requireLogin": true,
            "target": "${exchange.openid}",
            "scopes": [
              "openid",
              "profile"
            ],
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "comment": "Trivial failure handler for debugging only",
                "status": 500,
                "reason": "Error",
                "entity": "${exchange.openid}"
              }
            },
            "providerHandler": "ClientHandler",
            "providers": [
              {
                "name": "openam",
                "wellKnownConfiguration":
                    "http://openam.example.com:8088/openam/.well-known/openid-configuration",
                "clientId": "OpenIG",
                "clientSecret": "password"
              }
            ]
          }
        }
      ],
      "handler": {
        "type": "Chain",
        "config": {
          "filters": [
            {
              "type": "StaticRequestFilter",
              "config": {
                "method": "POST",
                "uri": "http://www.example.com:8081",
                "form": {
                  "username": [
                    "${exchange.openid.user_info.family_name}"
                  ],
                  "password": [
                    "${exchange.openid.user_info.name}"
                  ]
                }
              }
            }
          ],
          "handler": "ClientHandler"
        }
      }
    }
  },
  "condition": "${matches(exchange.request.uri.path, '^/openid')}",
  "baseURI": "http://www.example.com:8080"
}

  

On Windows, the file name should be %appdata%\OpenIG\config\routes\07-openid.json.

To try your configuration, browse to OpenIG at http://www.example.com:8080/openid.

When redirected to the OpenAM login page, login as user george, password costanza, and then allow the application access to user information.

If successful, OpenIG logs you into the minimal HTTP server as George Costanza, and the minimal HTTP server returns George's page.

What is happening behind the scenes?

After OpenIG gets the browser request, the "OAuth2ClientFilter" redirects you to authenticate with OpenAM and consent to authorize access to user information. After you authorize access, OpenAM returns an access token to the filter.

The filter then uses that access token to get the user information. The filter injects the authorization state information into exchange.openid. The outermost chain then calls its handler, which as another "Chain".

This inner chain uses the credentials to log the user in to the minimal HTTP server, which responds with its User Information page.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as you did for the chapter on Getting Started.

OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

You start therefore with a default route

When you set up the first tutorial, you configured a Router.

The Router is a handler that you can configure in the top-level config.json file for OpenIG, and in fact wherever you can configure a Handler. For the first tutorial, you added a Router as part of the base configuration, which is shown here again in the following listing.

{
    "handler": {
        "type": "Router",
        "audit": "global",
        "capture": "all"
    },
    "heap": [
        {
            "name": "LogSink",
            "type": "ConsoleLogSink",
            "config": {
                "level": "DEBUG"
            }
        },
        {
            "name": "JwtSession",
            "type": "JwtSession"
        },
        {
            "name": "ClientHandler",
            "type": "ClientHandler"
        },
        {
            "name": "capture",
            "type": "CaptureDecorator",
            "config": {
                "captureEntity": true,
                "_captureExchange": true
            }
        }
    ],
    "baseURI": "http://www.example.com:8081"
}

  

The Router's job is to pass the exchange to a route that matches a condition, and to periodically reload changed route configurations. As routes define the conditions on which they accept any given Exchange, the Router does not have to know about specific Routes in advance. In other words, you can configure the Router first and then add routes while OpenIG is running, as you have done in other tutorials.

The configuration shown above passes all Exchanges to the Router using the default settings, meaning that the Router monitors $HOME/.openig/config/routes for Routes. When OpenIG receives a request, if more time has passed than the default scan interval of 10 seconds, then OpenIG rescans the Routes directory for changes and reloads any Routes changes it finds.

Routes are configurations to handle an Exchange that meets a specified condition.

The condition is defined using a OpenIG expression in the Reference, so it can be based on almost any characteristic of the Exchange or even of the OpenIG runtime environment. Another way to think of the Route is like an independent DispatchHandler in the Reference.

Routes can also have their own names, used to order them lexicographically. If no name is specified, the Route file name is used. Route file names have the extension .json. In other words, a router only scans for files with the .json extension, and ignores files with other extensions.

Routes can have a base URI to change the scheme, host, and port of the request.

Routes wrap a heap of configuration objects, and hand off any Exchange they accept to a handler. In this way each Route is much like its own server-wide configuration file.

If no condition is specified for the Route, the Route accepts any Exchange. The following is a basic default route that accepts any Exchange and forwards it on without changes.

{
    "name": "default",
    "handler": {
        "type": "ClientHandler"
    }
}
  

At this point you can try your new route configurations.

Browse to the .com URL: http://www.example.com:8080/?site=com.

You should see the ForgeRock.com page.

Browse to the .org URL: http://www.example.com:8080/?site=org.

You should see the ForgeRock.org Community page.

Now browse to the base URL to see that the default route still works: http://www.example.com:8080/.

What happened behind the scenes?

When you issued your first request with "?site=com", the request matched the condition defined in the ForgeRock.com route. OpenIG rebased the request and sent it along to http://forgerock.com:80/.

When you issued your second request with "?site=org", the request matched the condition defined in the ForgeRock.org Community route. OpenIG rebased the request and sent it along to http://forgerock.org:80/.

When the third request did not match any of the conditions defined, the Exchange was routed to the default Route (that accepts any Exchange). The static request filter returned the default page.

At this point, tinker with your route configurations without stopping OpenIG, and notice that changes are picked up every 10 seconds.

Having the Route configurations automatically reloaded is great in the lab, but is perhaps not what you want in production.

In that case, stop the server, edit the Router "scanInterval", and restart. When "scanInterval" is set to -1, the Router only loads routes at startup.

{
    "name": "Router",
    "type": "Router",
    "config": {
        "scanInterval": -1
    }
}
  

You can also change the file system location to look for routes.

{
    "name": "Router",
    "type": "Router",
    "config": {
        "directory": "/path/to/safe/routes",
        "scanInterval": -1
    }
}
  

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

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, with a "DispatchHandler" to change the scheme to HTTPS on login. Simply change the "baseURI" to that of the target application, and login to the application. This template references a "ClientHandler" defined in config.json.

{
    "handler": {
        "type": "DispatchHandler",
        "config": {
            "bindings": [
                {
                    "condition": "${exchange.request.uri.scheme == 'http'}",
                    "handler": "ClientHandler",
                    "baseURI": "http://TARGETIP"
                },
                {
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": "ClientHandler",
                    "baseURI": "https://TARGETIP"
                },
                {
                    "handler": "ClientHandler",
                    "baseURI": "https://TARGETIP"
                }
            ]
        }
    },
    "capture": "all"
}

   

Logs the user into the target application with hard-coded user name and password. This template intercepts the login page request and replaces it with the login form.

{
    "handler": {
        "type": "DispatchHandler",
        "config": {
            "bindings": [
                {
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": {
                        "type": "Chain",
                        "config": {
                            "filters": [
                                {
                                    "type": "StaticRequestFilter",
                                    "config": {
                                        "method": "POST",
                                        "uri": "https://TARGETIP/login",
                                        "form": {
                                            "USER": [
                                                "MY_USERNAME"
                                            ],
                                            "PASSWORD": [
                                                "MY_PASSWORD"
                                            ]
                                        }
                                    }
                                }
                            ],
                            "handler": "ClientHandler"
                        }
                    },
                    "baseURI": "http://TARGETIP"
                },
                {
                    "handler": "ClientHandler",
                    "baseURI": "http://TARGETIP"
                }
            ]
        }
    }
}

   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of your application. Also change MY_USERNAME and MY_PASSWORD, and adapt the "StaticRequestFilter" for your application. This template references a "ClientHandler" defined in config.json.

For applications that expect a cookie from the login page to be sent in the login request form. This templates allows the login page request to go through to the target, intercepts the response, then creates the login form and adds the intercepted cookie to the POST.

{
    "heap": [
        {
            "name": "DispatchHandler",
            "type": "DispatchHandler",
            "config": {
                "bindings": [
                    {
                        "condition": "${exchange.request.uri.path == '/eum/login'}",
                        "handler": {
                            "type": "Chain",
                            "config": {
                                "filters": [
                                    {
                                        "type": "SwitchFilter",
                                        "config": {
                                            "onResponse": [
                                                {
                                                    "handler": "LoginRequestHandler"
                                                }
                                            ]
                                        }
                                    }
                                ],
                                "handler": "ClientHandler"
                            }
                        },
                        "baseURI": "http://TARGETIP"
                    },
                    {
                        "handler": "ClientHandler",
                        "baseURI": "http://TARGETIP"
                    }
                ]
            }
        },
        {
            "name": "LoginRequestHandler",
            "type": "Chain",
            "config": {
                "filters": [
                    {
                        "type": "StaticRequestFilter",
                        "config": {
                            "method": "POST",
                            "uri": "https://TARGETIP/login",
                            "form": {
                                "USER": [
                                    "MY_USERNAME"
                                ],
                                "PASSWORD": [
                                    "MY_PASSWORD"
                                ]
                            },
                            "headers": {
                                "cookie": [
                                    "${exchange.response.headers['Set-Cookie'][0]}"
                                ]
                            }
                        }
                    }
                ],
                "handler": "ClientHandler"
            }
        }
    ],
    "handler": "DispatchHandler"
}

   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of your application. Also change MY_USERNAME and MY_PASSWORD, and adapt the "StaticRequestFilter" for your application. This template references a "ClientHandler" defined in config.json.

For applications that return the login page when the user tries to access a page without a valid session. This template shows how to use the "ExtractFilter" to find the login page on the response and use the "CookieFilter" to ensure the cookies from the application are replayed on each request. The sample application in this template is OpenAM.

{
    "heap": [
        {
            "name": "DispatchHandler",
            "type": "DispatchHandler",
            "config": {
                "bindings": [
                    {
                        "handler": {
                            "type": "Chain",
                            "config": {
                                "filters": [
                                    "IsLoginPage",
                                    {
                                        "type": "EntityExtractFilter",
                                        "config": {
                                            "messageType": "response",
                                            "target": "${exchange.isLoginPage}",
                                            "bindings": [
                                                {
                                                    "key": "found",
                                                    "pattern": "OpenAM\s\(Login\)",
                                                    "template": "true"
                                                }
                                            ]
                                        }
                                    }
                                ],
                                "handler": "OutgoingChain"
                            }
                        },
                        "baseURI": "http://TARGETIP:PORT"
                    }
                ]
            }
        },
        {
            "name": "IsLoginPage",
            "type": "SwitchFilter",
            "config": {
                "onResponse": [
                    {
                        "condition": "${exchange.isLoginPage.found == 'true'}",
                        "handler": {
                            "type": "Chain",
                            "config": {
                                "filters": [
                                    {
                                        "type": "StaticRequestFilter",
                                        "config": {
                                            "method": "POST",
                                            "uri":
                                                "http://TARGETIP:PORT/openam/UI/Login",
                                            "form": {
                                                "IDToken0": [
                                                    ""
                                                ],
                                                "IDToken1": [
                                                    "MY_USERNAME"
                                                ],
                                                "IDToken2": [
                                                    "MY_PASSWORD"
                                                ],
                                                "IDButton": [
                                                    "Log+In"
                                                ],
                                                "encoded": [
                                                    "false"
                                                ]
                                            },
                                            "headers": {
                                                "host": [
                                                    "TARGETFQDN:PORT"
                                                ]
                                            }
                                        }
                                    }
                                ],
                                "handler": "OutgoingChain"
                            }
                        }
                    }
                ]
            }
        },
        {
            "name": "OutgoingChain",
            "type": "Chain",
            "config": {
                "filters": [
                    {
                        "type": "CookieFilter"
                    }
                ],
                "handler": {
                    "type": "ClientHandler"
                }
            }
        }
    ],
    "handler": "DispatchHandler"
}
   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of OpenAM, TARGETFQDN with the fully qualified domain name of OpenAM, and PORT with the port on which OpenAM listens. Also change MY_USERNAME and MY_PASSWORD to match those of your OpenAM user. This template references a "ClientHandler" defined in config.json.

Extracts a hidden value from the login page and includes it in the login form POSTed to the target application.

{
    "handler": {
        "type": "DispatchHandler",
        "config": {
            "bindings": [
                {
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": {
                        "name": "LoginChain",
                        "type": "Chain",
                        "config": {
                            "filters": [
                                {
                                    "type": "EntityExtractFilter",
                                    "config": {
                                        "messageType": "response",
                                        "target": "${exchange.hiddenValue}",
                                        "bindings": [
                                            {
                                                "key": "value",
                                                "pattern":
                                                    "wpLoginToken\"\\s.*value=\"(.*)\"",
                                                "template": "$1"
                                            }
                                        ]
                                    }
                                },
                                {
                                    "type": "StaticRequestFilter",
                                    "config": {
                                        "method": "POST",
                                        "uri": "https://TARGETIP/login",
                                        "form": {
                                            "USER": [
                                                "MY_USERNAME"
                                            ],
                                            "PASSWORD": [
                                                "MY_PASSWORD"
                                            ],
                                            "hiddenValue": [
                                                "${exchange.hiddenValue.value}"
                                            ]
                                        }
                                    }
                                }
                            ],
                            "handler": "ClientHandler"
                        }
                    },
                    "baseURI": "http://TARGETIP"
                },
                {
                    "handler": "ClientHandler",
                    "baseURI": "http://TARGETIP"
                }
            ]
        }
    }
}

   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of your application. Also change MY_USERNAME and MY_PASSWORD, and adapt the "StaticRequestFilter" for your application. This template references a "ClientHandler" defined in config.json.

Proxies traffic to an application listening on ports 80 and 443. The assumption is the application uses HTTPS for authentication and HTTP for the general application features. Assuming all login requests go to port 443, you must add the login filters and handlers to the "Chain".

{
    "handler": {
        "type": "DispatchHandler",
        "config": {
            "bindings": [
                {
                    "condition": "${exchange.request.uri.scheme == 'http'}",
                    "handler": "ClientHandler",
                    "baseURI": "http://TARGETIP"
                },
                {
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": {
                        "type": "Chain",
                        "config": {
                            "filters": [
                                "MY_FILTERS"
                            ],
                            "handler": "ClientHandler"
                        }
                    },
                    "baseURI": "https://TARGETIP"
                },
                {
                    "handler": "ClientHandler",
                    "baseURI": "https://TARGETIP"
                }
            ]
        }
    }
}

   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of your application. Also add the necessary filter configurations that are required for login with your application, and then change MY_FILTERS to identify the added filters. This template references a "ClientHandler" defined in config.json.

Logs the user into the target application using the headers passed down from an OpenAM policy agent. This template assumes the user name and password are passed down by the OpenAM policy agent as headers. 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.

{
    "handler": {
        "type": "DispatchHandler",
        "config": {
            "bindings": [
                {
                    "condition": "${exchange.request.uri.path == '/login'}",
                    "handler": {
                        "type": "Chain",
                        "config": {
                            "filters": [
                                {
                                    "type": "StaticRequestFilter",
                                    "config": {
                                        "method": "POST",
                                        "uri": "https://TARGETIP/login",
                                        "form": {
                                            "USER": [
                                                "${exchange.request.headers['username'][0]}"
                                            ],
                                            "PASSWORD": [
                                                "${exchange.request.headers['password'][0]}"
                                            ]
                                        }
                                    }
                                }
                            ],
                            "handler": "ClientHandler"
                        }
                    },
                    "baseURI": "http://TARGETIP"
                },
                {
                    "handler": "ClientHandler",
                    "baseURI": "http://TARGETIP"
                }
            ]
        }
    }
}

   

This template is a replacement for the default route, $HOME/.openig/config/routes/99-default.json, Substitute TARGETIP with the IP address of your application. Also adapt the "StaticRequestFilter" for your application. This template references a "ClientHandler" defined in config.json.

Logs the user into Microsoft Online Outlook Web Access (OWA). This template shows how you would use OpenIG and the OpenAM password capture feature to integrate with OWA. You can follow the chapter on Getting Login Credentials From OpenAM, and substitute this template as a replacement for the default route.

{
  "heap": [
    {
      "name": "DispatchHandler",
      "type": "DispatchHandler",
      "config": {
        "bindings": [
          {
            "condition": "${exchange.request.uri.path == '/owa/auth/logon.aspx'}",
            "handler": {
              "type": "Chain",
              "config": {
                "filters": [
                  {
                    "type": "CryptoHeaderFilter",
                    "config": {
                      "messageType": "REQUEST",
                      "operation": "DECRYPT",
                      "algorithm": "DES/ECB/NoPadding",
                      "key": "DESKEY",
                      "keyType": "DES",
                      "charSet": "utf-8",
                      "headers": [
                        "password"
                      ]
                    }
                  },
                  {
                    "type": "StaticRequestFilter",
                    "config": {
                      "method": "POST",
                      "uri": "https://65.55.171.158/owa/auth/owaauth.dll",
                      "headers": {
                        "Host": [
                          "red001.mail.microsoftonline.com"
                        ],
                        "Content-Type": [
                          "Content-Type:application/x-www-form-urlencoded"
                        ]
                      },
                      "form": {
                        "destination": [
                          "https://red001.mail.microsoftonline.com/owa/"
                        ],
                        "forcedownlevel": [
                          "0"
                        ],
                        "trusted": [
                          "0"
                        ],
                        "username": [
                          "${exchange.request.headers['username'][0]}"
                        ],
                        "password": [
                          "${exchange.request.headers['password'][0]}"
                        ],
                        "isUtf8": [
                          "1"
                        ]
                      }
                    }
                  }
                ],
                "handler": "OutgoingChain"
              }
            },
            "baseURI": "https://65.55.171.158"
          },
          {
            "handler": "OutgoingChain",
            "baseURI": "https://65.55.171.158"
          }
        ]
      }
    },
    {
      "name": "OutgoingChain",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "type": "HeaderFilter",
            "config": {
              "messageType": "REQUEST",
              "remove": [
                "password",
                "username"
              ]
            }
          }
        ],
        "handler": {
          "type": "ClientHandler"
        }
      }
    }
  ],
  "handler": "DispatchHandler"
}

   

Change DESKEY to the actual key value that you generated when following the instructions in Configuring Password Capture. This template references a "ClientHandler" defined in config.json.

You add these Filters and Handlers to your configuration in the same way as for other Filters and Handlers. Each takes as its configuration the script's Internet media "type" and either a "source" script included in the JSON configuration, or a "file" script that OpenIG reads from a file. The configuration can also optionally supply "args" in order to pass parameters to the script.

The following example defines a ScriptableFilter, written in the Groovy language, and stored in a file named $HOME/.openig/scripts/groovy/SimpleFormLogin.groovy (%appdata%\OpenIG\scripts\groovy\SimpleFormLogin.groovy on Windows).

 {
     "name": "SimpleFormLogin",
     "type": "ScriptableFilter",
     "config": {
         "type": "application/x-groovy",
         "file": "SimpleFormLogin.groovy"
     }
 }
  

Relative paths in the "file" field depend on how OpenIG is installed. If OpenIG is installed in an application server, then paths for Groovy scripts are relative to $HOME/.openig/scripts/groovy.

This base location $HOME/.openig/scripts/groovy is on the classpath when the scripts are executed. If therefore some Groovy scripts are not in the default package, but instead have their own package names, they belong in the directory corresponding to their package name. For example, a script in package com.example.groovy belongs under $HOME/.openig/scripts/groovy/com/example/groovy/.

OpenIG provides scripts with several global variables at run time, enabling them to access the Exchange, to store variables across executions, to write messages to the logs, and to make requests to a web service or to an LDAP directory service, in addition to Groovy's built-in functionality. For details, see the reference documentation for ScriptableFilter in the Reference and ScriptableHandler in the Reference.

This chapter demonstrates some of what you might do using scripts.

If you want to try these scripts, first install and configure OpenIG as described in the chapter on Getting Started.

When developing and debugging your scripts, consider configuring a CaptureDecorator in the Reference to log requests, responses, and the exchange data in JSON form. You can then turn off capturing when you move to production.

In order to route requests, especially when the conditions are complicated, you can use a ScriptableHandler instead of a DispatchHandler in the Reference.

The following script demonstrates a simple dispatch handler.

import org.forgerock.openig.http.Response

/*
 * This simplistic dispatcher matches the path part of the HTTP request.
 * If the path is /login, it checks Username and Password headers,
 * accepting bjensen:hifalutin, and returning HTTP 403 Forbidden to others.
 * Otherwise it returns HTTP 401 Unauthorized.
 */

// Rather than get the response from an external source,
// this handler produces the response itself.
exchange.response = new Response();

switch (exchange.request.uri.path) {

    case "/login":

        if (exchange.request.headers.Username[0] == "bjensen" &&
                exchange.request.headers.Password[0] == "hifalutin") {

            exchange.response.status = 200
            exchange.response.entity = "<html><p>Welcome back, Babs!</p></html>"

        } else {

            exchange.response.status = 403
            exchange.response.entity = "<html><p>Authorization required</p></html>"

        }

        break

    default:

        exchange.response.status = 401
        exchange.response.entity = "<html><p>Please <a href='./login'>log in</a>.</p></html>"

        break

}

  

To try this handler, save the script as $HOME/.openig/scripts/groovy/DispatchHandler.groovy (%appdata%\OpenIG\scripts\groovy\DispatchHandler.groovy on Windows).

Next, add the following route to your configuration as $HOME/.openig/config/routes/98-dispatch.json (%appdata%\OpenIG\config\routes\98-dispatch.json on Windows).

{
    "heap": [
        {
            "name": "DispatchHandler",
            "type": "DispatchHandler",
            "config": {
                "bindings": [
                    {
                        "condition":
                            "${matches(exchange.request.uri.path, '^/login')}",
                        "handler": {
                            "type": "Chain",
                            "config": {
                                "filters": [
                                    {
                                        "type": "HeaderFilter",
                                        "config": {
                                            "messageType": "REQUEST",
                                            "add": {
                                                "Username": [
                                                    "bjensen"
                                                ],
                                                "Password": [
                                                    "hifalutin"
                                                ]
                                            }
                                        }
                                    }
                                ],
                                "handler": "Dispatcher"
                            }
                        }
                    },
                    {
                        "handler": "Dispatcher"
                    }
                ]
            }
        },
        {
            "name": "Dispatcher",
            "type": "ScriptableHandler",
            "config": {
                "type": "application/x-groovy",
                "file": "DispatchHandler.groovy"
            }
        }
    ],
    "handler": "DispatchHandler"
}

  

The route sets up the headers required by the script when the user logs in.

To try it out, browse to http://www.example.com:8080.

The response from the script says Please log in. When you click the "log in" link, the "HeaderFilter" sets Username and Password headers in the request, and passes the request to the script.

The script then responds, Welcome back, Babs!

HTTP Basic authentication calls for the user agent such as a browser to send a user name and password to the server in an Authorization header. HTTP Basic authentication relies on an encrypted connection to protect the user name and password credentials, which are base64-encoded in the Authorization header, not encrypted.

The following script, for use in a ScriptableFilter, adds an Authorization header based on a username and password combination.

/*
 * Perform basic authentication with the user name and password
 * that are supplied using a configuration like the following:
 *
 * {
 *     "name": "BasicAuth",
 *     "type": "ScriptableFilter",
 *     "config": {
 *         "type": "application/x-groovy",
 *         "file": "BasicAuthFilter.groovy",
 *         "args": {
 *             "username": "bjensen",
 *             "password": "hifalutin"
 *             }
 *         }
 * }
 */

def userPass = username + ":" + password
def base64UserPass = userPass.getBytes().encodeBase64()
exchange.request.headers.add("Authorization", "Basic ${base64UserPass}" as String)

// Credentials are only base64-encoded, not encrypted: Set scheme to HTTPS.

/*
 * When connecting over HTTPS, by default the client tries to trust the server.
 * If the server has no certificate
 * or has a self-signed certificate unknown to the client,
 * then the most likely result is an SSLPeerUnverifiedException.
 *
 * To avoid an SSLPeerUnverifiedException,
 * set up HTTPS correctly on the server.
 * Either use a server certificate signed by a well-known CA,
 * or set up the gateway to trust the server certificate.
 */
exchange.request.uri.scheme = "https"

// Call the next handler. This returns when the request has been handled.
next.handle(exchange)

  

To try this filter, save the script as $HOME/.openig/scripts/groovy/BasicAuthFilter.groovy (%appdata%\OpenIG\scripts\groovy\BasicAuthFilter.groovy on Windows).

Next, add the following route to your configuration as $HOME/.openig/config/routes/09-basic.json (%appdata%\OpenIG\config\routes\09-basic.json on Windows).

{
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "ScriptableFilter",
                    "config": {
                        "type": "application/x-groovy",
                        "file": "BasicAuthFilter.groovy",
                        "args": {
                            "username": "bjensen",
                            "password": "hifalutin"
                        }
                    },
                    "capture": "filtered_request"
                }
            ],
            "handler": {
                "type": "StaticResponseHandler",
                "config": {
                    "status": 200,
                    "reason": "OK",
                    "entity": "Hello, Babs!"
                }
            }
        }
    },
    "condition": "${matches(exchange.request.uri.path, '^/basic')}"
}

  

When the request path matches /basic the route calls the "Chain", which runs the "ScriptableFilter". The "capture" setting captures the request as updated by the "ScriptableFilter". Finally, OpenIG returns a static page.

To try it out, browse to http://www.example.com:8080/basic.

The captured request in the console log shows that the "scheme" is now HTTPS, and that the "Authorization" header is set for HTTP Basic.

GET https://www.example.com:8080/basic HTTP/1.1
Authorization: Basic YmplbnNlbjpoaWZhbHV0aW4=
  

Many organizations use an LDAP directory service to store user profiles including authentication credentials. The LDAP directory service securely stores user passwords in a highly-available, central service capable of handling thousands of authentications per second.

The following script, for use in a ScriptableFilter, performs simple authentication against an LDAP server based on request form fields username and password.

import org.forgerock.opendj.ldap.*
import org.forgerock.openig.http.Response

/*
 * Perform LDAP authentication based on user credentials from a form.
 *
 * If LDAP authentication succeeds, then call the next handler.
 * If there is a failure, send a response back to the user.
 */

username = exchange.request.form?.username[0]
password = exchange.request.form?.password[0]

// For testing purposes, the LDAP host and port are provided in the exchange.
// Edit as needed to match your directory service.
host = exchange.ldapHost ?: "localhost"
port = exchange.ldapPort ?: 1389

client = ldap.connect(host, port as Integer)
try {

    // Assume the username is an exact match of either
    // the user ID, the email address, or the user's full name.
    filter = "(|(uid=%s)(mail=%s)(cn=%s))"

    user = client.searchSingleEntry(
            "ou=people,dc=example,dc=com",
            ldap.scope.sub,
            ldap.filter(filter, username, username, username))

    client.bind(user.name as String, password?.toCharArray())

    // Authentication succeeded.

    // Set a header (or whatever else you want to do here).
    exchange.request.headers.add("Ldap-User-Dn", user.name)

    // Most LDAP attributes are multi-valued.
    // When you read multi-valued attributes, use the parse() method,
    // with an AttributeParser method
    // that specifies the type of object to return.
    exchange.cn = user.cn?.parse().asSetOfString()

    // When you write attribute values, set them directly.
    user.description = "New description set by my script"

    // Here is how you might read a single value of a multi-valued attribute:
    exchange.description = user.description?.parse().asString()

    // Call the next handler. This returns when the request has been handled.
    next.handle(exchange)

} catch (AuthenticationException e) {

    // LDAP authentication failed, so fail the exchange with
    // HTTP status code 403 Forbidden.

    exchange.response = new Response()
    exchange.response.status = 403
    exchange.response.reason = e.message
    exchange.response.entity = "<html><p>Authentication failed: " + e.message + "</p></html>"

} catch (Exception e) {

    // Something other than authentication failed on the server side,
    // so fail the exchange with HTTP 500 Internal Server Error.

    exchange.response = new Response()
    exchange.response.status = 500
    exchange.response.reason = e.message
    exchange.response.entity = "<html><p>Server error: " + e.message + "</p></html>"

} finally {
    client.close()
}

  

For the list of methods to specify which type of objects to return, see the OpenDJ LDAP SDK Javadoc for AttributeParser.

To try this out, first install an LDAP directory server such as ForgeRock Directory Services or OpenDJ directory server. Also import some sample users who can authenticate over LDAP. With OpenDJ, you can generate sample users at installation time.

Next, save the script as $HOME/.openig/scripts/groovy/LdapAuthFilter.groovy (%appdata%\OpenIG\scripts\groovy\LdapAuthFilter.groovy on Windows). If the directory server installation does not match the assumptions made in the script, adjust the script to use the correct settings for your installation.

Finally, add the following route to your configuration as $HOME/.openig/config/routes/10-ldap.json (%appdata%\OpenIG\config\routes\10-ldap.json on Windows).

{
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "ScriptableFilter",
                    "config": {
                        "type": "application/x-groovy",
                        "file": "LdapAuthFilter.groovy"
                    }
                }
            ],
            "handler": {
                "type": "ScriptableHandler",
                "config": {
                    "type": "application/x-groovy",
                    "source":
                        "import org.forgerock.openig.http.Response;
                         dn = exchange.request.headers['Ldap-User-Dn'][0];
                         entity = '<html><p>Ldap-User-Dn: ' + dn + '</p></html>';

                         exchange.response = new Response();
                         exchange.response.status = 200;
                         exchange.response.entity = entity;"
                }
            }
        }
    },
    "condition": "${matches(exchange.request.uri.path, '^/ldap')}"
}
  

The route calls the "LdapAuthFilter.groovy" script to authenticate the user over LDAP. On successful authentication, it responds with the the bind DN.

To try it out, browse to a URL where query string parameters specify a valid username and password, such as http://www.example.com:8080/ldap?username=user.0&password=password.

The response from the script shows the DN: Ldap-User-Dn: uid=user.0,ou=People,dc=example,dc=com.

You can use a ScriptableFilter to look up information in a relational database and include the results in the Exchange.

The following filter looks up user credentials in a database given the user's email address, which is found in the form data of the request. The script then sets the credentials in headers, making sure the scheme is HTTPS to protect the request when it leaves OpenIG.

/*
 * Look up user credentials in a relational database
 * based on the user's email address provided in the request form data,
 * and set the credentials in the exchange headers for the next handler.
 */

def client = new SqlClient()
def credentials = client.getCredentials(exchange.request.form?.mail[0])
exchange.request.headers.add("Username", credentials.Username)
exchange.request.headers.add("Password", credentials.Password)

// The credentials are not protected in the headers, so use HTTPS.
exchange.request.uri.scheme = "https"

// Call the next handler. This returns when the request has been handled.
next.handle(exchange)

  

The previous script demonstrates a ScriptableFilter that uses a SqlClient class defined in another script. The following code listing shows the SqlClient class.

import groovy.sql.Sql

import javax.naming.InitialContext
import javax.sql.DataSource

/**
 * Access a database with a well-known structure,
 * in particular to get credentials given an email address.
 */
class SqlClient {

    // Get a DataSource from the container.
    InitialContext context = new InitialContext()
    DataSource dataSource = context.lookup("jdbc/forgerock") as DataSource
    def sql = new Sql(dataSource)

    // The expected table is laid out like the following.

    // Table USERS
    // ----------------------------------------
    // | USERNAME  | PASSWORD |   EMAIL   |...|
    // ----------------------------------------
    // | <username>| <passwd> | <mail@...>|...|
    // ----------------------------------------

    String tableName = "USERS"
    String usernameColumn = "USERNAME"
    String passwordColumn = "PASSWORD"
    String mailColumn = "EMAIL"

    /**
     * Get the Username and Password given an email address.
     *
     * @param mail Email address used to look up the credentials
     * @return Username and Password from the database
     */
    def getCredentials(mail) {
        def credentials = [:]
        def query = "SELECT " + usernameColumn + ", " + passwordColumn +
                " FROM " + tableName + " WHERE " + mailColumn + "='$mail';"

        sql.eachRow(query) {
            credentials.put("Username", it."$usernameColumn")
            credentials.put("Password", it."$passwordColumn")
        }
        return credentials
    }
}

  

To try this out, first follow the tutorial on Login With Credentials From a Database. When everything in that tutorial works, you know that OpenIG can connect to the database, lookup users by email address, and successfully authenticate to the sample application.

Next, save the scripts as $HOME/.openig/scripts/groovy/SqlAccessFilter.groovy (%appdata%\OpenIG\scripts\groovy\SqlAccessFilter.groovy on Windows), and as $HOME/.openig/scripts/groovy/SqlClient.groovy (%appdata%\OpenIG\scripts\groovy\SqlClient.groovy on Windows).

Finally, add the following route to your configuration as $HOME/.openig/config/routes/11-db.json (%appdata%\OpenIG\config\routes\11-db.json on Windows).

{
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "ScriptableFilter",
                    "config": {
                        "type": "application/x-groovy",
                        "file": "SqlAccessFilter.groovy"
                    }
                },
                {
                    "type": "StaticRequestFilter",
                    "config": {
                        "method": "POST",
                        "uri": "http://www.example.com:8081",
                        "form": {
                            "username": [
                                "${exchange.request.headers['Username'][0]}"
                            ],
                            "password": [
                                "${exchange.request.headers['Password'][0]}"
                            ]
                        }
                    }
                }
            ],
            "handler": "ClientHandler"
        }
    },
    "condition": "${matches(exchange.request.uri.path, '^/db')}"
}

  

The route calls the "ScriptableFilter" to look up credentials over SQL. It then uses calls a "StaticRequestFilter" to build a login request. Although the script sets the scheme to HTTPS, the "StaticRequestFilter" ignores that and resets the URI. This is to make it easier for you to try this out, without having to worry about setting up HTTPS.

To try it out, browse to a URL where a query string parameter specifies a valid email address, such as http://www.example.com:8080/db?mail=george@example.com.

If the lookup and authentication are successful, you see the profile page of the sample application.

If scripting is not enough, be aware that OpenIG includes a complete Java application programming interface, designed to allow you to customize OpenIG as required. Customizing OpenIG can be used to perform complex server interactions or intensive data transformations that you cannot achieve with scripts or existing handlers, filters and expressions in the Reference.

These Filter and Handler interfaces are similar to Java Enterprise Edition Filter and Servlet interfaces, with some differences in the semantics of messages. While you can simply implement these interfaces, OpenIG also provides convenience classes: GenericFilter and GenericHandler.

The Filter interface exposes a filter() method, which takes an Exchange object and the Chain of remaining filters and handler to dispatch to. Initially, exchange.request contains the request to be filtered. To pass the request to the next filter or handler in the chain, the filter calls next.handle(exchange). After this call, exchange.response contains the response that can be filtered.

A filter might elect not to pass the request to the next filter or handler, and instead handle the request itself. It can achieve this by merely avoiding a call to next.handle(exchange) and creating its own response object in the exchange. The filter is also at liberty to replace a response with another of its own. A filter can exist in more than one chain, therefore should make no assumptions or correlations using the chain it is supplied. The only valid use of a chain by a filter is to call its handle() method to dispatch the exchange to the rest of the chain.

The Handler interface exposes a handle() method, which takes an Exchange object. It processes the request in exchange.request and produces a response in exchange.response. A handler can elect to dispatch the exchange to another handler or chain.

Objects are added to the heap and supplied with configuration artifacts at initialization time. To be integrated with the configuration, a class must have an accompanying implementation of the Heaplet interface. The easiest and most common way of exposing the heaplet is to extend the GenericHeaplet class in a nested class of the class you want to create and initialize, overriding the heaplet's create method.

Within the create method, you can access the object's configuration through the config field.

The following sample filter sets an arbitrary header in the incoming request and outgoing response.

package org.forgerock.openig.doc;

import org.forgerock.openig.filter.GenericFilter;
import org.forgerock.openig.handler.Handler;
import org.forgerock.openig.handler.HandlerException;
import org.forgerock.openig.heap.GenericHeaplet;
import org.forgerock.openig.heap.HeapException;
import org.forgerock.openig.http.Exchange;

import java.io.IOException;

/**
 * Filter to set a header in the incoming request and in the outgoing response.
 */
public class SampleFilter extends GenericFilter {

    /** Header name. */
    String name;

    /** Header value. */
    String value;

    /**
     * Set a header in the incoming request and in the outgoing response.
     * A configuration example looks something like the following.
     *
     * <pre>
     * {
     *     "name": "SampleFilter",
     *     "type": "SampleFilter",
     *     "config": {
     *         "name": "X-Greeting",
     *         "value": "Hello world"
     *     }
     * }
     * </pre>
     *
     * @param exchange          Wraps request and response.
     * @param next              Next filter or handler in the chain.
     * @throws HandlerException Failure when handling the exchange.
     * @throws IOException      I/O exception when handling the exchange.
     */
    @Override
    public void filter(Exchange exchange, Handler next)
            throws HandlerException, IOException {

        // Set header in the request.
        exchange.request.getHeaders().putSingle(name, value);

        // Pass to the next filter or handler in the chain.
        next.handle(exchange);

        // Set header in the response.
        exchange.response.getHeaders().putSingle(name, value);
    }

    /**
     * Create and initialize the filter, based on the configuration.
     * The filter object is stored in the heap.
     */
    public static class Heaplet extends GenericHeaplet {

        /**
         * Create the filter object in the heap,
         * setting the header name and value for the filter,
         * based on the configuration.
         *
         * @return                  The filter object.
         * @throws HeapException    Failed to create the object.
         */
        @Override
        public Object create() throws HeapException {

            SampleFilter filter = new SampleFilter();
            filter.name  = config.get("name").required().asString();
            filter.value = config.get("value").required().asString();

            return filter;
        }
    }
}

When you set the sample filter "type" in the configuration, you need to provide the fully qualified class name, as in "type": "org.forgerock.openig.doc.SampleFilter". You can however implement a class alias resolver to make it possible to use a short name instead, as in "type": "SampleFilter".

package org.forgerock.openig.doc;

import org.forgerock.openig.alias.ClassAliasResolver;

import java.util.HashMap;
import java.util.Map;

/**
 * Allow use of short name aliases in configuration object types.
 *
 * This allows a configuration with {@code "type": "SampleFilter"}
 * instead of {@code "type": "org.forgerock.openig.doc.SampleFilter"}.
 */
public class SampleClassAliasResolver implements ClassAliasResolver {

    private static final Map<String, Class<?>> ALIASES =
            new HashMap<String, Class<?>>();

    static {
        ALIASES.put("SampleFilter", SampleFilter.class);
    }

    /**
     * Get the class for a short name alias.
     *
     * @param alias Short name alias.
     * @return      The class, or null if the alias is not defined.
     */
    @Override
    public Class<?> resolve(String alias) {
        return ALIASES.get(alias);
    }
}

When you add your own resolver, you must make it discoverable within your custom library. You do this by adding a services file named after the class resolver interface, where the file contains the fully qualified class name of your resolver, under META-INF/services/org.forgerock.openig.alias.ClassAliasResolver in the jar file for your customizations. When you have more than one resolver, add one fully qualified class name per line. If you build your project using Maven, then you can add this under the src/main/resources directory. The content of the file in this example is one line:

org.forgerock.openig.doc.SampleClassAliasResolver
  

The corresponding heap object configuration then looks as follows.

{
    "name": "SampleFilter",
    "type": "SampleFilter",
    "config": {
        "name": "X-Greeting",
        "value": "Hello world"
    }
}
  

You can use Apache Maven to manage dependencies on OpenIG. The dependencies are found in the ForgeRock Maven repository.

The following listing shows the Maven POM configuration for the ForgeRock Maven repository and the dependency to build the sample Filter.

  <repositories>
    <repository>
      <id>forgerock-staging-repository</id>
      <name>ForgeRock Release Repository</name>
      <url>http://maven.forgerock.org/repo/releases</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>forgerock-snapshots-repository</id>
      <name>ForgeRock Snapshot Repository</name>
      <url>http://maven.forgerock.org/repo/snapshots</url>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>org.forgerock.openig</groupId>
      <artifactId>openig-core</artifactId>
      <version>3.1.0</version>
    </dependency>
  </dependencies>

  

You can then build your customizations into a jar file and install them in your local Maven repository by using the mvn install command.

$ mvn install
...
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ sample-filter ---
[INFO] Building jar: .../sample-filter/target/sample-filter-1.0.0-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.478s
[INFO] Finished at: Fri Nov 07 16:57:18 CET 2014
[INFO] Final Memory: 18M/309M
[INFO] ------------------------------------------------------------------------

  

After building your customizations into a jar file, you can include them in the OpenIG war file for deployment. You do this by unpacking OpenIG-3.1.0.war, including your jar library in WEB-INF/lib, and then creating a new war file.

For example, if your jar file is in a project named sample-filter, and the development version is 1.0.0-SNAPSHOT, you might include the file as in the following example.

$ mkdir root && cd root
$ jar -xf ~/Downloads/OpenIG-3.1.0.war
$ cp ~/Documents/sample-filter/target/sample-filter-1.0.0-SNAPSHOT.jar WEB-INF/lib
$ jar -cf ../custom.war *
  

In this example, the resulting custom.war contains the custom sample filter. You can deploy the custom war file as you would deploy OpenIG-3.1.0.war.

org.forgerock.json.fluent.JsonValueException: /handler:
   object Router2 not found in heap
    at org.forgerock.openig.heap.HeapImpl.resolve(HeapImpl.java:351)
    at org.forgerock.openig.heap.HeapImpl.resolve(HeapImpl.java:334)
    at org.forgerock.openig.heap.HeapImpl.getHandler(HeapImpl.java:538)
  

You have specified "handler": "Router2" in config.json, but no handler configuration object named "Router2" exists. Make sure you have added an entry for the handler and that you have correctly spelled its name.

HTTP ERROR 500

Problem accessing /wp/wp-login.php. Reason:

    Server Error

Caused by:

    org.forgerock.openig.handler.HandlerException: no handler to dispatch to
  

A better description of the error appears as an error in the console log:

  
TUE DEC 02 17:35:57 CET 2014 (ERROR) {Router}/handler
The route defined in file '/Users/me/.openig/config/routes/route1.json'
 cannot be added
------------------------------
TUE DEC 02 17:35:57 CET 2014 (ERROR) {Router}/handler
Cannot read/parse content of /Users/me/.openig/config/routes/route1.json
[            HeapException] > Cannot read/parse content of
                              /Users/me/.openig/config/routes/route1.json
[       JsonParseException] > Unexpected character (',' (code 44)):
                              was expecting double-quote to start field name
 at [Source: java.io.InputStreamReader@4c8d1091; line: 4, column: 28]
  

In this case, extra comma is spotted at line 4, column 28.

Use a JSON editor or JSON validation tool such as JSONLint to make sure your JSON is valid.

Ensure the flat file is readable by the user running the container for OpenIG. Values are all characters, including space and tabs, between the separator, so make sure the values are not padded with spaces.

HTTP ERROR 500

Problem accessing /myURL . Reason:

java.lang.String cannot be cast to java.util.List
Caused by:
java.lang.ClassCastException: java.lang.String cannot be cast to java.util.List
  

This error is typically encountered when using the AssignmentFilter in the Reference and setting a string value for one of the Headers. All headers are stored in Lists so the header must be addressed with a subscript.

For example, if you try to set exchange.request.headers['Location'] for a redirect in the response object, you should instead set exchange.request.headers['Location'][0]. A header without a subscript leads to the error above.

You must define an entity for the response as in the following example.

{
    "name": "AccessDeniedHandler",
    "type": "StaticResponseHandler",
    "config": {
        "status": 403,
        "reason": "Forbidden",
        "entity": "<html><p>User does not have permission</p></html>"
    }
}
  

If you are proxying to more than one application in multiple DNS domains, you must make sure your container is enabled for domain cookies. For details on your specific container, see the section on Configuring Deployment Containers.

If a "baseURI" configuration setting causes a request to come back to OpenIG, OpenIG never produces a response to the request. You then observe the following behavior.

You send a request and OpenIG seems to hang. Then you see a failure message, HTTP Status 500 - Read timed out, accompanied by OpenIG throwing an exception, java.net.SocketTimeoutException: Read timed out.

To fix this issue, make sure that "baseURI" configuration settings do not cause requests to come back to OpenIG.

OpenIG loads all configuration at startup. By default, it then periodically reloads changed route configurations.

If you make changes to a route that result in an invalid configuration, OpenIG logs errors, but it keeps the previous, correct configuration, and continues to use the old route.

OpenIG only uses the new configuration after you save a valid version or when you restart OpenIG.

Of course, if you restart OpenIG with an invalid route configuration, then OpenIG tries to load the invalid route at startup and logs an error. In that case, if there is no default handler to accept any incoming exchange for the invalid route, then you see an error, No handler to dispatch to.

If you have copied routes from another OpenIG server, those routes might depend on environment or container configuration that you have not yet configured locally.

You can work around this problem by changing the route file extension. A router ignores route files that do not have the .json extension.

For example, suppose you copy route all sample route configurations from the documentation, and then start OpenIG without first configuring your container. This can result in an error such as the following.

org.forgerock.json.fluent.JsonValueException:
 /handler/config/filters/0/config/dataSource:
 javax.naming.NameNotFoundException;
 remaining name 'jdbc/forgerock'
  at org.forgerock.openig.servlet.GatewayServlet.init(GatewayServlet.java:222)
  at org.eclipse.jetty.servlet.ServletHolder.initServlet(ServletHolder.java:595)
  at org.eclipse.jetty.servlet.ServletHolder.getServlet(ServletHolder.java:458)
  at org.eclipse.jetty.servlet.ServletHolder.handle(ServletHolder.java:724)
   

This arises from the route in 03-sql.json, which defines an "SqlAttributesFilter" that depends on a JNDI data source configured in the container.

{
    "type": "SqlAttributesFilter",
    "config": {
        "dataSource": "java:comp/env/jdbc/forgerock",
        "preparedStatement":
          "SELECT username, password FROM users WHERE email = ?;",
        "parameters": [
            "george@example.com"
        ],
        "target": "${exchange.credentials}"
    }
}
  

To prevent OpenIG from loading the route configuration until you have had time to configure the container, change the file extension to render the route inactive.

$ mv ~/.openig/config/routes/03-sql.json ~/.openig/config/routes/03-sql.inactive
  

If necessary, restart the container to force OpenIG to reload the configuration.

When you have configured the data source in the container, change the file extension back to .json to render the route active again.

$ mv ~/.openig/config/routes/03-sql.inactive ~/.openig/config/routes/03-sql.json