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, based on reverse proxy architecture. 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.

By default, OpenIG configuration files are located under $HOME/.openig on Linux, macOS, and UNIX systems, and %appdata%\OpenIG on Windows systems. For information about how to change the default locations , see Section 3.4, "Changing the Default Location of the Configuration Folders".

OpenIG uses the following configuration directories:

Routers are handlers that perform the following tasks:

Routes are configuration files that you add to OpenIG to manage requests. They are flat files in JSON format. You can add routes in the following ways:

Every route must call a handler to process the request and produce a response to a request.

When a route has a condition, it can handle only requests that meet the condition. When a route has no condition, it can handle any request.

Routes inherit settings from their parent configurations. This means that you can configure global objects in the config.json heap, for example, and then reference the objects by name in any other OpenIG configuration.

For examples of route configurations see Chapter 12, "Configuring Routers and Routes". For information about the parameters for routers and routes, see Router(5) in the Configuration Reference and Route(5) in the Configuration Reference.

Figure 1.3, "Flow Inside a Chain" shows the flow inside a Chain, where a request filter transforms the request, a handler sends the request to a protected application, and then a response filter transforms the response. Notice how the flow traverses the filters in reverse order when the response comes back from the handler.

Figure 1.3. Flow Inside a Chain

The route configuration in Example 1.1, "Chain to a Protected Application" demonstrates the flow through a chain to a protected application. With OpenIG and the sample application set up as described in Chapter 2, "Getting Started", you can access this route on http://openig.example.com:8080.

{
    "handler": {
        "type": "Chain",
        "comment": "Base configuration defines the capture decorator",
        "config": {
            "filters": [
                {
                    "type": "HeaderFilter",
                    "comment": "Add a header to all requests",
                    "config": {
                        "messageType": "REQUEST",
                        "add": {
                            "MyHeaderFilter_request": [
                                "Added by HeaderFilter to request"
                            ]
                        }
                    }
                },
                {
                     "type": "HeaderFilter",
                     "comment": "Add a header to all responses",
                     "config": {
                         "messageType": "RESPONSE",
                         "add": {
                             "MyHeaderFilter_response": [
                                 "Added by HeaderFilter to response"
                            ]
                         }
                     }
                }
            ],
            "handler": {
                "type": "ClientHandler",
                "comment": "Log the request, pass it to the protected application,
                            and then log the response",
                "capture": "all",
                "baseURI": "http://app.example.com:8081"
            }
        }
    }
}
  

Example 1.1, "Chain to a Protected Application" 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://openig.example.com:8080/ HTTP/1.1
Accept: */*
Host: openig.example.com:8080

### Add a header to the request (inside OpenIG) and direct it to the protected application
GET http://app.example.com:8081/ HTTP/1.1
Accept: */*
Host: openig.example.com:8080
MyHeaderFilter_request: Added by HeaderFilter to request

### Return the response to the user-agent
HTTP/1.1 200 OK
Content-Length: 1809
Content-Type: text/html; charset=ISO-8859-1

### Add a header to the response (inside OpenIG)
HTTP/1.1 200 OK
Content-Length: 1809
MyHeaderFilter_response: Added by HeaderFilter to response
  

Filters, handlers, and other objects whose configuration settings are defined by strings, integers, or booleans, can alternatively be defined by expressions that match the expected type.

Decorators are additional heap objects to 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.

OpenIG defines the following decorators: audit, baseURI, capture, and timer. You can use these decorators without configuring them explicitly.

You can log requests, responses, and processing times by adding decorations as shown in the following example:

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

For more information, see Decorators in the Configuration Reference.

Configuration parameters, such as host names, port numbers, and directories, can be declared as property variables in the OpenIG configuration or in an external JSON file. The variables can then be used in expressions in routes and in config.json to set the value of configuration parameters.

Properties can be inherited across the router, so a property defined in config.json can be used in any of the routes in the configuration.

Storing the configuration centrally and using variables for parameters that can be different for each installation makes it easier to deploy OpenIG in different environments without changing a single line in your route configuration.

For more information, see Properties(5) in the Configuration Reference.

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.

Common REST endpoints in OpenIG serve API descriptors at runtime. When you retrieve an API descriptor for an endpoint, a JSON that describes the API for that endpoint is returned.

To help you discover and understand APIs, you can use the API descriptor with a tool such as Swagger UI to generate a web page that helps you to view and test the different endpoints.

When you start OpenIG, or add or edit routes, registered endpoint locations for the routes hosted by the main router are written in $HOME/.openig/logs/route-system.log. Endpoint locations for subroutes are written to other log files. To retrieve the API descriptor for a specific endpoint, append one of the following query string parameters to the endpoint:

For more information about CREST API descriptors, see Section 5.5, "Common REST API Documentation" in the Configuration Reference.

