AEM Dispatcher Series 6 - Handling Vanity URLs, Sessions, and /renders

If you’ve followed this series so far, you already know how Dispatcher caches and filters incoming requests.

In this part, we dive into what happens before content is cached (how Dispatcher selects and routes traffic to Publish renders) and after caching (how Dispatcher handles authenticated user sessions and author-configured vanity URLs).

Here is a breakdown of the three key areas:

• /renders: Connecting Dispatcher to multiple AEM Publish instances for load balancing and failover.
• /sessionmanagement: Safely managing authenticated user sessions without leaking private cached data.
• Vanity URLs: Handling short author-defined paths cleanly between Apache mod_rewrite and Dispatcher.

1. Understanding /renders: Connecting Dispatcher to AEM Publish Instances

The /renders section in dispatcher.any defines the backend AEM Publish servers responsible for generating uncached content.

Whenever Dispatcher receives a request that isn't already cached in the docroot, it delegates the request to one of the Publish instances defined in /renders.

Example: Multi-Publish Render Configuration

/renders {
  /publish1 {
    /hostname "publish1.mycompany.com"
    /port "4503"
    /timeout "30"
  }
  /publish2 {
    /hostname "publish2.mycompany.com"
    /port "4503"
    /timeout "30"
  }
}

Key Behaviors:

• Load Balancing: Dispatcher balances uncached requests across available render instances.
• Automatic Failover: If publish1 stops responding or times out, Dispatcher immediately reroutes requests to publish2.

Sticky Connections with /stickyConnectionsFor

If your site contains multi-step wizards or form submissions where subsequent requests must stay on the same Publish node:

/stickyConnectionsFor "/content/mysite/en/checkout"

This pins the user's session to the specific Publish server that handled the initial request.

2. Handling Logged-In Users: /sessionmanagement

By default, Dispatcher is designed for public anonymous traffic. When an AEM site includes private user dashboards, portals, or account pages, caching authenticated responses publicly would expose private customer data.

The /sessionmanagement section isolates authenticated user traffic.

Example: Basic /sessionmanagement

/sessionmanagement {
  /directory "/opt/dispatcher/sessions"
  /encode "md5"
  /header "Cookie:login-token"
  /timeout "300"
}

Best Practice: Explicitly Deny Caching for Secure Paths

Even with session management enabled, always enforce explicit cache deny rules for sensitive paths:

/cache {
  /rules {
    /0000 { /glob "*.html" /type "allow" }
    /0001 { /glob "/content/mysite/en/account/*" /type "deny" }
  }
}

3. Handling Vanity URLs with Dispatcher and mod_rewrite

Authors frequently define vanity URLs in AEM Page Properties (e.g. /contact or /offers) to avoid exposing long paths like /content/mysite/en/company/contact-us.html.

Because Dispatcher inspects paths before AEM's internal resource resolver, you should handle vanity mapping at the Apache mod_rewrite layer.

Example: Apache Rewrite Rules

Add these rewrite rules in your virtual host configuration before the Dispatcher handler executes:

RewriteEngine On

# Map clean vanity paths to physical JCR content paths
RewriteRule ^/offers$ /content/mysite/en/offers.html [PT,L]
RewriteRule ^/contact$ /content/mysite/en/company/contact-us.html [PT,L]

The [PT] (Pass Through) flag is critical: it directs Apache to hand off the rewritten URI directly to the Dispatcher module for caching and filter inspection.

Testing Vanity URL Resolution

Verify the rewrite and dispatcher filters using curl:

curl -I -k https://www.mysite.com/contact

If you receive HTTP 200 OK, the rewrite rule and Dispatcher filters are properly aligned. If you receive HTTP 404 or 403, verify that /filter in dispatcher.any permits the target .html path.

4. Complete dispatcher.any Farm Example

Here is how /renders, /filter, /cache, and /sessionmanagement come together in a production farm:

/farms {
  /mysite {
    /virtualhosts { "www.mysite.com" "mysite.com" }

    /renders {
      /publish1 { /hostname "10.0.1.10" /port "4503" /timeout "30" }
      /publish2 { /hostname "10.0.1.11" /port "4503" /timeout "30" }
    }

    /filter {
      /0000 { /type "deny"  /url "/*" }
      /0001 { /type "allow" /url "/content/mysite/*" }
      /0002 { /type "allow" /url "/etc.clientlibs/*" }
      /0003 { /type "deny"  /url "/system/*" }
    }

    /cache {
      /docroot "/opt/dispatcher/cache"
      /rules {
        /0000 { /glob "*.html" /type "allow" }
        /0001 { /glob "/content/mysite/en/account/*" /type "deny" }
      }
    }

    /sessionmanagement {
      /directory "/opt/dispatcher/sessions"
      /encode "md5"
      /header "Cookie:login-token"
      /timeout "300"
    }

    /statfileslevel "3"
  }
}

5. Developer Troubleshooting Checklist

Key Takeaways

• /renders handles backend Publish connectivity, timeout thresholds, and failover.
• /sessionmanagement isolates authenticated user caching, but private account paths should always be denied in /cache.
• Vanity URLs are most reliably resolved at the Apache mod_rewrite layer using the [PT] flag.

Next: Part 7 — AEM Dispatcher Troubleshooting: A Developer’s Debugging Playbook