In today's enterprise, more than 30% of web applications are incompatible with web access management (WAM) software. That is, unlike OpenAM with OpenIG, most web access management products lack the agent to protect the web applications, or the application is a legacy solution that does not follow standard protocols for single sign-on. This limits the return on the enterprise WAM investment and constrains what types of web applications can be protected.

ForgeRock OpenIG addresses this problem by extending access management to encompass all web applications. With OpenIG, OpenAM deployments can now be extended to be inclusive of those applications that do not integrate with policy agents alone. In addition, ForgeRock OpenIG interoperates, out-of-the-box, with all management solutions. Most importantly, your organization can on-board any web application without ever modifying or touching the target application again, significantly reducing the development and quality assurance required to protect web applications.

The expertise and cost required to add SAML 2.0 support to web applications is a problem for many businesses. Those businesses not moving to a standard for exposing their applications to their customers see increased cost and maintenance due to the complexity of one-off proprietary integrations. They can also see a loss of business to those customers requiring a Federation standard for authentication. Sometimes, deploying a full access management solution just to federate a few applications is is too complex and costly, and building out their own solution by modifying their applications is just not possible.

OpenIG Federation allows businesses to add SAML 2.0 support to their applications with little to no knowledge of the standard. In addition, there is no need to modify the application or to install any plugin or policy agent on the application container.

OAuth 2.0 is modern federation alternative, aimed at making it easy for users to delegate third-party applications access to their protected resources without having to share credentials with the third-party applications. Like federation, OAuth 2.0 lets users benefit from new services without having to create new accounts. Instead they can use an existing account with an OAuth 2.0-compliant identity provider, such as Facebook, Google, or any provider using OpenAM. Many mobile and web applications are moving to use OAuth 2.0.

With OpenIG, you can add OAuth 2.0 support to existing protected resources, and use OpenIG capabilities to quickly develop new OAuth 2.0 applications. OpenIG can protect resources by using OAuth 2.0 (as resource server), interoperating with client applications and identity providers, so that your applications can rely on delegated authorization for access to users' protected resources.

The following figure shows OpenIG playing the role of resource server in an OAuth 2.0 authorization code grant flow.

OpenIG can also play the role of OAuth 2.0 client, authenticating an end user using OAuth 2.0 delegated authorization with an existing OAuth 2.0-compliant identity provider. This means developers can quickly develop OAuth 2.0 client applications without having to learn the intricacies of OAuth 2.0 authorization grant flows. OpenIG takes care of obtaining the access token on behalf of your application and injects the access token for your use.

OpenID Connect 1.0 is an implementation of OAuth 2.0 whereby the protected resource is information about the user or about the user's account with the identity provider.

As OAuth 2.0 client, OpenIG can play the role of OpenID Connect 1.0 relying party, obtaining user information on behalf of your application.

The following figure shows OpenIG playing the role of relying party, where the mail server requires user information to show the right mailboxes.

In addition, there is generally no need to modify existing applications or servers housing protected resources or to install plugins or policy agents on the servers.

OpenIG can for example inject user information into the URL, adding a username as in https://mail.example.com/mail/username. For some applications, you might choose to provide additional capabilities, and so you might want to enhance the application to accept additional user information from the provider in other ways.

The underlying core of ForgeRock OpenIG is based on a reverse proxy architecture. All HTTP traffic to each protected application is routed through OpenIG, enabling close inspection, transformation and filtering of each request. By inspecting the traffic, OpenIG is able to intercept requests that would normally require the user to authenticate, obtain the user's login credentials, and send the necessary HTTP request to the target application, thereby logging in the user without modifying or installing anything on the application. In its simplest form and basic configuration, OpenIG is a Java-based reverse proxy which runs as a web application. Enable the Form-Filter replay module and OpenIG automatically log users in when a timeout or authentication page is detected. Additionally, enable the SAML2 service and OpenIG becomes a SAML2 endpoint. In this mode of operation, OpenIG receives and verifies the SAML2 request and then logs the user directly into the target application.