http://openig.example.com:8080/openig/api/system/objects/_router/routes?_api
{
     "swagger": "2.0",
     "info": {
     "version": "OpenIG version",
     "title": "OpenIG"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/openig/api/system/objects/_router/routes",
     "tags": [{
     "name": "Routes Endpoint"
     }],
     . . . 

http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share?_api
{
     "swagger": "2.0",
     "info": {
     "version": "OpenIG version",
     "title": "OpenIG"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share",
     "tags": [{
     "name": "Manage UMA Share objects"
     }],
     . . . 

http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-uma/monitoring?_api
{
     "swagger": "2.0",
     "info": {
     "version": "OpenIG version",
     "title": "OpenIG"
     },
     "host": "openig.example.com:8080",
     "basePath": "/openig/api/system/objects/_router/routes/00-uma/monitoring",
     "tags": [{
     "name": "Monitoring endpoint"
     }],
     . . .

http://openig.example.com:8080/openig/api/system/objects/_router?_api
{
     "swagger": "2.0",
     "info": {
     "version": "OpenIG version",
     "title": "OpenIG"
     },
     "host": "openig.example.com:8080",
     "basePath": "/openig/api/system/objects/_router",
     "tags": [{
     "name": "Monitoring endpoint"
     }, {
     "name": "Manage UMA Share objects"
     }, {
     "name": "Routes Endpoint"
     }],
     . . .

http://openig.example.com:8080/openig/api?_api
{
     "swagger": "2.0",
     "info": {
     "version": "OpenIG version",
     "title": "OpenIG"
     },
     "host": "openig.example.com:8080",
     "basePath": "/openig/api",
     "tags": [{
     "name": "Internal Storage for UI Models"
     }, {
     "name": "Monitoring endpoint"
     }, {
     "name": "Manage UMA Share objects"
     }, {
     "name": "Routes Endpoint"
     }, {
     "name": "Server Info"
     }],
     . . .

Make sure you have a supported Java Development Kit installed. For details, see Section 2.2, "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.

ForeRock provides a mockup web application for testing OpenIG configurations. The sample application is used in many of the tutorials in this guide. This section takes you through the steps to download and run the sample application.

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

Because OpenIG uses reverse proxy architecture, you must configure the network so that traffic from the browser to the protected application goes through OpenIG.

If you followed the installation steps, you are running both OpenIG and the sample application 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 sample application to be running on app.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    openig.example.com app.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    openig.example.com app.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://openig.example.com:8080/home should take you to the home page of the sample application.

What just happened?

When your browser goes to http://openig.example.com:8080/, it is actually connecting to OpenIG deployed in Jetty. OpenIG proxies all traffic it receives to the protected application at http://app.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. This file specifies a main router named _router. OpenIG calls this handler when it receives an incoming request.

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, zz-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 login 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.3, "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>

Because OpenIG uses reverse proxy architecture, you must configure the network so that that traffic from the browser to the protected application goes through OpenIG.

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 with a cookieDomain set, be sure to share the encryption keys and the sharedSecret across all OpenIG configurations so that any server can read or update JWT cookies from any other server in the same cookieDomain.

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 procedure prepares a keystore for JWT encryption in a deployment with one OpenIG instance. For a deployment with more than one OpenIG instance, also configure a "sharedSecret" as described in JwtSession(5) in the Configuration Reference.

OpenIG operates in development mode (mutable mode) and production mode (immutable mode):

Before you start this tutorial, prepare OpenIG and the sample application as shown in Chapter 2, "Getting Started".

OpenIG should be running in Jetty, configured to access the sample application 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://openig.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 following figure 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

The following terms are used in access management:

OpenIG as a PEP intercepts requests for a resource, and provides information about the request to OpenAM as a PDP.

OpenAM evaluates requests based on their context and the configured policies. OpenAM then returns decisions that indicate what actions are allowed or denied, as well as any advices, subject attributes, or static attributes for the specified resources.

Attributes and advices returned by the policy decision are stored in the attributes and advices properties of the ${contexts.policyDecision} context. They are available to the PolicyEnforcementFilter's downstream filters and handlers.

In OpenAM, administrators can maintain centralized, fine-grained, declarative policies to manage who can access what resources, and under what conditions. Policies can be managed separately 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. For information, see PolicyEnforcementFilter(5) in the Configuration Reference.

This section gives an example of how to set up OpenIG as a PEP, requesting policy decisions from OpenAM as a PDP.

{
  "name": "04-pep",
  "baseURI": "http://app.example.com:8081",
  "monitor": false,
  "condition": "${matches(request.uri.path, '^/home/pep')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "SingleSignOnFilter",
          "name": "SingleSignOn",
          "config": {
            "openamUrl": "http://openam.example.com:8088/openam",
            "realm": "/",
            "cookieName": "iPlanetDirectoryPro"
          }
        },
        {
          "type": "PolicyEnforcementFilter",
          "name": "PEPFilter",
          "config": {
            "openamUrl": "http://openam.example.com:8088/openam",
            "pepUsername": "policyAdmin",
            "pepPassword": "password",
            "pepRealm": "/",
            "realm": "/",
            "application": "PEP policy set",
            "ssoTokenSubject": "${contexts.ssoToken.value}"
          }
        }
      ],
      "handler": "ClientHandler"
    }
  }
}

This section builds on the example in Section 6.2, "Enforcing Policy Decisions From OpenAM". The authentication level required to access the sample application is increased to level 1. After authenticating with OpenAM, the user must upgrade the session by entering a verification code before they can access the sample application.

Federation allows organizations to share identities and services without giving away their identity information or the services they provide. Federation depends on standards to orchestrate interaction and exchange information between providers.

SAML 2.0 is a standard that describes the messages that providers exchange and the way that they exchanged them. SAML 2.0 enables web single sign-on (SSO), for example, where the service managing the user's identity does not belong to the same organization and does not use the same software as the service that the user wants to access.

When an identity provider and a service provider participate in federation, they agree on what security information to exchange, and mutually configure access to each others' services. The metadata that identity providers and service providers share is in an XML format defined by the SAML 2.0 standard.

This tutorial assumes that you are familiar with SAML 2.0 federation and with the components involved, including OpenAM. For information about OpenAM, read the documentation for your version of OpenAM.

This tutorial does not address PKI configuration for validation and encryption, although OpenIG is capable of handling both, just as any OpenAM Fedlet can handle both.

This tutorial takes you through the steps to set up OpenAM as an IDP and OpenIG as an SP to protect an application. To set up multiple SPs, read this chapter, work through the samples, and then consider the explanation in Appendix A, "SAML 2.0 and Multiple Applications".

For examples of the federation configuration files, see Section 7.7, " Example Federation Configuration Files ". You can copy and edit these files to create new configurations.

Configure the network so that browser traffic to the application hosts is proxied through OpenIG. The example in this chapter uses the host name sp.example.com.

Add the following address to your hosts file: sp.example.com.

   127.0.0.1    localhost openam.example.com openig.example.com app.example.com sp.example.com
  

Before you start, prepare OpenIG and the sample application as shown in Chapter 2, "Getting Started". Getting the basic setup to work before you configure federation makes it simpler to troubleshoot if anything goes wrong.

To test your setup, access the login page of the sample application through OpenIG at http://openig.example.com:8080/login. Log in as username george, password costanza. You should see a page showing the username and some information about the request.

{
  "handler": {
    "type": "SamlFederationHandler",
    "config": {
      "assertionMapping": {
        "username": "mail",
        "password": "employeenumber"
      },
      "subjectMapping": "sp-subject-name",
      "redirectURI": "/federate"
    }
  },
  "condition": "${matches(request.uri.path, '^/saml')}",
  "session": "JwtSession"
}

{
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${empty session.username}",
          "handler": {
            "type": "StaticResponseHandler",
            "config": {
              "status": 302,
              "reason": "Found",
              "headers": {
                "Location": [
                  "http://sp.example.com:8080/saml/SPInitiatedSSO"
                ]
              }
            }
          }
        },
        {
          "handler": {
            "type": "Chain",
            "config": {
              "filters": [
                {
                  "type": "StaticRequestFilter",
                  "config": {
                    "method": "POST",
                    "uri": "http://app.example.com:8081/login",
                    "form": {
                      "username": [
                        "${session.username[0]}"
                      ],
                      "password": [
                        "${session.password[0]}"
                      ]
                    }
                  }
                }
              ],
              "handler": "ClientHandler"
            }
          }
        }
      ]
    }
  },
  "condition": "${matches(request.uri.path, '^/federate')}",
  "session": "JwtSession"
}

