Most organizations have valuable existing services that are not easily integrated into newer architectures. These existing services cannot often be changed. Many client applications cannot communicate as they lack a gateway to bridge the gap. Figure 1.1, "Missing Gateway" illustrates one example of a missing gateway.

Figure 1.1. Missing Gateway

OpenIG works as an HTTP gateway, also known as a reverse proxy. OpenIG is deployed on a network so it can intercept both client requests and server responses. Figure 1.2, "OpenIG Deployed" illustrates a OpenIG deployment.

Figure 1.2. OpenIG Deployed

Clients interact with protected servers through OpenIG. OpenIG can be configured to add new capabilities to existing services without affecting current clients or servers.

OpenIG supports these capabilities as out of the box configuration options. Once you understand the essential concepts covered in this chapter, try the additional instructions in this guide to use OpenIG to add other features.

OpenIG handles HTTP requests and responses in user-defined chains, making it possible to manage and to monitor processing at any point in a chain. The OpenIG object model provides both access to the requests and responses that pass through each chain, and also context information associated with each request.

Contexts provide information about the client making the request, the session, the authentication or authorization identity of the principal, and any other state information associated with the request. Contexts provide a means to access state information throughout the duration of the HTTP session between the client and protected application, including when this involves interaction with additional services.

The configuration for OpenIG is stored in flat files, which are mainly in JavaScript Object Notation (JSON) format.^[1] Configure OpenIG by editing the JSON files.

When installation is complete, add at least one configuration file. Each configuration file holds a JSON object, which specifies a handler to process the request. A handler is an object responsible for producing a response to a request. Every route must call a handler.

The following very simple configuration routes requests to be handled according to separate route configurations:

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

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, declare the object in the heap. The heap is a collection of named configuration objects that can be referenced by their names from elsewhere in the configuration.

The following example declares a reusable router object and references it by its name, as follows:

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

Notice that the heap takes an array. Because the heap holds configuration objects all at the same level, you can impose any hierarchy or order that you like when referencing objects. Note that 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 a ClientHandler object that OpenIG uses to connect to servers. The following ClientHandler configuration uses defaults for all settings, except hostnameVerifier, which it configures to verify host names in SSL certificates:

{
    "name": "ClientHandler",
    "type": "ClientHandler",
    "config": {
        "hostnameVerifier": "STRICT"
    }
}
  

Decorators are additional heap objects that let you extend what another object can do. For example, a CaptureDecorator extends the capability of filters and handlers to log requests and responses. A TimerDecorator logs processing times. Decorate configuration objects with decorator names as field names. By default OpenIG defines both a CaptureDecorator named capture and also a TimerDecorator named timer. Log requests, responses, and processing times by adding decorations as shown in the following example:

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

OpenIG also creates additional utility objects with default settings, including ClientHandler, LogSink, and TemporaryStorage. These objects can be referenced by name and do not need to be configured unless they are needed to override the default configurations.

Routes are configuration objects whose behavior is triggered when their conditions are matched. Routes 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.

Use routing where OpenIG protects multiple services or multiple and different endpoints of the same service. Routing is also used when processing a request involves multiple steps, because the client must be redirected to authenticate with an identity provider before accessing the service.

As illustrated in Section 1.3, "The Configuration" a router manages the routes in its file system directory, periodically reloading changed routes unless it is configured to load them only at startup.

A router does not explicitly specify any routes. Instead the router specifies a directory where route configuration files are found, or uses the default directory. Routes specify their own condition, which is an expression that evaluates to true, false, or null. If a route condition is true, then the route handles the request.

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

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

If the route has no condition, or if the value of the condition is null, then the route matches any request. Furthermore, OpenIG orders routes lexicographically by file 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 by 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.

Figure 1.3, "Flow Inside a Chain" shows the flow inside a chain with 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 response comes back from the handler.

Figure 1.3. Flow Inside a Chain

The route configuration in Example 1.1, "Chain Without an External Service" demonstrates the flow through a chain that does not call 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>"
                }
            }
        }
    }
}
  

Example 1.1, "Chain Without an External Service" explained how a chain processes a request and its context. Example 1.2, "Requests and Responses in a Chain" illustrates the HTTP requests and responses captured as they flow through the chain.

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

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