The following modules make up OpenIG.

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

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

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

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

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

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

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

127.0.0.1    www.example.com

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

192.168.0.15    www.example.com

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

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

Also view the file capturing information about requests and responses. In the default sample configuration, this file is /tmp/gateway.log.

What's happening behind the scenes?

When your browser goes to http://www.example.com:8080/, it is actually connecting to OpenIG deployed in Jetty. OpenIG proxies all traffic it receives to the protected application at http://www.example.com:8080/, and returns responses from the application to your browser.

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. And OpenIG also replaces your browser's original HTTP GET request with an HTTP POST login request containing credentials to authenticate. As a result, instead of the home page with a login form, OpenIG logs you in directly, and the application responds with the page you see after logging in. OpenIG then returns this response to your browser.

The following sequence diagram shows the steps.

Figure 3.1. 

In this chapter, you have scratched the surface of OpenIG. For more information, start with these chapters.

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

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

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

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

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

    

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

    

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

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

    

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

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

Restart the browser after making this change.

The figure below illustrates a sample flow with a description of each request from the browser to the back end application. This flow is based on the tutorial, Login With Credentials From a File. Try the tutorial yourself to learn how OpenIG works. The Flat-File attribute store contains only one set of credentials. OpenIG makes the assumption this user is logging into the sample application. In a real deployment OpenIG would look up the user credentials using its own session, a SAML 2.0 assertion, or a header from an OpenAM policy agent. Use cases that follow show examples of these types of deployments.

The figure below illustrates OpenIG integrated into an OpenAM deployment. In this deployment OpenIG is running in a container that is protected by an OpenAM policy agent. The agent is configured to forward a header, with the subject (user) of the single sign-on session, to OpenIG. OpenIG then uses the subject as the login credentials, or uses the subject as a reference to look up the login credentials in a database or directory. The HR application is integrated into the SSO deployment without an agent or any modification to the application or its deployment configuration.

The figure below illustrates OpenIG Federation providing SAML 2.0 features acting as Service Provider (SP) in an SP-initiated single sign-on configuration. In this sample, the HR application is an outsourced provider of HR services and has started seeing increased demand for SAML 2.0 support in their core application. The companies to which they outsource are refusing proprietary means of authentication and demanding the widely-accepted SAML 2.0 standard. The HR application cannot be modified to support SAML 2.0 nor do they have the time or money to integrate and deploy all of OpenAM. With OpenIG Federation, the HR application deploys OpenIG as a reverse proxy for their application, configures it as a SAML 2.0 Service Provider, and configures it to log users into the HR application upon successful verification of the SAML 2.0 authentication assertion from their customers' SAML 2.0 Identity Providers.

The figure below illustrates OpenIG Federation providing SAML 2.0 features acting as Service Provider in an IDP-initiated single sign-on configuration.

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

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

The initial OpenIG configuration file should look like the one used to login with a hard-coded username and password, see Configuration for Hard-Coded Credentials.

{
    "name": "LogSink",
    "type": "ConsoleLogSink",
    "config": {
        "level": "DEBUG"
    }
}
   

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

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

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

  

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

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

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

What's happening behind the scenes?

Figure 6.1. 

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

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

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

What's happening behind the scenes?

Figure 6.2. 

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

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

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

In this section, it is assumed that you are familiar with the components involved.

Access the application home page, http://www.example.com:8080/.

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

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

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

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

The following sample configuration is corresponds to a scenario where OpenIG receives a SAML assertion from OpenAM, and then logs the user in to the protected application using the username and password from the assertion. Descriptions of the fields follow the example.

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

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

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

The "SamlFederationHandler" configuration object looks like this:

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

The "LoginRequest" configuration object looks like this:

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

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

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

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

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

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

The initial OpenIG configuration file should look like the one used to proxy requests through to the HTTP server and to capture request and response data, see Configuration for Proxy & Capture.

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

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

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

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

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

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

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

Replace the existing OpenIG configuration file with the new configuration from the example, Configuration for the Federation Tutorial.

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

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

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

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