"headers": {
    "Location": [
        "http://openig.example.com:8080/saml/SPInitiatedSSO?RelayState=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}"
    ]
}

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 a string given by the authorization server that represents the authorization to access protected resources. 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 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 time until the token expires, the OAuth 2.0 scopes associated with the token, and potentially 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 sample application as described in Chapter 2, "Getting Started".

OpenIG should be running in Jetty, configured to access the sample application 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.

For more complete information about configuring the OAuth 2.0 authorization service in OpenAM, see Configuring the OAuth 2.0 Authorization Service in the OpenAM OAuth 2.0 Guide.

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

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 creates a new context for the authorization server response, at ${contexts.oauth2}.

The context is named oauth2 and can be reached at contexts.oauth2 or contexts['oauth2'].

The context contains data such as the access token, which can be reached at contexts.oauth2.accessToken or contexts['oauth2'].accessToken.

Filters and handlers placed after the OAuth2ResourceServerFilter in the chain, can access the token info through the context.

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.

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
          },
          "capture": "filtered_request",
          "timer": true
        },
        {
          "type": "AssignmentFilter",
          "config": {
            "onRequest": [
              {
                "target": "${session.username}",
                "value": "${contexts.oauth2.accessToken.info.mail}"
              },
              {
                "target": "${session.password}",
                "value": "${contexts.oauth2.accessToken.info.employeenumber}"
              }
            ]
          },
          "timer": true
        },
        {
          "type": "StaticRequestFilter",
          "config": {
            "method": "POST",
            "uri": "http://app.example.com:8081/login",
            "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 get an access token from OpenAM and use it to access OpenIG, which uses the OAuth 2.0 resource owner password credentials authorization grant.

What is happening behind the scenes?

After OpenIG gets the curl request, the resource server filter validates the access token with OpenAM, and creates a new context for the authorization server response, at ${contexts.oauth2.accessToken}. If the access token had been missing or invalid, then the resource server filter would have returned an error status to the user-agent, and 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 sample application, which responds with the user information page.

As described in Chapter 8, "Acting As an OAuth 2.0 Resource Server", an OAuth 2.0 client is a third-party application that needs access to a user's protected resources.

OpenIG can act as an OAuth 2.0 client when you configure an OAuth2ClientFilter as described in OAuth2ClientFilter(5) in the Configuration Reference. The OAuth2ClientFilter 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. The code grant results in the authorization server returning an access token to the filter.

When an authorization grant succeeds, the OAuth2ClientFilter 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 an authorization grant fails, the failureHandler is invoked.

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 the OpenID Connect 1.0 authentication layer built on OAuth 2.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.

When OpenIG acts as an OpenID Connect 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.

This tutorial takes you through the steps to set up OpenAM as an OpenID Connect provider and OpenIG as an OpenID Connect relying party. For an example configuration with two identity providers, OpenAM and Google, and a login handler, see "Example Configuration For Multiple Identity Providers" in the Configuration Reference.

In this part, you create a sample user and set up OpenAM as an OpenID Connect provider.

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

This section describes how to use OpenIG Studio to configure OpenIG as a relying party for browser requests to the home page of the sample application. The example refers to the provider configuration in Section 9.4, " Setting Up OpenAM for OpenID Connect ".

To configure OpenIG without using OpenIG Studio, add the route in Example 9.1, "Route for OpenIG As a Relying Party" to the OpenIG configuration as $HOME/.openig/config/routes/07-openid.json. On Windows, add the route as %appdata%\OpenIG\config\routes\07-openid.json.

{
  "name": "07-openid",
  "baseURI": "http://app.example.com:8081",
  "monitor": false,
  "condition": "${matches(request.uri.path, '^/home/id_token')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "OAuth2ClientFilter",
          "name": "OAuth2Client",
          "config": {
            "clientEndpoint": "/home/id_token",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/plain"
                  ]
                },
                "entity": "An error occurred during the OAuth2 setup."
              }
            },
            "registrations": [
              {
                "name": "oidc-user-info-client",
                "type": "ClientRegistration",
                "config": {
                  "clientId": "oidc_client",
                  "clientSecret": "password",
                  "issuer": {
                    "name": "Issuer",
                    "type": "Issuer",
                    "config": {
                      "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
                    }
                  },
                  "scopes": [
                    "openid",
                    "profile",
                    "email"
                  ],
                  "tokenEndpointAuthMethod": "client_secret_basic"
                }
              }
            ],
            "requireHttps": false
          }
        }
      ],
      "handler": "ClientHandler"
    }
  }
}

