--- title: Not-enforced URIs description: By default, IG routes protect resources (such as a websites or applications) from all requests on the route's condition path. Some parts of the resource, however, do not need to be protected. For example, it can be okay for unauthenticated requests to access the welcome page of a web site, or an image or favicon. component: pinggateway version: 2023.11 page_id: pinggateway:gateway-guide:not-enforced-uri canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/not-enforced-uri.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-06-07T15:12:25Z keywords: ["Configuration", "Authentication", "URI"] superseded_by: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/not-enforced-uri.html section_ids: not-enforced-uri-switch: Implement not-enforced URIs with a SwitchFilter not-enforced-uri-dispatch: Implement not-enforced URIs with a DispatchHandler --- # Not-enforced URIs By default, IG routes protect resources (such as a websites or applications) from all requests on the route's condition path. Some parts of the resource, however, do not need to be protected. For example, it can be okay for unauthenticated requests to access the welcome page of a web site, or an image or favicon. The following sections give examples of routes that do not enforce authentication for a specific request URL or URL pattern, but enforce authentication for other request URLs: ## Implement not-enforced URIs with a SwitchFilter Before you start: * Prepare IG and the sample app as described in the [Quick install](../getting-started/preface.html) * Install and configure AM on , using the default configuration. 1. On your system, add the following data in a comma-separated value file: * Linux * Windows ``` /tmp/userfile.txt ``` ``` C:\Temp\userfile.txt ``` ```csv username,password,fullname,email george,C0stanza,George Costanza,george@example.com kramer,N3wman12,Kramer,kramer@example.com bjensen,H1falutin,Babs Jensen,bjensen@example.com demo,Ch4ng31t,Demo User,demo@example.com kvaughan,B5ibery12,Kirsten Vaughan,kvaughan@example.com scarter,S9rain12,Sam Carter,scarter@example.com ``` 2. Set up AM: 1. (From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources: * `http://ig.example.com:8080/*` * `http://ig.example.com:8080/*?*` 2. Select Applications > Agents > Identity Gateway and register an IG agent with the following values: * Agent ID: `ig_agent` * Password: `password` For AM 6.5.x and earlier versions, register an agent as described in [Register an IG agent in AM 6.5 and earlier](preface.html#register-agent-65). | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | Use secure passwords in a production environment. Consider using a password manager to generate secure passwords. | 3. (Optional) Authenticate the agent to AM as described in [Authenticate an IG agent to AM](preface.html#authenticate-agent-am). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | IG agents are automatically authenticated to AM by a deprecated authentication module in AM. This step is currently optional, but will be required when authentication chains and modules are removed in a future release of AM. | 3. Set up IG: 1. Set an environment variable for the IG agent password, and then restart IG: ```bash $ export AGENT_SECRET_ID='cGFzc3dvcmQ=' ``` The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded. 2. Add the following route to IG to serve the sample application .css and other static resources: * Linux * Windows ``` $HOME/.openig/config/routes/00-static-resources.json ``` ``` %appdata%\OpenIG\config\routes\00-static-resources.json ``` ```json { "name" : "00-static-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}", "handler": "ReverseProxyHandler" } ``` 3. Add the following route to IG: * Linux * Windows ``` $HOME/.openig/config/routes/not-enforced-switch.json ``` ``` %appdata%\OpenIG\config\routes\not-enforced-switch.json ``` ```json { "properties": { "notEnforcedPathPatterns": "^/home|^/favicon.ico|^/css" }, "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam/" } } ], "name": "not-enforced-switch", "condition": "${find(request.uri.path, '^/')}", "baseURI": "http://app.example.com:8081", "handler": { "type": "Chain", "config": { "filters": [ { "name": "SwitchFilter-1", "type": "SwitchFilter", "config": { "onRequest": [{ "condition": "${find(request.uri.path, '&{notEnforcedPathPatterns}')}", "handler": "ReverseProxyHandler" }] } }, { "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "type": "PasswordReplayFilter", "config": { "loginPage": "${true}", "credentials": { "type": "FileAttributesFilter", "config": { "file": "/tmp/userfile.txt", "key": "email", "value": "${contexts.ssoToken.info.uid}@example.com", "target": "${attributes.credentials}" } }, "request": { "method": "POST", "uri": "http://app.example.com:8081/login", "form": { "username": [ "${attributes.credentials.username}" ], "password": [ "${attributes.credentials.password}" ] } } } } ], "handler": "ReverseProxyHandler" } } } ``` Notice the following features of the route: * The route condition is `/`, so the route matches all requests. * The SwitchFilter passes requests on the path `^/home`, `^/favicon.ico`, and `^/css` directly to the ReverseProxyHandler. All other requests continue the along the chain to the SingleSignOnFilter. * If the request does not have a valid AM session cookie, the SingleSignOnFilter redirects the request to AM for authentication. The SingleSignOnFilter stores the cookie value in an `SsoTokenContext`. * Because the PasswordReplayFilter detects that the response is a login page, it uses the FileAttributesFilter to replay the password, and logs the request into the sample application. 4. Test the setup: 1. If you are logged in to AM, log out and clear any cookies. 2. Access the route on the not-enforced URL . The home page of the sample app is displayed without authentication. 3. Access the route on the enforced URL . The SingleSignOnFilter redirects the request to AM for authentication. 4. Log in to AM as user `demo`, password `Ch4ng31t`. The PasswordReplayFilter replays the credentials for the demo user. The request is passed to the sample app's profile page for the demo user. ## Implement not-enforced URIs with a DispatchHandler To use a DispatchHandler for not-enforced URIs, replace the route in [Implement not-enforced URIs with a SwitchFilter](#not-enforced-uri-switch) with the following route. If the request is on the path `^/home`, `^/favicon.ico`, or `^/css`, the DispatchHandler sends it directly to the ReverseProxyHandler, without authentication. It passes all other requests into the Chain for authentication. ```json { "properties": { "notEnforcedPathPatterns": "^/home|^/favicon.ico|^/css" }, "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam/" } } ], "name": "not-enforced-dispatch", "condition": "${find(request.uri.path, '^/')}", "baseURI": "http://app.example.com:8081", "handler": { "type": "DispatchHandler", "config": { "bindings": [ { "condition": "${find(request.uri.path, '&{notEnforcedPathPatterns}')}", "handler": "ReverseProxyHandler" }, { "handler": { "type": "Chain", "config": { "filters": [ { "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "type": "PasswordReplayFilter", "config": { "loginPage": "${true}", "credentials": { "type": "FileAttributesFilter", "config": { "file": "/tmp/userfile.txt", "key": "email", "value": "${contexts.ssoToken.info.uid}@example.com", "target": "${attributes.credentials}" } }, "request": { "method": "POST", "uri": "http://app.example.com:8081/login", "form": { "username": [ "${attributes.credentials.username}" ], "password": [ "${attributes.credentials.password}" ] } } } } ], "handler": "ReverseProxyHandler" } } } ] } } } ```