What is happening behind the scenes?

Consider the configuration, $HOME/.openig/config/config.json. In this configuration, the "DispatchHandler" is the entry point to OpenIG processing. The "DispatchHandler" provides an internal routing mechanism, based on the state of the exchange. If the incoming URI matches a SAML URI, then the "SamlFederationHandler" can process an incoming SAML 2.0 assertion, and also set the attributes from the assertion in the session. This condition is not met until the user has authenticated.

If no user name is set in the session of the exchange, the "DispatchHandler" considers that the user has not yet authenticated. This condition is met when the user has not yet authenticated. In this case the "DispatchHandler" dispatches to the static request handler, "SPInitiatedSSORedirectHandler", which redirects the user-agent to the Identity Provider for SAML 2.0 single sign-on. After authentication, the Identity Provider redirects the user-agent back to a SAML URI on the Service Provider (OpenIG), and so the request is dispatched to the "SamlFederationHandler" mentioned above.

Once the attributes from the assertion are set in the session, then the exchange is dispatched to the "LoginChain". The "LoginRequest" static request filter in the "LoginChain" uses the attribute values to replace the request with an HTTP POST of login form data to log the user in to the protected application.

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

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

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

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

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

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

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

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

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

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

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

The initial OpenIG configuration file should look like the one used to login with a hard-coded username and password, see Configuration for Hard-Coded Credentials.

{
    "name": "LogSink",
    "type": "ConsoleLogSink",
    "config": {
        "level": "DEBUG"
    }
}
   

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

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

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

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

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

Finally, edit the OpenAM demo user to set credentials in the Email Address and Employee Number fields of the demo user profile. In OpenAM console, browse to the user profile under Access Control > / (Top Level Realm) > Subjects > User > demo. Set Email Address to george and Employee Number to costanza.

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

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

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

The filter then uses the access token to validate the token and to retrieve token information from the authorization server. On successful validation, the filter injects the response from the authorization server into exchange.oauth2AccessToken.

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

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

To configure OpenIG as an OAuth 2.0 resource server, replace the config.json file with the new configuration from the example, Configuration for an OAuth 2.0 Resource Server.

Notice "ResourceServer" configuration. This configuration includes a client handler to send access token validation requests, the list of required scopes that the filter expects to find in access tokens, the OpenAM token info endpoint used to validate access tokens, and "enforceHttps": false to allow testing without having to set up keys and certificates. (In production environments, do use HTTPS to protect access tokens.)

When the "ResourceServer" filter has injected information for a valid access token into the exchange, the "CaptureTokenInfo" filter dumps the token information to the log. The "CaptureTokenInfo" filter also injects the credentials from the user profile in OpenAM into the exchange.

Finally, the "LoginRequestFilter" logs a user in to the minimal HTTP server by using the credentials injected from the token information. In this simple configuration, all requests result in login attempts against the minimal HTTP server.

After updating config.json, restart Jetty server so that OpenIG loads the new configuration.

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

$ curl \
 --user "OpenIG:password" \
 --data "grant_type=password&username=demo&password=changeit&scope=mail%20employeenumber" \
 http://openam.example.com:8088/openam/oauth2/access_token
{
    "scope": "mail employeenumber",
    "expires_in": 600,
    "token_type": "Bearer",
    "refresh_token": "7fe9b284-698e-4738-ad11-01b984920861",
    "access_token": "b8102957-486b-47f2-bd2b-54faa55ec363"
}

$ curl \
 --header "Authorization: Bearer b8102957-486b-47f2-bd2b-54faa55ec363" \
 http://www.example.com:8080
...
    <h1>User Information</h1>

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

    <h1>Request Information</h1>

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

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

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

  

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

2014-08-04T16:43:38Z:CaptureTokenInfo.CaptureTokenInfo:INFO:
{
    "access_token": "b8102957-486b-47f2-bd2b-54faa55ec363",
    "mail": "george",
    "employeenumber": "costanza",
    "grant_type": "password",
    "scope": [
        "mail",
        "employeenumber"
    ],
    "realm": "/",
    "token_type": "Bearer",
    "expires_in": 35
}
  