Notice the following features about the route:

To authenticate automatically to the sample application, edit $HOME/.openig/config/routes/07-openid.json manually as follows:

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.

The following figure illustrates the basic flow of information between a request, OpenIG, the OpenAM OAuth 2.0 and STS modules, and an application. For a more detailed view of the flow, see Figure 10.2, "Flow of Events".

Figure 10.1. Token Transformation

The basic process is as follows:

This tutorial takes you through the steps to set up OpenAM as an OAuth 2.0 provider and OpenIG as an OpenID Connect relying party.

When a user makes a request, the OAuth2ClientFilter returns an id_token. The TokenTransformationFilter references a REST STS instance that you set up in OpenAM to transform the id_token into a SAML 2.0 assertion.

You need to be logged in to OpenAM as administrator to set up the configuration for token transformation, but you do not need special privileges to request a token transformation. For more information, see TokenTransformationFilter(5) in the Configuration Reference.

The following sequence diagram shows what happens when you set up and access routes for token transformation.

Figure 10.2. Flow of Events

Example of the final 50_idtoken.json:

{
  "heap": [
    {
      "name": "openam",
      "type": "ClientRegistration",
      "config": {
        "clientId": "oidc_client",
        "clientSecret": "password",
        "issuer": {
          "type": "Issuer",
          "config": {
            "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
          }
        },
        "scopes": [
          "openid",
          "profile",
          "email"
        ]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "OAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/home/id_token",
            "requireHttps": false,
            "requireLogin": true,
            "registrations": "openam",
            "target": "${attributes.openid}",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "entity": "OAuth2ClientFilter failed...",
                "reason": "NotFound",
                "status": 500
              }
            }
          }
        },
        {
          "type": "TokenTransformationFilter",
          "config": {
            "openamUri": "http://openam.example.com:8088/openam",
            "username": "oidc_client",
            "password": "password",
            "idToken": "${attributes.openid.id_token}",
            "instance": "openig",
            "ssoTokenHeader": "iPlanetDirectoryPro"
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "entity": "{\"id_token\":\n\"${attributes.openid.id_token}\"} \n\n\n{\"saml_assertions\":\n\"${contexts.sts.issuedToken}\"}",
          "reason": "Found",
          "status": 200
        }
      }
    }
  },
  "condition": "${matches(request.uri.path, '^/home/id_token')}"
}

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

