How To

How do I configure IG (All versions) to access unprotected static content and resources?

Last updated May 8, 2020

The purpose of this article is to provide information on configuring IG to not enforce authorization when accessing unprotected static content and resources (such as graphics, images and CSS files). This is effectively the same as a Not-Enforced URL list.


Overview

When IG is protecting an application with a specific endpoint (such as /login), any static content and resources that are outside of that context (such as /static) will not be accessible. To make them available, you must either configure a separate route or the web container:

  • If the resources are on a different server to IG: you must configure a separate route for static content and resources. See Configuring a route section for further information.
  • If the resources are on the same server as IG: you can configure the web application container to serve the files instead. See Configuring the web application container section for further information.

If you do not configure this correctly, IG will not be able to retrieve these files when you access the application via IG and you will see 404 Not Found responses. The resources will be available when the application is accessed directly.

Configuring a route

You can create a separate route with route conditions to make the static content and resources publicly available so they are accessible to IG. This route is effectively specifying a Not-Enforced URL list.

The following examples demonstrate how you might construct your conditions:

  • The following route specifies file types that should be publicly accessible:
    {
       "name" : "public_access",
       "baseURI" : "https://example.com", 
       "condition": "${contains(request.uri.path, '.css') or contains(request.uri.path, '.ico') or matches(request.uri.path, '.js$') or contains(request.uri.path, '.jpeg') or contains(request.uri.path, '.gif') or contains(request.uri.path, '.png') or contains(request.uri.path, '.jpg')}",
       "handler" : "ReverseProxyHandler"
    }
  • The following route does not enforce authorization on a request where the URI contains .css .svg, and .png file types:
    {
       "name" : "not_enforced",
       "baseURI" : "https://example.com", 
       "condition": "${matches(request.uri.path, '^/login') and matches(request.uri.path,'(\\\\.css|\\\\.svg|\\\\.png)$')}",
       "handler" : "ReverseProxyHandler"
    }

See Gateway Guide › Setting Route Conditions and Configuration Reference › Expressions  for further information.

Note

Customizing or building expressions for IG is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Configuring the web application container

You can configure your web application container to serve the static content and resources if they are on the same server as IG. The following example demonstrates doing this for Apache Tomcat™ but you can do something similar if you use Jetty® or JBoss®.

Note

It is recommended that the resources you want to serve are located in a directory that is outside of the WEB-INF directory and the WAR file.

Tomcat Example

Edit the server.xml file to add a context path to the resources you want to serve. This is done by adding a Context element with the docbase attribute to indicate where the files are located and the path attribute to indicate the URL path they should be served on. For example:

  <Host appBase="webapps"
           autoDeploy="false" name="localhost" unpackWARs="true"
           xmlNamespaceAware="false" xmlValidation="false">
    ...
    <Context docBase="/path/to/static/files" path="/static" />
  </Host>

This solution is discussed in more detail in this blog: Serving static content (including web pages) from outside of the WAR using Apache Tomcat.

See Also

FAQ: Installing and configuring IG/OpenIG

Gateway Guide › Configuring Routes

Related Training

ForgeRock Identity Gateway Core Concepts (IG-400)

Related Issue Tracker IDs

OPENIG-3066 (Expose ResourceHandler as a configurable handler that can be added to an IG config)



Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.
Loading...