What is happening behind the scenes?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "name": "LogSink",
    "type": "ConsoleLogSink",
    "config": {
        "level": "DEBUG"
    }
}
   

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

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

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

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

Edit the OpenIG client profile to add the Redirection URI http://www.example.com:8080/openid/callback. Also add openid and profile scopes to the Scope(s) list, and then save your work. In this tutorial, you overload these profile settings to pass credentials to OpenIG. This tutorial uses Full Name and Last Name for the sake of simplicity. Both of those attributes are part of a user's profile out of the box with the default OpenAM configuration. Neither of the attributes are needed for anything else in this tutorial. So this tutorial uses Last Name to hold the username, and Full Name to hold the password. In a real deployment, you would no doubt use other attributes, depending upon the user profiles and on your requirements.

Finally, edit the OpenAM demo user to set credentials in the Last Name and Full Name fields of the demo user profile. In OpenAM console, browse to the user profile under Access Control > / (Top Level Realm) > Subjects > User > demo. Set Last Name to george and Full Name to costanza.

To configure OpenIG as an OpenID Connect 1.0 relying party, replace the config.json file with the new configuration from the example, Configuration for an OpenID Connect 1.0 Client.

Also add the DumpExchange.groovy script from that section under $HOME/.openig/scripts/groovy (%appdata%\OpenIG\scripts\groovy on Windows). The script is called from the configuration on failure.

In the new config.json file, consider the "OpenIDConnectClient" filter. This configuration object has the OAuth2ClientFilter in the Reference type. This is the filter that enables OpenIG to act as a relying party.

The filter is configured to work only with a single provider, the OpenAM server you configured in Section 11.4, "Setting Up OpenAM as an OpenID Provider". If you had more than one provider configured, you would need a "loginHandler" as well to help end users pick a provider.

The "OpenIDConnectClient" filter has a base client endpoint of /openid. Incoming requests to /openid/login start the delegated authorization process. Incoming requests to /openid/callback are expected as redirects from the OP (as authorization server), so this is why you set the redirect URI in the client profile in OpenAM to http://www.example.com:8080/openid/callback.

The "OpenIDConnectClient" filter has "requireHttps": false as a convenience for testing. In production environments, require HTTPS.

The filter has "requireLogin": true to ensure you see the delegated authorization process when you make your request.

In the "OpenIDConnectClient" filter, the target for storing authorization state information is ${exchange.openid}, so this is where subsequent filters and handlers can find access token and user information.

The scopes are set to "openid" and "profile" as allowed for OpenID Connect 1.0.

Notice that on failure the filter dumps the current information in the exchange into a web page response to the end user. While this is helpful to you for debugging purposes, it is not helpful to an end user. In production environments, return a more user-friendly failure page.

Also in the "OpenIDConnectClient" filter, the typical "ClientHandler" configures the HTTP client that communicates with the OpenID Provider.

Returning to the top of the configuration, notice that the "OpenIDConnectChain" invokes an "OutgoingChain" handler after the filter injects the access token and user information into exchange.openid. The "OutgoingChain" in this case extracts credentials from the user information by script ("GetCredentials"), and then uses the credentials to log the user in to the minimal HTTP server ("LoginRequestFilter").

In this simple configuration, all successful requests result in login attempts against the minimal HTTP server.

After updating config.json, restart Jetty server so that OpenIG loads the new configuration.

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

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

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

What is happening behind the scenes?

After OpenIG gets the browser request, the "OpenIDConnectClient" filter redirects you to authenticate with OpenAM and consent to authorize access to user information. After you authorize access, OpenAM returns an access token to the filter. The filter then uses that access token to get the user information. Before handling the next filter or handler in the exchange, which is the "OutgoingChain", the filter injects the authorization state information into exchange.openid.