### Captured outgoing response (inside OpenIG)
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>
  

The JSON format does not specify a notation for comments. If OpenIG does not recognize a JSON field name, it ignores the field. As a result, it is possible to use comments in configuration files.

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

Make sure you have a supported Java Development Kit installed. For details, see Section 2.1, "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 a sample application to protect, it is time to 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.

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.

Restart Jetty to take the configuration changes into account.

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:8081/, 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 as described in FileLogSink(5) in the Configuration Reference, rather than a ConsoleLogSink.

The baseURI decoration 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 go 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.

Figure 2.1, "Log in With Hard-Coded Credentials" shows the steps.

Figure 2.1. Log in With Hard-Coded Credentials

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

For the full list of supported containers see Section 2.2, "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"
    

<context-param>
  <param-name>org.eclipse.jetty.servlet.SessionDomain</param-name>
  <param-value>.example.com</param-value>
</context-param>

    

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 context, or retrieves locally from the OpenIG server system. If information is retrieved locally, then consider setting up failover. 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 context 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(5) in the Configuration 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 a context 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 truststore to trust server certificates. The Java environment default truststore 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 and a TrustManager, and optionally, a KeyManager to reference when configuring an ClientHandler to enable OpenIG to trust servers when acting as a client.

The KeyStore holds the servers' certificates or the CA's 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 keystore when the server must authenticate OpenIG as client. The ClientHandler references whatever TrustManager and KeyManager you configure.

You can configure each of these either globally, for the OpenIG server, or 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 Keystore 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 ClientHandler configuration references MyTrustManager and sets strict host name verification:

{
    "name": "ClientHandler",
    "type": "ClientHandler",
    "config": {
        "hostnameVerifier": "STRICT",
        "trustManager": "MyTrustManager"
    }
}
  

You can use a JSON Web Token (JWT) session, JwtSession, to configure OpenIG as described in JwtSession(5) in the Configuration Reference. A JwtSession stores 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 keystore. The following steps describe how to prepare the keystore for JWT encryption:

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as shown in Chapter 2, "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 uses a FileAttributesFilter to look up the credentials.

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. Log in With Credentials From a File

OpenIG intercepts your browser's HTTP GET request. The request matches the new route configuration. The PasswordReplayFilter's FileAttributesFilter looks up credentials in a file, and stores the credentials it finds in the request context attributes map. The PasswordReplayFilter's request pulls the credentials out of the attributes map, 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. Log in With Credentials From a Database

OpenIG intercepts your browser's HTTP GET request. The request matches the new route configuration. The PasswordReplayFilter's SqlAttributesFilter looks up credentials in H2, and stores the credentials it finds in the request context attributes map. The PasswordReplayFilter's request pulls the credentials out of the attributes map, 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 into 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.

Figure 5.1. Log in With Credentials Captured by OpenAM

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 and OpenAM policy agent documentation, see https://backstage.forgerock.com/docs/am.

In access management, a policy enforcement point (PEP) intercepts requests for a resource, provides information about the request to a policy decision point (PDP), and then grants or denies access to the resource based on the policy decision. The policy decision point determines whether to allow a request based on the information that puts the request in context. The policy decision is made based on authorization policies that apply depending on the context for the request.

OpenAM allows the administrator to maintain centralized, fine-grained, declarative policies describing who can access what resources, and under what conditions access is authorized. OpenAM evaluates access decisions based on applicable policies, which can be managed by OpenAM realm, and by OpenAM application.

OpenAM provides a REST API for authorized users to request policy decisions. OpenIG provides a PolicyEnforcementFilter that uses the REST API.

You configure OpenIG to use a PolicyEnforcementFilter to protect resources based on OpenAM policies. For reference information about the filter, see PolicyEnforcementFilter(5) in the Configuration Reference.

This tutorial shows you how OpenIG can act as a PEP, requesting policy decisions from OpenAM as a PDP. You add an OpenIG route that does the following:

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as described in Chapter 2, "Getting Started".

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

Now proceed to Section 6.3, "Setting Up OpenAM As a PDP".

