Authorable Vanity URLs in Adobe Experience Manager

Vanity URLs are supported out of the box by Adobe Experience Manager (AEM), however authorability can be difficult if the website employs URL shortening or tight Dispatcher URL filters.

One alternative is to handle Vanity URLs at the web server level using Apache RewriteMaps. This simplifies the definition of redirects, and can lighten the load on AEM Publish instances (since these requests at the web server level).

The solution detailed below allows AEM content authors to define their Vanity URLs and redirects using the ACS AEM Commons Redirect Map Manager interface, and have the resulting redirects deployed automatically to Dispatcher servers.

1. The Authoring Environment

The Redirect Map Manager provides an easy authoring interface for creating and managing Redirect Maps (i.e. collections of website redirects and vanity URLs that are packaged and loaded into the AEM Dispatcher as Apache RewriteMaps).

The Redirect Map Manager is part of a free and open source library called ACS AEM Commons, which can be downloaded and installed into an AEM via the Package Manager.

Borrowed directly from the source, here.

Once installed, the Redirect Map Manager provides several different ways to generate and modify Redirect Maps. The documentation here outlines a few.

Once a content author has created a Redirect Map, or has finished updating an existing one, the Redirect Map is activated to the Publish instance. At this point, the Redirect Map is accessible to the Dispatcher instance (detailed in the next section).

 2. Setting up auto-polling on the Dispatcher Instance

The AEM Dispatcher instance is configured to poll the Publish servers for updated Redirect Maps. This is done via a Bash script, which performs a wget to retrieve the Redirect Maps from the Publish instance, and then converts them into Apache RewriteMap format (dbm) using httxt2dbm.

#!/bin/bash
        
# configuration values
PUBLISHER_IP=10.10.15.22
LOG_DIR=/var/log/httpd
MAPS=(
   "mysite-redirectmap"
   "legacy-redirectmap"
)
  
# loop through the defined redirect maps
for MAP_FILE in "${MAPS[@]}"
do
  
  # clear temp directory
  rm -f /tmp/${MAP_FILE}.txt
  
  # download redirect map txt file from publish instances - check to ensure download successful
  if wget http://${PUBLISHER_IP}:4503/etc/acs-commons/redirect-maps/${MAP_FILE}/jcr:content.redirectmap.txt -O /tmp/${MAP_FILE}.txt >> ${LOG_DIR}/update-redirect-map.log 2>&1; then
  
    # convert txt file into apache redirect map
    httxt2dbm -i /tmp/${MAP_FILE}.txt -o /etc/httpd/conf.d/redirectmaps/tmp-${MAP_FILE}.map >> ${LOG_DIR}/update-redirect-map.log 2>&1
    
    # deploy updated redirect map into apache directory
    mv /etc/httpd/conf.d/redirectmaps/tmp-${MAP_FILE}.map.dir /etc/httpd/conf.d/redirectmaps/${MAP_FILE}.map.dir
    mv /etc/httpd/conf.d/redirectmaps/tmp-${MAP_FILE}.map.pag /etc/httpd/conf.d/redirectmaps/${MAP_FILE}.map.pag
  
  fi
  
done

# only requied on RHEL instances
#   update permissions and selinux context on all auto redirect maps
chmod -R 755 /etc/httpd/conf.d/redirectmaps 
chcon -R -t httpd_config_t /etc/httpd/conf.d/redirectmaps

The Publisher IP address and Redirect Map names will need to be configured to match the environment.

Once the script is configured and tested, the next step is to schedule it as a Cron Job. Make sure this is done on all public-facing Dispatcher instances.

Depending on the operating system, scheduling may involve using crontab (for Ubuntu/Debian), or adding a symlink to the script in the /etc/cron.hourly directory (for RHEL/CentOS).

3. Loading the RewriteMap into Apache

Apache directives are added to the Vhost file that instruct Apache to use the newly created RewriteMap.

