How To
ForgeRock Identity Platform
ForgeRock Identity Cloud

How do I create a custom error page in IG (All versions)?

Last updated Jun 8, 2021

The purpose of this article is to provide information on creating custom error pages in IG for standard response codes.


1 reader recommends this article

Creating a custom error page

You can use the StaticResponseHandler for custom error pages. This handler checks for error codes coming from the backend application and can be used to replace a standard error message with a custom response.

This article includes two examples to get you started:

Multiple error codes

You can also check for a range of error codes rather than just a single code by using a condition such as:

"condition": "${response.status.code >= 500 and response.status.code <= 504}",

Custom text

The examples show custom text being specified in the entity field; if you would prefer to include the custom text in a file, replace the text in the entity field using the read(), Function for example:

"entity": "${read('/home/user/customError.html')}"

Where customError.html is the file that contains your custom text.

403 error page

Here's a simple example that checks for response code 403 and replaces the standard response with the text defined in the entity field:

        "handler": {             "name": "MyChain",             "type": "Chain",             "config": {               "filters": [                 {                   "name": "Switch",                   "type": "SwitchFilter",                   "config": {                     "onResponse": [                       {                         "condition": "${response.status.code == 403}",                         "handler": {                           "type": "StaticResponseHandler",                           "config": {                             "status": 403,                             "reason": "ACCESS DENIED",                             "entity": "<html>403: Access Denied: You do not have permission to view this page.</html>",                             "headers": {                                 "content-type": ["text/html"]                             }                           }                         }                       }                     ]                   }                 }               ],               "handler": {                 "type": "ClientHandler",                 "comment": "Log the request, pass it to the protected application, and then log the response",                 "capture": "all",                 "baseURI": "https://example.com"               }             }           }

500 error page

In this example, by being ahead of the PolicyEnforcementFilter, the StaticResponseHandler will intercept 500 error codes returned by AM’s policy engine and replace them with the text defined in the entity field:

{            "name": "Switch",             "type": "SwitchFilter",             "config": {               "onResponse": [                 {                   "condition": "${response.status.code == 500}",                   "handler": {                     "type": "StaticResponseHandler",                     "config": {                       "status": 500,                       "reason": "ERROR",                       "entity": "<html>500: Custom error page.</html>",                       "headers": {                           "content-type": ["text/html"]                       }                     }                   }                 }               ]             }           },         {          "type": "PolicyEnforcementFilter",           "name": "PolicyEnforcementFilter-1",           "config": {             "amService": "AmService",             "pepRealm": "/",             "application": "PEP policy set",             "ssoTokenSubject": "${contexts.ssoToken.value}"           }         }       ],       "handler": "ClientHandler"     }   } }

The amService property shown in the example above is used in IG 6 and later; it replaces the following removed properties: openamUrl, pepUsername, pepPassword and realm as detailed in IG 6.5 Removed Functionality.

See Also

FAQ: Installing and configuring IG

Installing and configuring IG

PolicyEnforcementFilter

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.