The "OutgoingChain" extracts credentials to re-inject them into the exchange. Its login filter then uses the credentials to log the user in to the minimal HTTP server, which responds with its User Information page.

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

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

The initial OpenIG configuration file should look like the one used to proxy requests through to the HTTP server and to capture request and response data, see Configuration for Proxy & Capture.

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

Routes are configuration objects to handle a particular kind of Exchange.

The particular kind of an Exchange that a Route handles is an Exchange that fits the condition defined for the route. The condition is defined using a OpenIG expression in the Reference, so it can be based on almost any characteristic of the Exchange. Another way to think of the Route is like an independent DispatchHandler in the Reference.

Routes can also have their own names, used to order them lexicographically. If no name is specified, the Route file name is used.

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

Routes wrap a heap of configuration objects, and hand off any Exchange they accept to a handler. In this way each Route is much like one of the server-wide configuration files you have used in other tutorials.

If no condition is specified for the Route, the Route accepts any Exchange. The following is a basic default route that accepts any Exchange and forwards it on without changes. This object explicitly shows you all the fields of the Route object. (You could omit "condition" and "baseURI" here as they have no effect.)

{
    "heap": {
        "objects": [
            {
                "name": "ClientHandler",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "name": "default",
    "condition": null,
    "baseURI": null,
    "handler": "ClientHandler"
}
  

At this point you have configured the Routes, but OpenIG does not route any traffic to them. To use the routes, you must configure a Router.

The Router is a handler that you can configure in the top-level config.json file for OpenIG.^[2] The Router's job is to pass Exchanges to configured Routes, and to periodically reload changed route configurations. As Routes define the conditions on which they accept any given Exchange, the Router does not have to know about specific Routes in advance. In other words, you could configure the Router first and then add Routes while OpenIG is running.

At this point you can try your new Router and Route configurations.

Make a request to hit the ForgeRock.com router.

$ curl --data "site=forgerock" http://www.example.com:8080
...HTML of ForgeRock.com home page...
  

Now make a request to hit the Community page.

$ curl --data "site=community" http://www.example.com:8080
...HTML of ForgeRock.org home page...
  

Now check that the default route still works.

$ curl http://www.example.com:8080 | grep george

   <title>Howdy, george</title>
        <dd>george</dd>

  

What happened behind the scenes?

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

When you issued your second request with HTTP POST form data "site=community", the request matched the condition defined in the Community Route. OpenIG rebased the request and sent it along to http://forgerock.org:80/.

When the third request did not match either of the conditions defined, the Exchange was routed to the default Route (that accepts any Exchange). The static request filter in that route logged George in to the local server listening on http://www.example.com:8081/. The default Route has name "zDefault".

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

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

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

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

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

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

Proxies all requests and captures them in a flat file. Use this template if you need to analyze the traffic for your application. Simply change the baseURI to be that of the target application, restart OpenIG, and login to the application. The entire sequence is logged to the flat file.

    {
    "heap": {
        "objects": [
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "condition": "${exchange.request.uri.scheme == 'http'}",
                            "handler": "OutgoingChain",
                            "baseURI": "http://TARGETIP"
                        },
                        {
                            "condition": "${exchange.request.uri.path == '/login'}",
                            "handler": "LoginChain",
                            "baseURI": "https://TARGETIP"
                        },
                        {
                            "handler": "OutgoingChain",
                            "baseURI": "https://TARGETIP"
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": [],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "CaptureFilter"
                    ],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": false,
                    "file": "/tmp/gateway.log"
                }
            },
            {
                "name": "ClientHandler",
                "comment": "Sends all requests to remote servers.",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "handlerObject": "DispatchHandler"
}
   

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

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

   

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

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

   

For applications that return the login page when the user tries to access a page without a valid session. This template shows how to use the ExtractFilter to find the login page on the response and use the CookieFilter to ensure the cookies from the application are replayed on each request. The sample application in this template is OpenAM. If you change the TARGETIP:PORT to be the IP address of OpenAM, the TARGETDN:PORT to be the fully qualified name and port of OpenAM and modify USERNAME and PASSWORD in the LoginRequest you automatically log USERNAME into OpenAM.

    {
    "heap": {
        "objects": [
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "handler": "FindLoginPageChain",
                            "baseURI": "http://TARGETIP:PORT"
                        }
                    ]
                }
            },
            {
                "name": "FindLoginPageChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "IsLoginPage",
                        "FindLoginPage"
                    ],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "FindLoginPage",
                "type": "EntityExtractFilter",
                "config": {
                    "messageType": "response",
                    "target": "${exchange.isLoginPage}",
                    "bindings": [
                        {
                            "key": "found",
                            "pattern": "OpenAM\s\(Login\)",
                            "template": "true"
                        }
                    ]
                }
            },
            {
                "name": "IsLoginPage",
                "type": "SwitchFilter",
                "config": {
                    "onResponse": [
                        {
                            "condition": "${exchange.isLoginPage.found == 'true'}",
                            "handler": "LoginChain"
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "LoginRequest"
                    ],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "LoginRequest",
                "type": "StaticRequestFilter",
                "config": {
                    "method": "POST",
                    "uri": "http://TARGETIP:PORT/openam/UI/Login",
                    "form": {
                        "IDToken0": [
                            ""
                        ],
                        "IDToken1": [
                            "USERNAME"
                        ],
                        "IDToken2": [
                            "PASSWORD"
                        ],
                        "IDButton": [
                            "Log+In"
                        ],
                        "encoded": [
                            "false"
                        ]
                    },
                    "headers": {
                        "host": [
                            "TARGETFQDN:PORT"
                        ]
                    }
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "CookieFilter",
                        "CaptureFilter"
                    ],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "CookieFilter",
                "type": "CookieFilter",
                "config": {}
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": true,
                    "file": "/tmp/gateway.log"
                }
            },
            {
                "name": "LogSink",
                "comment": "Default sink for logging information.",
                "type": "ConsoleLogSink",
                "config": {
                    "level": "DEBUG"
                }
            },
            {
                "name": "ClientHandler",
                "comment": "Responsible for sending all requests to remote servers.",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "handlerObject": "DispatchHandler"
}

   

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

    {
    "heap": {
        "objects": [
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "condition": "${exchange.request.uri.path == '/login'}",
                            "handler": "LoginChain",
                            "baseURI": "http://TARGETIP"
                        },
                        {
                            "handler": "OutgoingChain",
                            "baseURI": "http://TARGETIP"
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "HiddenValueExtract",
                        "LoginRequest"
                    ],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "HiddenValueExtract",
                "type": "EntityExtractFilter",
                "config": {
                    "messageType": "response",
                    "target": "${exchange.hiddenValue}",
                    "bindings": [
                        {
                            "key": "value",
                            "pattern": "wpLoginToken\"\s.*value=\"(.*)\"",
                            "template": "$1"
                        }
                    ]
                }
            },
            {
                "name": "LoginRequest",
                "type": "StaticRequestFilter",
                "config": {
                    "method": "POST",
                    "uri": "https://TARGETIP/login",
                    "form": {
                        "USER": [
                            "myusername"
                        ],
                        "PASSWORD": [
                            "mypassword"
                        ],
                        "hiddenValue": [
                            "${exchange.hiddenValue.value}"
                        ]
                    }
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "CaptureFilter"
                    ],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": false,
                    "file": "/tmp/gateway.log"
                }
            },
            {
                "name": "ClientHandler",
                "comment": "Responsible for sending all requests to remote servers.",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "handlerObject": "DispatchHandler"
}

   

Proxies traffic to an application listening on ports 80 and 443. The assumption is the application uses HTTPS for authentication and HTTP for the general application features. Assuming the login will all take place on port 443, you will need to add the login filters and handlers to the LoginChain. To get started quickly, modify the baseURI to be the IPAddress of your target application. This should allow you to proxy all traffic to the application. Then add the logic for the LoginChain using the flow from one of the login templates.

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

   

Logs the user into the target application using the headers passed down from an OpenAM policy agent. This template assumes the user name and password are passed down by the OpenAM policy agent as headers. If the header passed in contains only a user name or subject and requires a lookup to an external data source, you must add an attribute filter to the chain to retrieve the credentials.

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

   

A sample template used to log a user into Microsoft Online Outlook Web Access. This template shows how you would use OpenIG and the OpenAM password capture feature to integrate with OWA. You can follow the Tutorial On Password Capture & Replay tutorial and substitute this template.

    {
    "heap": {
        "objects": [
            {
                "name": "LogSink",
                "comment": "Default sink for logging information.",
                "type": "ConsoleLogSink",
                "config": {
                    "level": "DEBUG"
                }
            },
            {
                "name": "DispatchHandler",
                "type": "DispatchHandler",
                "config": {
                    "bindings": [
                        {
                            "condition": "${exchange.request.uri.path == '/owa/auth/logon.aspx'}",
                            "handler": "LoginChain",
                            "baseURI": "https://65.55.171.158"
                        },
                        {
                            "handler": "OutgoingChain",
                            "baseURI": "https://65.55.171.158"
                        }
                    ]
                }
            },
            {
                "name": "LoginChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "CryptoHeaderFilter",
                        "LoginRequest"
                    ],
                    "handler": "OutgoingChain"
                }
            },
            {
                "name": "CryptoHeaderFilter",
                "type": "CryptoHeaderFilter",
                "config": {
                    "messageType": "REQUEST",
                    "operation": "DECRYPT",
                    "algorithm": "DES/ECB/NoPadding",
                    "key": "DESKEY",
                    "keyType": "DES",
                    "charSet": "utf-8",
                    "headers": [
                        "password"
                    ]
                }
            },
            {
                "name": "LoginRequest",
                "type": "StaticRequestFilter",
                "config": {
                    "method": "POST",
                    "uri": "https://65.55.171.158/owa/auth/owaauth.dll",
                    "headers": {
                        "Host": [
                            "red001.mail.microsoftonline.com"
                        ],
                        "Content-Type": [
                            "Content-Type:application/x-www-form-urlencoded"
                        ]
                    },
                    "form": {
                        "destination": [
                            "https://red001.mail.microsoftonline.com/owa/"
                        ],
                        "forcedownlevel": [
                            "0"
                        ],
                        "trusted": [
                            "0"
                        ],
                        "username": [
                            "${exchange.request.headers['username'][0]}"
                        ],
                        "password": [
                            "${exchange.request.headers['password'][0]}"
                        ],
                        "isUtf8": [
                            "1"
                        ]
                    }
                }
            },
            {
                "name": "OutgoingChain",
                "type": "Chain",
                "config": {
                    "filters": [
                        "HeaderFilter",
                        "CaptureFilter"
                    ],
                    "handler": "ClientHandler"
                }
            },
            {
                "name": "HeaderFilter",
                "type": "HeaderFilter",
                "config": {
                    "messageType": "REQUEST",
                    "remove": [
                        "password",
                        "username"
                    ]
                }
            },
            {
                "name": "CaptureFilter",
                "type": "CaptureFilter",
                "config": {
                    "captureEntity": false,
                    "file": "/tmp/gateway.log"
                }
            },
            {
                "name": "ClientHandler",
                "type": "ClientHandler",
                "config": {}
            }
        ]
    },
    "handlerObject": "DispatchHandler"
}

   

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