OpenAM must have at least one policy that applies to requests to make policy decisions allowing access to resources. For OpenIG to request policy decisions, it must use the credentials of a user with the privilege to do so. This section describes what policy to create, and how to prepare a user who can request policy decisions.

Now proceed to Section 6.4, "Setting Up OpenIG As a PEP".

To configure OpenIG as a PEP, use a PolicyEnforcementFilter as described in PolicyEnforcementFilter(5) in the Configuration Reference.

Include the following route configuration file as $HOME/.openig/config/routes/04-pep.json:

{
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${request.cookies['iPlanetDirectoryPro'] == null}",
          "handler": {
            "type": "StaticResponseHandler",
            "config": {
              "status": 302,
              "reason": "Found",
              "headers": {
                "Location": [
                  "http://openam.example.com:8088/openam/XUI/#login/&goto=${urlEncode(contexts.router.originalUri)}"
                ]
              },
              "entity": "Redirecting to OpenAM..."
            }
          }
        },
        {
          "comment": "This condition is optional, but included for clarity.",
          "condition": "${request.cookies['iPlanetDirectoryPro'] != null}",
          "handler": {
            "type": "Chain",
            "config": {
              "filters": [
                {
                  "type": "PolicyEnforcementFilter",
                  "config": {
                    "openamUrl": "http://openam.example.com:8088/openam/",
                    "pepUsername": "policyAdmin",
                    "pepPassword": "password",
                    "ssoTokenSubject": "${request.cookies['iPlanetDirectoryPro'][0].value}"
                  }
                }
              ],
              "handler": "ClientHandler"
            }
          }
        }
      ]
    }
  },
  "condition": "${matches(request.uri.path, '^/pep') and not contains(request.uri.path, 'not-enforced')}"
}

   

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

Now proceed to Section 6.5, "Test the Setup".

To try your configuration, first log out of OpenAM. Then try the following:

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 Appendix A, "SAML 2.0 and 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 wizard to generate a Fedlet, and then copy the Fedlet configuration files to the correct locations. The wizard is accessible from the Common Tasks page in the console for OpenAM 12 and earlier, and from the Dashboard for the realm in OpenAM 13 and later.

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 a SamlFederationHandler as described in SamlFederationHandler(5) in the Configuration Reference 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": "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": [
                "${session.username}"
            ],
            "password": [
                "${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 described in Chapter 2, "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 described in Chapter 2, "Getting Started".

To test your setup, access the HTTP server home page through OpenIG at http://www.example.com:8080. Log in 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 details, read the documentation for your version of OpenAM.

However you initiate SSO, 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 IDP for SAML 2.0 SSO. After authentication, the IDP redirects the user-agent back to the SAML URI on the SP (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 session context. 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 request 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.

Chapter 2, "Getting Started" describes 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.

You will learn how OpenIG can act as an OAuth 2.0 resource server, validating OAuth 2.0 access tokens and including token info in the context.

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 described in Chapter 2, "Getting Started".

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

Edit config.json to make sure that the CaptureDecorator also captures the context. After you make the changes, the object declaration appears as follows:

{
    "name": "capture",
    "type": "CaptureDecorator",
    "config": {
        "captureEntity": true,
        "captureContext": true
    }
}
  

Restart Jetty for the changes to take effect. This allows you to view the token information that OpenAM returns.

To configure OpenIG as an OAuth 2.0 resource server, you use an OAuth2ResourceServerFilter as described in OAuth2ResourceServerFilter(5) in the Configuration 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 request. This is done as specified in the RFC, OAuth 2.0 Bearer Token Usage.

You can 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": "${attributes.token}"
                    },
                    "capture": "filtered_request",
                    "timer": true
                },
                {
                    "type": "AssignmentFilter",
                    "config": {
                        "onRequest": [
                            {
                                "target": "${session.username}",
                                "value": "${attributes.token.info.mail}"
                            },
                            {
                                "target": "${session.password}",
                                "value": "${attributes.token.info.employeenumber}"
                            }
                        ]
                    },
                    "timer": true
                },
                {
                    "type": "StaticRequestFilter",
                    "config": {
                        "method": "POST",
                        "uri": "http://www.example.com:8081",
                        "form": {
                            "username": [
                                "${session.username}"
                            ],
                            "password": [
                                "${session.password}"
                            ]
                        }
                    },
                    "timer": true
                }
            ],
            "handler": "ClientHandler"
        }
    },
    "condition": "${matches(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": 3599,
    "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 token information injected into attributes.token. The token information looks something like the following:

