Identity Gateway 7.2

Troubleshooting

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to help you set up and maintain your deployments.

Getting support

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock’s support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to everyone, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

Getting info about the problem

When you are trying to solve a problem, save time by asking the following questions:

  • How do you reproduce the problem?

  • What behavior do you expect, and what behavior do you see?

  • When did the problem start occurring?

  • Are their circumstances in which the problem does not occur?

  • Is the problem permanent, intermittent, getting better, getting worse, or staying the same?

If you contact ForgeRock for help, include the following information with your request:

  • The product version and build information. This information is included in the logs when IG starts up. If IG is running in development mode, and set up as described in the Getting started, access the information at http://ig.example.com:8080/openig/api/info.

  • Description of the problem, including when the problem occurs and its impact on your operation.

  • Steps you took to reproduce the problem.

  • Relevant access and error logs, stack traces, and core dumps.

  • Description of the environment, including the following information:

    • Machine type

    • Operating system and version

    • Web server or container and version

    • Java version

    • Patches or other software that might affect the problem

Troubleshooting

Displaying resources
Requests redirected to AM instead of to the resource

By default, ForgeRock Access Management 5 and later writes cookies to the fully qualified domain name of the server; for example, am.example.com. Therefore, a host-based cookie, rather than a domain-based cookie, is set.

Consequently, after authentication through Access Management, requests can be redirected to Access Management instead of to the resource.

To resolve this issue, add a cookie domain to the Access Management configuration. For example, in the Access Management console, go to Configure > Global Services > Platform, and add the domain example.com.

Sample application not displayed correctly

When the sample application is used with IG in the documentation examples, the sample application must serve static resources, such as the .css. Add the following route to the IG configuration, as:

  • Linux

  • Windows

$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{
  "name" : "sampleapp-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css')}",
  "handler": "ReverseProxyHandler"
}
StaticResponseHandler results in a blank page

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

{
  "name": "AccessDeniedHandler",
  "type": "StaticResponseHandler",
  "config": {
    "status": 403,
    "headers": {
      "Content-Type": [ "text/html; charset=UTF-8" ]
    },
    "entity": "<html><body><p>User does not have permission</p></body></html>"
  }
}
Using routes
No handler to dispatch to

If you get the message no handler to dispatch to, consider the following points:

  • Make sure that your routes include a condition configuration to match the request. For more information, see Set Route Conditions.

  • If requests might not match any condition, consider adding a default route to provide a default handler when no condition is met. For more information, see Adding a Default Route.

Object not found in heap

If you see the following error, you have specified "handler": "Router2" in config.json or in the route, but no handler configuration object named Router2 exists:

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)

Make sure you have added an entry for the handler, and that you have correctly spelled its name.

Extra or missing character / invalid JSON

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

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

Route not used

IG loads all configurations at startup, and, by default, periodically reloads changed route configurations.

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

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

Of course, if you restart IG with an invalid route configuration, then IG 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.

Skip routes

IG returns an exception if it loads a route for which it can’t resolve a requirement. For example, when you load a route that uses an AmService object, the object must be available in the AM configuration.

If you add routes to a configuration when the environment is not ready, rename the route to prevent IG from loading it. For example, rename a route as follows:

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

If necessary, restart IG to reload the configuration. When you have configured the environment, change the file extension back to .json.

Using Studio
Can’t deploy routes in Studio

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 creating routes in Studio, see the Studio guide.

Understanding timeout errors
Timeout downloading large files

(Not supported for IG in standalone mode.) If SocketTimeoutException errors occur in the logs when you try to download large files, in your ReverseProxyHandler or ClientHandler, increase soTimeout and set asyncBehavior to streaming.

Log is flushed with timeout exception warnings on sending a request

Problem: After a request is sent to IG, IG seems to hang. An HTTP 502 Bad Gateway error is produced, and the IG log is flushed with SocketTimeoutException warnings.

Possible cause: The baseURI configuration is missing or causes the request to return to IG, so IG can’t produce a response to the request.

Possible solution: Configure the baseURI to use a different host and port to IG.

Other problems
Incorrect values in the flat files

Make sure that the user running IG can read the flat file. Remember that values include spaces and tabs between the separator, so make sure the values are not padded with spaces.

Problem accessing URLs

The following error can be encountered when using an AssignmentFilter as described in AssignmentFilter and setting a string value for one of the headers.

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

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.