The following script demonstrates a simple dispatch handler.

import org.forgerock.openig.http.Response
import org.forgerock.openig.io.ByteArrayBranchingStream

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

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

switch (exchange.request.uri.path) {

    case "/login":

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

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

        } else {

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

        }

        break

    default:

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

        break

}

  

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 hard-coded username and password.

/*
 * Perform basic authentication with a hard-coded user name and password.
 */

def credentials = "bjensen:hifalutin".getBytes().encodeBase64().toString()
exchange.request.headers.add("Authorization", "Basic ${credentials}" as String)

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

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

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

  

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

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

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

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

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

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

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

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

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

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

    // Authentication succeeded.

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

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

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

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

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

} catch (AuthenticationException e) {

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

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

} catch (Exception e) {

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

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

} finally {
    client.close()
}

  

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

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

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

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

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

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

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

  

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

import groovy.sql.Sql

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

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

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

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

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

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

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

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

  

The two primary extension points are the interfaces: Filter (for processing a request and/or response en route) and Handler (for generating responses from requests). These interfaces are similar to the Java Enterprise Edition Filter and Servlet interfaces, with some differences in the semantics of messages. While you can simply implement these interfaces, there are also included convenience classes: GenericFilter and GenericHandler that you can use if you intend to make your extensions configurable through the OpenIG configuration resource.

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

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

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

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

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

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