{
    "token": {
        "token": "ddf31dac-e23a-446c-bd21-db60cf19b9f3",
        "info": {
            "access_token": "ddf31dac-e23a-446c-bd21-db60cf19b9f3",
            "employeenumber": "costanza",
            "mail": "george",
            "grant_type": "password",
            "scope": [
                "employeenumber",
                "mail"
            ],
            "realm": "/",
            "token_type": "Bearer",
            "expires_in": 3585
        },
        "scopes": [
            "employeenumber",
            "mail"
        ],
        "expiresAt": 1449663614998
    }
}
  

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 context. (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.)

OpenIG captures the token information into the log, and the AssignmentFilter injects the credentials into the session context. 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 Chapter 8, "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 as described in OAuth2ClientFilter(5) in the Configuration 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 in the context so that subsequent filters and handlers have access to the access token. Subsequent requests can use the access token without reauthentication.

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

Chapter 2, "Getting Started" describes 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 described in Chapter 2, "Getting Started".

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

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:

{
  "heap": [
    {
      "comment": "To reuse issuers, configure them in the parent route",
      "name": "openam",
      "type": "Issuer",
      "config": {
        "wellKnownEndpoint":
          "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
      }
    },
    {
      "comment": "To reuse client registrations, configure them in the parent route",
      "name": "OidcRelyingParty",
      "type": "ClientRegistration",
      "config": {
        "clientId": "OpenIG",
        "clientSecret": "password",
        "issuer": "openam",
        "redirect_uris": [
          "http://www.example.com:8080/openid/callback"
        ],
        "scopes": [
          "openid",
          "profile"
        ]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "OAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/openid",
            "requireHttps": false,
            "requireLogin": true,
            "target": "${attributes.openid}",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "comment": "Trivial failure handler for debugging only",
                "status": 500,
                "reason": "Error",
                "entity": "${attributes.openid}"
              }
            },
            "registration": "OidcRelyingParty"
          }
        }
      ],
      "handler": {
        "type": "Chain",
        "config": {
          "filters": [
            {
              "type": "StaticRequestFilter",
              "config": {
                "method": "POST",
                "uri": "http://www.example.com:8081",
                "form": {
                  "username": [
                    "${attributes.openid.user_info.family_name}"
                  ],
                  "password": [
                    "${attributes.openid.user_info.name}"
                  ]
                }
              }
            }
          ],
          "handler": "ClientHandler"
        }
      }
    }
  },
  "condition": "${matches(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 attributes.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.

OpenID Connect defines mechanisms for discovering and dynamically registering with an identity provider that is not known in advance. These mechanisms are specified in OpenID Connect Discovery and OpenID Connect Dynamic Client Registration. OpenIG supports discovery and dynamic registration. In this section you will learn how to configure OpenIG to try these features with OpenAM.

Although this tutorial focuses on OpenID Connect dynamic registration, OpenIG also supports dynamic registration as described in RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol.

This section covers the role OpenIG plays as UMA resource server.

10.1.1. About UMA

User-Managed Access (UMA) Profile of OAuth 2.0 defines a workflow that allows resource owners to share their protected resources with requesting parties. Figure 10.1, "UMA Workflow" illustrates the relationships where OpenIG protects the resource server.

Figure 10.1. UMA Workflow

The actions that form the UMA workflow are as follows:

1. Manage

The resource owner manages their resources on the resource server.

When using OpenIG to protect the resources, OpenIG creates the resource sets that describe what the resource owner shares. Resource set registration is covered in OAuth 2.0 Resource Set Registration.

2. Protect

The resource owner links their resource server and chosen authorization server, such as OpenAM.

The authorization server provides a protection API so that the resource server can register sets of resources. Use of the protection API requires a protection API token (PAT), an OAuth 2.0 token with scope uma_protection.