11.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 11.1, "UMA Workflow" illustrates the relationships where OpenIG protects the resource server.

Figure 11.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 tutorial guides you through one way to set up OpenIG as an UMA resource server. It uses OpenAM as an authorization server for OAuth 2.0 and for UMA, and uses the sample application as a resource to protect and for files that serve as a basic UMA client.

This section describes the following tasks to set up OpenAM as an authorization server:

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

If you use a configuration that is different to that described in this chapter, consider the following tasks to adjust the sample to your configuration:

When you set up the first tutorial, you configured a Router in the top-level config.json file, which is shown here again in the following listing:

{
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "http://app.example.com:8081",
    "capture": "all"
  },
  "heap": [
    {
      "name": "JwtSession",
      "type": "JwtSession"
    },
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ]
}

In this configuration, all requests are passed with the default settings to the router. The router scans $HOME/.openig/config/routes at startup, and rescans the directory every 10 seconds. If routes have been added, deleted or changed, the router applies the changes.

The main router and any subrouters are used to build the monitoring endpoints. For information about monitoring endpoints, see Chapter 15, "Auditing and Monitoring". For information about the parameters of a router, see Router(5) in the Configuration Reference.

Routes are JSON configuration files that handle requests and their context, and then hand off any request they accept to a handler. Another way to think of a route is like an independent dispatch handler, as described in DispatchHandler(5) in the Configuration Reference.

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

For information about the parameters of routes, see Route(5) in the Configuration Reference.

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

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

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

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

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

Through Common REST, you can read, add, delete, and edit routes on OpenIG without manually accessing the file system. You can also list the routes in the order that they are loaded in the configuration, and set fields to filter the information about the routes.

The following examples show some ways to manage routes through Common REST. For more information, see Section 5, "About ForgeRock Common REST" in the Configuration Reference.

OpenIG Studio is a user interface to configure and deploy routes in OpenIG. You can use OpenIG Studio to create routes for tasks such as authenticating users, and authorizing access to APIs, throttling the rate of requests to protected applications, capturing messages, and collecting statistics. New features will be added as OpenIG Studio evolves.

When OpenIG is installed and running as described in this guide, access OpenIG Studio on http://openig.example.com:8080/openig/studio.

For examples of how to use OpenIG Studio to configure routes, see the following sections of this guide:

To prevent routes from being reloaded after startup, stop OpenIG, edit the router scanInterval, and restart OpenIG. When the interval is set to disabled, routes are loaded only at startup:

{
    "name": "Router",
    "type": "Router",
    "config": {
        "scanInterval": "disabled"
    }
}

The following example changes the location where the router looks for the routes:

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

OpenIG uses an ApiProtectionFilter to protect the reserved routes. By default, the filter allows access to reserved routes only from the loopback address. To override this behavior, declare a custom ApiProtectionFilter in the top-level heap. For an example, see the CORS filter described in Procedure 11.5, "To Set Up OpenIG As a UMA Resource Server".

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 13.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://app.example.com:8444"
        },
        {
          "condition": "${request.uri.scheme == 'http'}",
          "handler": "ClientHandler",
          "baseURI": "http://app.example.com:8081"
        },
        {
          "handler": "ClientHandler",
          "baseURI": "https://app.example.com:8444"
        }
      ]
    }
  },
  "capture": "all",
  "condition": "${matches(request.uri.query, 'demo=capture')}"
}

   

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

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

The route in Example 13.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://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=simple')}"
}

   

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

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

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

Some applications expect a cookie from the login page to be sent in the login request form. OpenIG can manage the cookies. The route in Example 13.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://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ]
              }
            }
          }
        },
        {
          "type": "CookieFilter"
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=cookie')}"
}

   

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

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

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