package com.example.filter;

// Java Standard Edition
import java.io.IOException;

// OpenIG Core Library
import org.forgerock.openig.filter.GenericFilter;
import org.forgerock.openig.handler.HandlerException;
import org.forgerock.openig.heap.HeapException;
import org.forgerock.openig.heap.NestedHeaplet;
import org.forgerock.openig.http.Exchange;

public class HelloWorldFilter extends GenericFilter {

    public String name;
    public String value;

    @Override
    public void filter(Exchange exchange, Handler next)
            throws HandlerException, IOException {
        exchange.request.getHeaders().putSingle(name, value); // set header in request
        next.handle(exchange); // pass to remaining filters & handler in chain
        exchange.response.getHeaders().putSingle(name, value); // set header in response
    }

    public static class Heaplet extends NestedHeaplet {

        @Override
        public Object create() throws HeapException {
            HelloWorldFilter filter = new HelloWorldFilter();
            filter.name = config.get("name").required().asString(); // required
            filter.value = config.get("value").required().asString(); // req'd
            return filter;
        }
    }
}  

The corresponding heap object configuration is as follows.

{
     "name": "HelloWorldFilter",
     "type": "com.example.filter.HelloWorldFilter",
     "config": {
         "name": "X-Hello",
         "value": "World" 
     }
}