3. Control

The resource owner controls who has access to their registered resources by creating policies on the authorization server.

Only a resource owner can create policies for their registered resources.

4. Authorize

The client, acting on behalf of the requesting party, uses the authorization server's authorization API to acquire a requesting party token (RPT). The requesting party or client may need further interaction with the authorization server at this point, for example, to supply identity claims. Use of the authorization API requires an authorization API token (AAT), an OAuth 2.0 token with scope uma_authorization.

5. Access

The client presents the RPT to the resource server, which verifies its validity with the authorization server and, if both valid and containing sufficient permissions, returns the protected resource to the requesting party.

This section covers preparation to complete before configuring OpenIG as an UMA resource server.

This tutorial relies on OpenAM as an authorization server for OAuth 2.0 and for UMA, and the minimal HTTP server for resources to protect, and for files that serve as a basic UMA client. OpenAM 13 and later can function as an UMA authorization server.

Before you start this tutorial, prepare OpenIG and the minimal HTTP server as described in Chapter 2, "Getting Started".

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

This tutorial uses api.example.com as the domain. Add api.example.com as an alias for the OpenIG network address. For example, if traffic to OpenIG goes through the loopback address, edit the line in your hosts file to add the additional domain:

127.0.0.1    www.example.com    api.example.com

Edit config.json to comment the baseURI decoration in the top-level handler for OpenIG configuration. After you make the changes, the handler declaration appears as follows:

{
    "handler": {
        "type": "Router",
        "audit": "global",
        "_baseURI": "http://www.example.com:8081",
        "capture": "all"
    }
}
  

Restart Jetty for the changes to take effect. This allows you to view the token information that OpenAM returns.

Now proceed to Section 10.3, "Setting Up OpenAM As an Authorization Server".

When finished, log out of OpenAM and proceed to Section 10.4, "Setting Up OpenIG As an UMA Resource Server".

This section covers configuring OpenIG as an UMA resource server.

This section demonstrates OpenIG acting as an UMA resource server.

What is happening behind the scenes?

The first page is the client that simulates Alice sharing resources. The output shown in the page lets you see the PAT Alice gets, the metadata for the resource set Alice registers through OpenIG, the result of Alice authenticating with OpenAM in order to create a policy, and the successful result {} when Alice creates the policy.

The second page is the client that simulates Bob accessing a resource. The output shown on the page lets you see the ticket returned initially, the AAT that Bob gets to obtain the RPT, the RPT Bob gets in order to request the resource again, and the final response containing the body of the resource.

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",
        "baseURI": "http://www.example.com:8081",
        "capture": "all"
    },
    "heap": [
        {
            "name": "LogSink",
            "type": "ConsoleLogSink",
            "config": {
                "level": "DEBUG"
            }
        },
        {
            "name": "JwtSession",
            "type": "JwtSession"
        },
        {
            "name": "capture",
            "type": "CaptureDecorator",
            "config": {
                "captureEntity": true,
                "_captureContext": true
            }
        }
    ]
}

  

The Router's job is to pass the request and context 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 request, 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 the tutorials.

The configuration shown above passes all requests 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 a request that meets a specified condition.

The condition is defined using an OpenIG expression as described in Expressions(5) in the Configuration Reference. It can be based on almost any characteristic of the request, context, or even of the OpenIG runtime environment. Another way to think of the Route is like an independent DispatchHandler as described in DispatchHandler(5) in the Configuration Reference.

The following example shows a condition setting. With this condition on a route, the route matches all requests that have api.example.com as the host portion of the URI:

"condition": "${request.uri.host == 'api.example.com'}"
  

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 request 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 request. The following is a basic default route that accepts any request and forwards it on without changes:

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

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 Chapter 2, "Getting Started", then you already proxy and capture both the application requests coming in and the server responses going out.

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

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

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

   

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

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

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

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

   

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

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

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

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

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

   

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

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

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

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

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

   

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

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

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

Welcome, demo!
  

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

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

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

   

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

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

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

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

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

   

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

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

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

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

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

   

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

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

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

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

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

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

   

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

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