Below is a sample AEM Dispatcher Apache Vhost config file, with the RewriteMap directives employed on lines 19-22. Make sure the path to the RewriteMap file matches the map output path in the polling script above.

Note: Be sure to run the script at least once prior to adding these directives. Apache will fail to start if no RewriteMap is found at the set location.

#
# Sample AEM Dispatcher vhost for a single site
#
#   Features use of rewritemap, url shortening, root element definition,
#    and ACS Commons sitemap passthrough
#

<VirtualHost *:80>
  
  ServerName https://mysite.org
  ServerAlias mysite.org www.mysite.org kdl20s2pkvjv923.cloudfront.net

  ## Use a doc root that matches what's in the ../conf/publish-farm.any
  DocumentRoot /mnt/var/www/html

  ## Enable Rewrite Engine
  RewriteEngine on

  # Add authorable RewriteMap
  RewriteMap mysiteredirects "dbm:/etc/httpd/conf.d/redirectmaps/mysite-redirectmap.map"
  RewriteCond ${mysiteredirects:$1} !=""
  RewriteRule ^(.*)$ ${mysiteredirects:$1|/} [L,R=301]

  # Root elememt
  RewriteCond %{REQUEST_URI} ^/$
  Rewriterule ^(.*)$ /us/en.html [R=301,L]

  # Sitemap XML - hooks into ACS AEM Commons Sitemap Generator
  RewriteCond %{REQUEST_URI} ^/sitemap.xml$
  Rewriterule ^(.*)$ /content/mysite/us/en.sitemap.xml [PT]

  # URL shortening (i.e. remove /content/mysite/en/us prefix from URLs)
  #  see https://helpx.adobe.com/experience-manager/dispatcher/using/dispatcher-domains.html
  RewriteCond %{REQUEST_URI} !^/apps
  RewriteCond %{REQUEST_URI} !^/bin
  RewriteCond %{REQUEST_URI} !^/content
  RewriteCond %{REQUEST_URI} !^/etc
  RewriteCond %{REQUEST_URI} !^/home
  RewriteCond %{REQUEST_URI} !^/libs
  RewriteCond %{REQUEST_URI} !^/tmp
  RewriteCond %{REQUEST_URI} !^/var
  RewriteRule ^/(.*)$ /content/mysite/us/en/$1 [PT]

  # Load AEM dispatcher module
  <Directory />
    <IfModule disp_apache2.c>
      SetHandler dispatcher-handler
    </IfModule>
    Options FollowSymLinks
    AllowOverride None
    Header always append X-Frame-Options SAMEORIGIN
  </Directory>

  # Additional dispatcher config (not allowed in directory)
  <IfModule disp_apache2.c>
    ## Enabled to allow rewrites to take affect and not be ignored by the dispatcher module
    DispatcherUseProcessedURL 1
    ## Default setting to allow all errors to come from the AEM instance
    DispatcherPassError 0
  </IfModule>

</VirtualHost>

Once the RewriteMap directives have been added and tested (via Apache configtest or otherwise), restarting Apache will bring the Redirects into affect. At this point, the content author’s vanity URLs and redirects are live!

As mentioned earlier, once Apache is configured to use a RewriteMap, it is not required to restart Apache each time the RewriteMap is changed/updated,

Wrapping Up

While the ACS AEM Commons Redirect Map Manager is not exactly the out of the box vanity URL definition provided in AEM, it does allow for more robust support in environments with URL shortening or security related URL filters.

Following AEM’s “everything is content” mentality, redirect maps are defined in the CRX like any other node, and can have normal User & Group ACLs applied to them.

ACS has also taken several steps to improve authorability of Redirect Maps within their tool’s interface. The “Redirect Configuration” section allows authors and administrators to query the CRX and create RedirectMaps automatically based on certain properties (including the standard Vanity URL properties set in Page Properties).

Borrowed directly from the source, here.