org.forgerock.json.fluent.JsonValueException: /handlerObject:
   object Router2 not found in heap
    at org.forgerock.openig.heap.HeapUtil.getRequiredObject(HeapUtil.java:69)
    at org.forgerock.openig.servlet.GatewayServlet.init(GatewayServlet.java:188)
    at org.eclipse.jetty.servlet.ServletHolder.initServlet(ServletHolder.java:595)
  

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

HTTP ERROR 500
Problem accessing /. Reason:

Unexpected character (x) at position 1103
  

This error usually means a missing double quote or a missing bracket in the configuration file. Use a JSON editor or JSON validation tool such as JSONLint to make sure your JSON is valid.

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

HTTP ERROR 500

Problem accessing /myURL . Reason:

java.lang.String cannot be cast to java.util.List
Caused by:
java.lang.ClassCastException: java.lang.String cannot be cast to java.util.List
at org.forgerock.openig.filter.LoggingFilter.writeHeaders(LoggingFilter.java:132
at org.forgerock.openig.filter.LoggingFilter.logResponse(LoggingFilter.java:119)
at org.forgerock.openig.filter.LoggingFilter.filter(LoggingFilter.java:86)
at org.forgerock.openig.filter.Chain.handle(Chain.java:54)
  

This error is typically encountered when using the AssignmentFilter in the Reference and setting a string value for one of the Headers. All headers are stored in Lists so the header must be addressed with a subscript. For example, if you try to set exchange.request.headers['Location'] for a redirect in the response object, you should instead set exchange.request.headers['Location'][0]. A header without a subscript leads to the error above.

You must define an entity for the response. For example:

{
    "name": "AccessDeniedHandler",
    "type": "org.forgerock.openig.handler.StaticResponseHandler",
    "config": {
        "status": 403,
        "reason": "Forbidden",
        "entity": "<html><h2>User does not have permission</h2></html>"
    }
}

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

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

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

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

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

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

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

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