Scriptable filters and handlers are added to the configuration in the same way as standard 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 optionally supply arguments 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 request and the context, 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. Scripts can also access responses returned in promise callback methods. For details, see ScriptableFilter(5) in the Configuration Reference and ScriptableHandler(5) in the Configuration Reference.

Before trying the scripts shown in this chapter, first install and configure OpenIG as described in Chapter 2, "Getting Started".

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

For details, see CaptureDecorator(5) in the Configuration Reference.

In order to route requests, especially when the conditions are complicated, you can use a ScriptableHandler instead of a DispatchHandler as described in DispatchHandler(5) in the Configuration Reference.

The following script demonstrates a simple dispatch handler:

import org.forgerock.http.protocol.Response
import org.forgerock.http.protocol.Status

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

// Rather than return a Promise of a response from an external source,
// this script returns the response itself.
response = new Response();

switch (request.uri.path) {

    case "/mylogin":

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

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

        } else {

            response.status = Status.FORBIDDEN
            response.entity = "<html><p>Authorization required</p></html>"

        }

        break

    default:

        response.status = Status.UNAUTHORIZED
        response.entity = "<html><p>Please <a href='./mylogin'>log in</a>.</p></html>"

        break

}

// Return the locally created response, no need to wrap it into a Promise
return response


  

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(request.uri.path, '/mylogin')}",
                        "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()
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.
 */
request.uri.scheme = "https"

// Calls the next Handler and returns a Promise of the Response.
// The Response can be handled with asynchronous Promise callbacks.
next.handle(context, request)

  

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(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.http.protocol.Response
import org.forgerock.http.protocol.Status

/*
 * Perform LDAP authentication based on user credentials from a form.
 *
 * If LDAP authentication succeeds, then return a promise to handle the response.
 * If there is a failure, produce an error response and return it.
 */

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

// For testing purposes, the LDAP host and port are provided in the context's attributes.
// Edit as needed to match your directory service.
host = attributes.ldapHost ?: "localhost"
port = attributes.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).
    request.headers.add("Ldap-User-Dn", user.name.toString())

    // 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.
    attributes.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:
    attributes.description = user.description?.parse().asString()

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

} catch (AuthenticationException e) {

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

    response = new Response()
    response.status = Status.FORBIDDEN
    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 response with HTTP 500 Internal Server Error.

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

} finally {
    client.close()
}

// Return the locally created response, no need to wrap it into a Promise
return response

   

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

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

To test the configuration, 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 request context.

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 request headers for the next handler.
 */

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

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

// Calls the next Handler and returns a Promise of the Response.
// The Response can be handled with asynchronous Promise callbacks.
next.handle(context, request)

  

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
    }
}

  

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 makes it easier to try the script without additional steps to set up HTTPS.

To try the configuration, 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 addition to scripting scripting, OpenIG includes a complete Java application programming interface, designed to allow you to customize OpenIG as required. You can customize OpenIG to perform complex server interactions or intensive data transformations that you cannot achieve with scripts or existing handlers, filters and expressions described in Expressions(5) in the Configuration Reference.

Interface Stability: Evolving (For details, see Section A.2, "ForgeRock Product Interface Stability" in the Configuration Reference.)

These Filter and Handler interfaces are similar to Java Enterprise Edition Filter and Servlet interfaces, with some differences in the semantics of messages. OpenIG also provides the convenience class, GenericHeapObject, to help with configuration.

The Filter interface exposes a filter() method, which takes a Context, a Request, and the Handler, which is the next filter or handler to dispatch to. The filter() method returns a Promise that provides access to the Response with methods for dealing with both success and failure conditions.

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(context, request), creating its own response object and returning that in the promise. 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 request to the rest of the chain.