The route in Example 13.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://app.example.com:8081/openam/UI/Login",
              "form": {
                "IDToken0": [
                  ""
                ],
                "IDToken1": [
                  "demo"
                ],
                "IDToken2": [
                  "changeit"
                ],
                "IDButton": [
                  "Log+In"
                ],
                "encoded": [
                  "false"
                ]
              },
              "headers": {
                "host": [
                  "app.example.com:8081"
                ]
              }
            }
          }
        },
        {
          "type": "CookieFilter"
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=classic')}"
}

   

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

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

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

Welcome, demo!
  

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

Some applications call for extracting a hidden value from the login page and including the value in the login form POSTed to the target application. The route in Example 13.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://app.example.com:8444/login",
              "form": {
                "username": [
                  "MY_USERNAME"
                ],
                "password": [
                  "MY_PASSWORD"
                ],
                "hiddenValue": [
                  "${attributes.extracted.hidden}"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=hidden')}"
}

   

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

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

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 13.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://app.example.com:8081"
        },
        {
          "condition": "${request.uri.path == '/login'}",
          "handler": {
            "type": "Chain",
            "config": {
              "comment": "Add one or more filters to handle login.",
              "filters": [],
              "handler": "ClientHandler"
            }
          },
          "baseURI": "https://app.example.com:8444"
        },
        {
          "handler": "ClientHandler",
          "baseURI": "https://app.example.com:8444"
        }
      ]
    }
  },
  "condition": "${matches(request.uri.query, 'demo=https')}"
}

   

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

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

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

The route in Example 13.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://app.example.com:8444/login",
              "form": {
                "username": [
                  "${request.headers['username'][0]}"
                ],
                "password": [
                  "${request.headers['password'][0]}"
                ]
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.query, 'demo=headers')}"
}

   

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

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

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

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 13.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 Access Management", 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 Procedure 5.5, "To Configure Password Capture in OpenAM".

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 several global variables to scripts at runtime. As well as having access to Groovy's built-in functionality, scripts can access the request and the context, store variables across executions, write messages to logs, make requests to a web service or to an LDAP directory service, and access responses returned in promise callback methods. For information about scripting in OpenIG, 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:

/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */


/*
 * 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(Status.OK);

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",
            "condition": "${matches(request.uri.path, '/dispatch')}"
          }
        ]
      }
    },
    {
      "name": "Dispatcher",
      "type": "ScriptableHandler",
      "config": {
        "type": "application/x-groovy",
        "file": "DispatchHandler.groovy"
      }
    }
  ],
  "handler": "DispatchHandler",
  "condition": "${matches(request.uri.path, '^/dispatch') or matches(request.uri.path, '^/mylogin')}"
}

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

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

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:

/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

/*
 * 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://openig.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://openig.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:

/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

import org.forgerock.opendj.ldap.*

/*
 * 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(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(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://openig.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:

/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

/*
 * 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:

/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

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://openig.example.com:8080/db?mail=george@example.com.

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

OpenIG includes a complete Java application programming interface to allow you to customize OpenIG to perform complex server interactions or intensive data transformations that you cannot achieve with scripts or the existing handlers, filters, and expressions described in Expressions(5) in the Configuration Reference.

package org.forgerock.openig.doc;

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.GenericHeaplet;
import org.forgerock.openig.heap.HeapException;
import org.forgerock.services.context.Context;
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 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").as(evaluatedWithHeapProperties()).required().asString();
            filter.value = config.get("value").as(evaluatedWithHeapProperties()).required().asString();

            return filter;
        }
    }
}

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

org.forgerock.openig.doc.SampleClassAliasResolver

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

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

To collect statistics for a route, set the route's monitor attribute to true. Alternatively, use an appropriate boolean expression to enable or disable monitoring with an environment variable or system property.

When monitoring is enabled, statistics for the route are exposed as a JSON format monitoring resource that you can access over a Common REST endpoint. For information about what information is monitored, see "The REST API for Monitoring" in the Configuration Reference.

Monitoring endpoints serve API descriptors at runtime. When you retrieve an API descriptor for a monitoring endpoint, a JSON that describes the API for the endpoint is returned. You can use the API descriptor with a tool such as Swagger UI to generate a web page that helps you to view and test the endpoint. For information, see Section 1.10, "Understanding OpenIG APIs With API Descriptors".

When you start OpenIG, or add or edit routes, the endpoints are written in $HOME/.openig/logs/route-system.log. The endpoints are constructed from the base URL of OpenIG, the object name of the main router configured in config.json, and the route ID. When a route contains a subrouter, its endpoint includes the main router and the subrouter.

The routes endpoint is defined by the presence and content of config.json, as follows:

The ForgeRock common audit framework is a platform-wide infrastructure to handle audit events by using common audit event handlers. The handlers record events by logging them into files, relational databases, or syslog.

Each audit event is identified by a unique transaction ID that can be communicated across products and recorded for each local event. By using the transaction ID, requests can be tracked as they traverse the platform, making it easier to monitor activity and to enrich reports.

Transaction IDs from other services in the ForgeRock platform are sent as X-ForgeRock-TransactionId header values.

By default, OpenIG does not trust transaction ID headers from client applications.

To enable the audit framework for a route, you specify an audit service and configure an audit event handler. The following procedures describe how to record audit events in a CSV file and to the Elasticsearch search and analytics engine. For more information about recording audit events, see Audit Framework in the Configuration Reference.

This section describes how to use OpenIG Studio to configure a simple throttling filter that applies a throttling rate of 6 requests/10 seconds to requests. When an application is protected by this throttling filter, no more than 6 requests, irrespective of their origin, can access the sample application in a 10 second period.

To configure OpenIG without using OpenIG Studio, add the route in Example 16.1, "Route for Simple Throttling" to the OpenIG configuration as $HOME/.openig/config/routes/simple-throttling.json. On Windows, add the route as %appdata%\OpenIG\config\routes\simple-throttling.json.

Figure 16.1. Simple Throttling Filter

{
  "name": "00-throttle-simple",
  "baseURI": "http://app.example.com:8081",
  "monitor" : false,
  "condition": "${matches(request.uri.path, '^/home/throttle-simple')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "name": "Throttling",
          "config": {
            "rate": {
              "numberOfRequests": 6,
              "duration": "10 s"
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  }
}

The following example route uses a mapped throttling policy to map requests from users in the accounts and sales departments of example.com to different throttling rates. Requests from other departments use the default throttling rate.

The throttling rate is applied to groups according to the evaluation of requestGroupingPolicy. In the example, this parameter evaluates to the first UserID in the request header, representing each user.

The value of the throttling rate is assigned according to the evaluation of throttlingRateMapper. In the example, this parameter evaluates to the value of the request header X-Forwarded-For, representing the hostname of the department.

Figure 16.2. Mapped Throttling Filter

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "config": {
            "requestGroupingPolicy": "${request.headers['UserId'][0]}",
            "throttlingRatePolicy": {
              "type": "MappedThrottlingPolicy",
              "config": {
                "throttlingRateMapper": "${request.headers['X-Forwarded-For'][0]}",
                "throttlingRatesMapping": {
                  "accounts.example.com": {
                    "numberOfRequests": 6,
                    "duration": "10 seconds"
                  },
                  "sales.example.com": {
                    "numberOfRequests": 3,
                    "duration": "10 seconds"
                  }
                },
                "defaultRate": {
                  "numberOfRequests": 1,
                  "duration": "10 seconds"
                }
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.path, '^/home/throttle-mapped')}"
}

In this example, the DefaultRateThrottlingPolicy delegates the management of throttling to the scriptable throttling policy.

The script applies a throttling rate of 6 requests/10 seconds to requests from the accounts department of example.com. For all other requests, the script returns null. When the script returns null, the default rate of 1 request/10 seconds is applied.

Figure 16.3. Scriptable Throttling Policy

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "config": {
            "requestGroupingPolicy": "${request.headers['UserId'][0]}",
            "throttlingRatePolicy": {
              "type": "DefaultRateThrottlingPolicy",
              "config": {
                "delegateThrottlingRatePolicy": {
                  "type": "ScriptableThrottlingPolicy",
                  "config": {
                    "type": "application/x-groovy",
                    "source": [
                      "if (request.headers['X-Forwarded-For'].values[0]  == 'accounts.example.com') {",
                      "  return new ThrottlingRate(6, '10 seconds')",
                      "} else {",
                      "  return null",
                      "}"
                    ]
                  }
                },
                "defaultRate": {
                  "numberOfRequests": 1,
                  "duration": "10 seconds"
                }
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.path, '^/home/throttle-scriptable')}"
}

In Section 16.2, " Configuring a Mapped Throttling Filter ", requests from the same user were always sent from the same department in example.com. This example shows what happens to the throttling rate when a user sends requests from more than one department.

The throttling rate is applied to users according to the evaluation of requestGroupingPolicy, and different throttling rates are mapped to different departments of example.com according to the evaluation of throttlingRateMapper.

Figure 16.4. Dynamic Throttling Rate

In the example, Alice sends five requests from the accounts department, quickly followed by four requests from sales, and then three more requests from accounts.

After making five requests from accounts, Alice has almost reached the throttling rate. When she switches to sales, the number of requests she has already made is disregarded and the full throttling rate for sales is applied. Alice can now make three more requests from sales even though she had nearly reached her throttling rate for accounts.

After making three requests from sales, Alice has reached her throttling rate. When she makes a fourth request from sales, the request is refused. Alice switches back to accounts and can now make six more requests even though she had reached her throttling rate for sales.

When you configure requestGroupingPolicy and throttlingRateMapper, bear in mind what happens when requests from the same requestGroupingPolicy can be mapped to different throttling rates by the throttlingRateMapper.

Log messages are recorded with the following default configuration:

The content and format of logs is defined by the reference logback.xml delivered with OpenIG. This file defines the following configuration items for logs:

<?xml version="1.0" encoding="UTF-8"?><!--
  Copyright 2016-2017 ForgeRock AS. All Rights Reserved
 
  Use of this code requires a commercial software license with ForgeRock AS.
  or with one of its affiliates. All use shall be exclusively subject
  to such license between the licensee and ForgeRock AS.
--><configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%nopex[%thread] %highlight(%-5level) %boldWhite(%logger{35}) - %message%n%highlight(%rootException{short})</pattern>
    </encoder>
  </appender>

  <appender name="SIFT" class="ch.qos.logback.classic.sift.SiftingAppender">
    <discriminator>
      <key>routeId</key>
      <defaultValue>system</defaultValue>
    </discriminator>
    <sift>
      <!-- Create a separate log file for each <key> -->
      <appender name="FILE-${routeId}" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${openig.base}/logs/route-${routeId}.log</file>

        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
          <!-- Rotate files daily -->
          <fileNamePattern>${openig.base}/logs/route-${routeId}-%d{yyyy-MM-dd}.%i.log</fileNamePattern>

          <!-- each file should be at most 100MB, keep 30 days worth of history, but at most 3GB -->
          <maxFileSize>100MB</maxFileSize>
          <maxHistory>30</maxHistory>
          <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>

        <encoder>
          <pattern>%d{HH:mm:ss:SSS} | %-5level | %thread | %logger{20} | %message%n%xException</pattern>
        </encoder>
      </appender>
    </sift>
  </appender>

  <!-- Disable logs of exceptions attached to responses by defining 'level' to OFF -->
  <logger name="org.forgerock.openig.filter.LogAttachedExceptionFilter" level="INHERITED"/>

  <root level="INFO">
    <appender-ref ref="SIFT"/>
    <appender-ref ref="STDOUT"/>
  </root>
</configuration>

The Logback configuration is very flexible, providing a wide range of options for logging. For a full description of its parameters, see the Logback website. The following examples show some simple changes that you can make.

To change the logging behavior, create a new Logback file at $HOME/.openig/config/logback.xml. This Logback file overrides the default configuration.

To take into account edits to logback.xml, stop and restart OpenIG or edit the configuration parameter to add a scan and interval:

<configuration scan="true" scanPeriod="5 seconds">

The configuration scan="true" requires logback.xml to be scanned for changes. The file is scanned after both of the following criteria are met:

14:38:59,667 |-ERROR in ch.qos.logback.core.joran.spi.Interpreter@20:72 ...
14:38:59,690 |-ERROR in ch.qos.logback.core.joran.action.AppenderRefAction ...

%d{yyyyMMdd-HH:mm:ss} | %-5level | %thread | %logger{20} | %message%n%xException

<logger name="org.forgerock.openig.handler.ClientHandler" level="ERROR"/>

<logger name="org.forgerock.openig.decoration.baseuri.BaseUriDecorator.baseURI" level="TRACE"/>

12:27:40| TRACE | http-nio-8080-exec-3 | o.f.o.d.b.B.b.{Router}/handler
        | Rebasing request to http://app.example.com:8081

<logger name="org.forgerock.openig.filter.LogAttachedExceptionFilter" level="OFF"/>

You have set up and are testing the example in Section 11.1, "About OpenIG in the UMA Resource Server Role".

If you have problems creating shares for Alice, perform the following steps to see if you can get a PAT from OpenAM:

If you continue to have problems, make sure that your OpenIG configuration matches that shown when you are running the test on http://app.example.com:8081/uma/.

OpenIG Studio deploys and undeploys routes through a main router named _router, which is the name of the main router in the default configuration. If you use a custom config.json, make sure that it contains a main router named _router.

For information about OpenIG Studio, see Section 12.4, "Creating Routes Through OpenIG Studio ".

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:

16:09:50 | ERROR | openig.example.com-startStop-1 | o.f.o.h.r.RouterHandler |
The file '/Users/me/.openig/config/routes/zz-default.json' is not a valid route configuration.

Use a JSON editor or JSON validation tool such as JSONLint to make sure that 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.

Define an entity for the response as in the following example:

{
    "name": "AccessDeniedHandler",
    "type": "StaticResponseHandler",
    "config": {
        "status": 403,
        "reason": "Forbidden",
        "entity": "<html><body><p>User does not have permission</p></body></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