Avoiding Pitfalls When Using Unsupported Url Rewrites With Sharepoint

What are URL Rewrites and Why Use Them?

URL rewriting is the process of modifying request URLs on the fly before they are processed by the server. Rewrites create an abstraction layer between the resource’s physical location and the URL used to access it. This allows the underlying resource to change locations without affecting the links used to access it.

The main reasons for using URL rewriting in SharePoint are:

Improve perceived performance by shortening long default URLs
Hide physical server names and directory structures for security
Support migration to new SharePoint environments without broken links
Create custom URLs that match branding or are easier to use

For example, the default URL to a document might be:

Table of Contents

https://mycompany.sharepoint.com/sites/division/departments/engineering/Shared%20Documents/manual.docx

With rewriting, it could become:

https://kb.mycompany.com/engineering/manual

This is much shorter and matches a section of the company intranet for engineering knowledge base articles.

Supported vs Unsupported URL Rewrites in SharePoint

SharePoint provides a built-in capability for URL rewriting of pages and assets through its “Managed Paths” feature. This allows site administrators to define custom URLs for site pages and other components that bypass the long default URLs.

These managed path rewrites are fully supported because they use SharePoint’s internal mapping logic. The platform handles routing requests from the rewritten URLs to the right locations transparently.

However, SharePoint also allows creating custom rewrite rules through Internet Information Services (IIS) that work outside of or extend the supported managed paths. These custom rewrites using IIS URL Rewrite Module are considered unsupported.

Unsupported rewrites come with caveats:

Not maintained during upgrades or migrations
Can break unexpectedly with SharePoint and IIS updates
Harder to troubleshoot issues
Bypass SharePoint security in some configurations

Examples of unsupported rewrites:

Rewrites crossing site collections or IIS web applications
Complex chained/nested rewrites
Rewrites using query string parameters

Common Issues with Unsupported Rewrites

Some common problems that can occur when using complicated unsupported URL rewrites with SharePoint include:

Breaking upgrades or migrations: Custom rewrite rules can stop working when SharePoint or IIS components are upgraded, often with no indication as to why.
Security vulnerabilities: In some cases, overly broad rewrite rules allow bypassing SharePoint permissions and access control.
Performance problems: Unsupported rules often anchor to physical server names and locations, losing out on SharePoint’s load balancing.
Creating circular references: Chained rewrite rules can sometimes loop back on themselves, creating endless redirects.
Interfering with other systems: Rewrites that work for SharePoint can negatively interact with CDNs, proxy servers, firewalls, etc.
Difficulty identifying issues: Cryptic IIS errors rarely point directly to a custom rewrite rule as the culprit when problems emerge.

Identifying Unsupported Rewrites

The first steps in troubleshooting rewrite issues are identifying which rules are in place and determining if any qualify as unsupported configurations per Microsoft’s guidelines.

All implemented rewrite rules can be reviewed in IIS Manager:

Connect to the appropriate SharePoint server in IIS Manager
Navigate to the level matching the web application or site collection with the rewrite issue
Click on the URL Rewrite icon/module
Review the list of inbound and outbound rules

Any custom rules were created manually, while SharePoint’s supported “Managed Paths” rules are identified as such.

Rules crossing web applications, using chained rewrites, matching query strings, or pointing outside the local server can indicate an unsupported configuration. Rewrite conditions and actions that seem overly complex are also signs of an unsupported rule.

Administrators can also review IIS logs during periods of rewrite-related errors. The entries immediately before the error occur will show which rewrite rules were processing the request.

Fixing and Replacing Unsupported Rewrites

The best way to resolve issues with unsupported rewrites is removing them entirely and achieving the same functionality through simpler, supported methods.

Two main options exist:

Managed Paths: If the goal is only URL shortening or hiding internals, implement equivalent managed paths.
Full Redirects: For maintaining legacy URLs or complex rewriting, use permanent IIS redirects instead.

For managed paths:

Identify the site collection, site, library, list or page used.
Check the Managed Paths section in that object’s settings.
Add a custom path that matches the rewrite’s output URL.

For permanent redirects:

Remove the original rewrite rule entirely.
Create a new inbound rule with a 302 Permanent Redirect action.
Send this to the current internal URL rather than rewriting.

This approach prevents further issues down the line, while still sending legacy URLs to the proper place.

Best Practices for Implementing URL Rewrites

When URL rewriting is necessary in SharePoint, admins should follow these best practices to avoid pitfalls:

Start with managed paths: Use OOTB options before custom rewrites.
Stay within the farm: Don’t rewrite across farms or IIS servers.
Limit rule complexity: Simple = stable. Avoid chains and nesting.
Map to internal URLs: Target actual SharePoint paths, not aliases.
Use redirects over rewrites when possible.
Documentation keeps future admins in the know.

Also avoid these common anti-patterns:

Excessively long rename strings
Query string and parameter-based conditions
Attempting to sync edited rules across servers
URLs that route outside the local network

Following these guidelines results in cleaner, more robust rewrite implementations.

Example Code for a Supported Rewrite Rule

Here is sample code for a basic, supported rewrite rule that shortens URLs to documents in one site collection:

“`

“`

Key aspects that identify this as a supported rule:

Operates within one IIS site / web application
Uses a simple relative string replace action
Does not chain multiple complicated conditions
Targets SharePoint content URLs, not physical paths

This avoids potential pitfalls seen with complicated unsupported rules.

Testing and Monitoring Rewrite Rules

Once rewrite rules are in place, admins should thoroughly test them before roll out. This includes:

Clicking sample rewritten links to ensure proper functionality
Accessing content from alternate device types and external networks
Verifying permissions and security using different user accounts
Loading test pages that exercise multiple rewritten URL paths
Checking for signs of redirect loops or excess latency from chains

Production rewrite rules also demand ongoing monitoring, including:

Periodically sampling incoming logs for 404s and unexpected hits
Watching network traffic for redirect chains and latency
Validating permissions and access controls haven’t shifted
Testing again after any related upgrades or patches

Changes in traffic patterns or the appearance of errors warrants deeper investigation of impacted rewrites.

When to Reach Out for Help with Rewrites

If overloaded admins need to implement complex rewrite rules but want to maintain support and stability, the best practice is engaging Microsoft services or expert partners rather than tackling on your own.

Some scenarios where you should reach out for help:

Rewrites crossing IIS sites and server farms
URLs handle by non-SharePoint systems like CDNs
Custom chains for aggregating related content
Migrating legacy URLs during upgrades to new environments
Rewrites tied heavily to custom development work

The right consultants can develop advanced rewrite rules purpose-built for these complex requirements while maintaining support and best practice adherence.

Investing in custom configuration assistance also pays dividends when migrating rewritten links during future upgrades.