The Handler interface exposes a handle() method, which takes a Context, and a Request. It processes the request and returns a Promise that provides access to the Response with methods for dealing with both success and failure conditions. A handler can elect to dispatch the request 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.services.context.Context;
import org.forgerock.http.Filter;
import org.forgerock.http.Handler;
import org.forgerock.http.protocol.Request;
import org.forgerock.http.protocol.Response;
import org.forgerock.openig.heap.GenericHeapObject;
import org.forgerock.openig.heap.GenericHeaplet;
import org.forgerock.openig.heap.HeapException;
import org.forgerock.util.promise.NeverThrowsException;
import org.forgerock.util.promise.Promise;
import org.forgerock.util.promise.ResultHandler;

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

    /** 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 context           Execution context.
     * @param request           HTTP Request.
     * @param next              Next filter or handler in the chain.
     * @return A {@code Promise} representing the response to be returned to the client.
     */
    @Override
    public Promise<Response, NeverThrowsException> filter(final Context context,
                                                          final Request request,
                                                          final Handler next) {

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

        // Pass to the next filter or handler in the chain.
        return next.handle(context, request)
                // When it has been successfully executed, execute the following callback
                .thenOnResult(new ResultHandler<Response>() {
                    @Override
                    public void handleResult(final Response response) {
                        // Set header in the response.
                        response.getHeaders().put(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<>();

    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>4.0.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-4.0.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-4.0.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-4.0.0.war.

To limit access rates by throttling requests, use a throttling filter. This section demonstrates how a throttling filter works. For details, see ThrottlingFilter(5) in the Configuration Reference.

The following example route uses a throttling filter to limit the number of requests to 60 requests per minute from clients at the same network address:

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "config": {
            "rate": {
              "numberOfRequests": 60,
              "duration": "1 minute"
            },
            "partitionKey": "${contexts.client.remoteAddress}"
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "reason": "OK",
          "entity": "Success!"
        }
      }
    }
  },
  "condition": "${matches(request.uri.path, '^/limited')}"
}

  

Before you try this route, prepare OpenIG and the minimal HTTP server as shown in Chapter 2, "Getting Started".

Add the route file to the OpenIG configuration as $HOME/.openig/config/routes/00-throttle.json (on Windows, %appdata%\OpenIG\config\routes\00-throttle.json).

With the route in place and OpenIG running, access the route in a loop until you reach the limit. The URL for the route is http://www.example.com:8080/limited. You can use a command-line tool such as curl to access the route multiple times, as in the following example:

$ curl -v http://www.example.com:8080/limited/\[001-100\] > /tmp/curl.txt 2>&1
$ grep "< HTTP/1.1" /tmp/curl.txt | sort | uniq -c

     60 < HTTP/1.1 200 OK
     40 < HTTP/1.1 429 429

  

Notice that the initial requests receive a success response. Once the limit is reached, OpenIG throttles further requests from the same client address, which is the loopback address in this case. The result is HTTP status code 429 Too Many Requests.

Replace the handler in the chain with a client handler to limit requests through OpenIG to the protected application.

To monitor a route, you set "monitor": true in the top-level attributes on the route. The value of the attribute can be an expression that evaluates to a boolean, such as "monitor": "${true}", or an object that indicates the percentile thresholds. By using an appropriate boolean expression, for example, you can enable or disable monitoring with an environment variable or system property. For details, see Expressions(5) in the Configuration Reference and Route(5) in the Configuration Reference.

The following example route has monitoring enabled:

{
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "reason": "OK",
      "entity": "Hello, world!"
    }
  },
  "monitor": "${true}",
  "condition": "${matches(request.uri.path, '^/monitor')}"
}

  

Before you try this route, prepare OpenIG and the minimal HTTP server as shown in Chapter 2, "Getting Started".

Add the route file to the OpenIG configuration as $HOME/.openig/config/routes/00-monitor.json (on Windows, %appdata%\OpenIG\config\routes\00-monitor.json).

With the route in place and OpenIG running, access the route a few times at http://www.example.com:8080/monitor.

Your access causes OpenIG to collect monitoring statistics for the route. After generating statistics by accessing the route a few times, read the JSON monitoring resource for the route at http://www.example.com:8080/openig/api/system/objects/router-handler/routes/00-monitor/monitoring. The monitoring resource provides statistics on requests and responses as in the following example:

{
    "requests": {
        "total": 100,
        "active": 0
    },
    "responses": {
        "total": 100,
        "info": 0,
        "success": 100,
        "redirect": 0,
        "clientError": 0,
        "serverError": 0,
        "other": 0,
        "errors": 0,
        "null": 0
    },
    "throughput": {
        "mean": 15.6,
        "lastMinute": 20.0,
        "last5Minutes": 20.0,
        "last15Minutes": 20.0
    },
    "responseTime": {
        "mean": 0.093,
        "median": 0.046,
        "standardDeviation": 0.371,
        "total": 9,
        "percentiles": {
            "0.999": 3.762,
            "0.9999": 3.762,
            "0.99999": 3.762
        }
    }
}
  

For details about the content of the monitoring resource, see "The REST API for Monitoring" in the Configuration Reference.

By default, monitoring statistics are accessible from the local host. OpenIG uses an ApiProtectionFilter that protects the reserved routes for paths under /openig. By default, the filter allows access to reserved routes only from the local host. You can override this behavior by declaring a custom ApiProtectionFilter in the top-level heap. For an example, see the CORS filter described in Section 10.4, "Setting Up OpenIG As an UMA Resource Server".

This section covers adding an audit service to a route to integrate with the ForgeRock common audit event framework and to log audit event messages.

The ForgeRock common audit event framework provides common infrastructure across ForgeRock products to handle audit events using common audit event handlers.

To enable the audit framework for a route, you specify an audit service. The following example route, 30-audit.json, adds a route with an audit service configuration for publishing log messages to a CSV file, /tmp/logs/access.csv:

{
    "handler": "ForgeRockClientHandler",
    "baseURI": "http://www.example.com:8081",
    "condition": "${matches(request.uri.path, '^/audit')}",
    "auditService": {
        "type": "AuditService",
        "config": {
            "config": {},
            "event-handlers": [
                {
                    "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
                    "config": {
                        "name": "csv",
                        "logDirectory": "/tmp/logs",
                        "buffering": {
                            "enabled": "true",
                            "autoFlush": "true"
                        },
                        "topics": [
                            "access"
                        ]
                    }
                }
            ]
        }
    }
}

  

Notice that this route is triggered when the request path starts with /audit.

For additional information on the audit service, see Audit Logging Framework in the Configuration Reference.

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.

When the JSON for a route is not valid, OpenIG does not load the route. Instead, a description of the error appears in the log:

  
MON NOV 30 16:12:56 CET 2015 (ERROR) {Router}/handler
The route defined in file '/Users/me/.openig/config/routes/99-default.json'
 cannot be modified
------------------------------
MON NOV 30 16:12:56 CET 2015 (ERROR) {Router}/handler
Cannot read/parse content of /Users/me/.openig/config/routes/99-default.json
[            HeapException] > Cannot read/parse content of
                              /Users/me/.openig/config/routes/99-default.json
[       JsonParseException] > Unexpected character (',' (code 44)):
                              was expecting double-quote to start field name
 at [Source: java.io.InputStreamReader@195ed7f6; line: 8, column: 33]
  

In this case, extra comma is spotted at line 8, column 33.

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 an AssignmentFilter as described in AssignmentFilter(5) in the Configuration 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, rather than trying to set request.headers['Location'] for a redirect in the response object, you should instead set 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 Section 3.1, "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 use a different host and port than the host and port for 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 request 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:

/handler/config/filters/0/config/dataSource: javax.naming.NameNotFoundException;
    remaining name 'jdbc/forgerock'
[       JsonValueException] > /handler/config/filters/0/config/dataSource:
    javax.naming.NameNotFoundException; remaining name 'jdbc/forgerock'
[    NameNotFoundException] > null

org.forgerock.json.fluent.JsonValueException:
    /handler/config/filters/0/config/dataSource:
    javax.naming.NameNotFoundException; remaining name 'jdbc/forgerock'
 at org.forgerock.openig.filter.SqlAttributesFilter$Heaplet.create(
    SqlAttributesFilter.java:211)
 at org.forgerock.openig.heap.GenericHeaplet.create(GenericHeaplet.java:81)
 at org.forgerock.openig.heap.HeapImpl.extract(HeapImpl.java:316)
 at org.forgerock.openig.heap.HeapImpl.get(HeapImpl.java:281)
...
   

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": "${attributes.sql}"
    }
}
  

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