Bug #13455


Switch from WPMU Domain Mapping to Mercator

Added by Raymond Hoh almost 3 years ago. Updated almost 3 years ago.

Priority name:
Category name:
Domain Mapping
Target version:
Start date:
Due date:
% Done:


Estimated time:
Deployment actions:


We currently use the WPMU Domain Mapping plugin to provide mapped domains, however that plugin doesn't get many updates and the code quality could be improved.

Mercator is Human Made's alternative to domain mapping and has better support for object caching and SSO.

This also gives us a chance to stop redirecting logged-in users to the Commons subdomain (#5525). We did this to ensure login requests and the admin dashboard are served over HTTPS. However, since IT has implemented Let's Encrypt, we no longer need to do this.

I'm targetting this for 1.18.

Related issues

Related to CUNY Academic Commons - Feature #5525: Mapped domains should be administered over *.commons.gc.cuny.eduResolvedRaymond Hoh2016-05-03

Related to CUNY Academic Commons - Support #13379: Commenting issue with Mapped Domain (Using Jetpack)ResolvedRaymond Hoh2020-09-24

Related to CUNY Academic Commons - Bug #13947: Elementor plugin problemResolvedRaymond Hoh2021-02-05

Actions #1

Updated by Raymond Hoh almost 3 years ago

  • Related to Feature #5525: Mapped domains should be administered over * added
Actions #2

Updated by Raymond Hoh almost 3 years ago

  • Related to Support #13379: Commenting issue with Mapped Domain (Using Jetpack) added
Actions #3

Updated by Raymond Hoh almost 3 years ago

Mercator is now available for testing on cdev.

The biggest user-facing changes are:
  • We no longer redirect mapped domains back to the Commons subdomain when attempting to go to the site's admin dashboard.
  • Single sign-on (SSO) now works if you attempt to login from a mapped domain. Or if you are logged into the Commons and then attempt to navigate to a mapped domain.

For super administrators, mapped domain administration now takes place at "Network Admin > Sites > All Sites" and clicking on the individual site, followed by the new "Aliases" tab to add or remove a domain.

To those that want to test SSO with a mapped domain on cdev, you'll need to adjust the HOSTS file on your computer with the following:

With the HOSTS file change applied, next:

1. Login at
2. Navigate to
3. You should notice a brief delay, followed by a redirect, and then you should be logged in at

If you are not logged into, you might have blocked third-party cookies in your browser. If that is the case, add a cookie exception for in your browser and reload the page.

If you log out from via the WP toolbar, you will also be logged out of the Commons as well.

I've also tested other iterations like logging in from or first and I was able to login successfully.

To accomplish this, technically, there were a few hoops I had to jump through.

(This is mostly for Boone and Jeremy. However if you're not interested, you can stop reading!)

Full commit log:

1. Cross-domain SSO requires cookies to set some additional parameters

For relatively newer browsers, in order for SSO to take place across different domains, some additional parameters need to be set for WP's auth cookies. Namely SameSite to None and since our site is served over HTTPS, the Secure flag also needs to be set.

More info can be found here:

As of right now, WordPress doesn't support these cookie flags natively. So I had to install the SameSite Cookie Manager plugin as a must-use plugin.

One problem with setting these cookie flags is older browsers will not read these flags correctly. This most likely means that SSO will not work in these cases. The article I linked to above lists the affected browsers:

  • Any browser on iOS 12. This affects the following devices: iPhone 5S, iPhone 6/6 Plus and iPod Touch (6th gen).
  • Safari on MacOS 10.14.
  • Chrome 51–66.
  • UC Browser < 12.13.2 for Android

I don't think this is a major issue, but if it is, a workaround would be to do some user-agent sniffing for the browsers listed before setting the cookies. I also haven't tested any of these older versions, but if it is important, I can do so.

2. Mercator patches

There are several patches that I've sent upstream to the main Mercator plugin. I'll list some of the main ones below and what they address:

And a few patches that I haven't sent upstream:

  • Load SSO javascript asynchronously. Read the commit message instead :) The SSO JS script loads up WordPress via admin-ajax.php and does some redirections, so the load time will take a bit longer than usual. Basically, moving to async helps to speed up the pageload time when on a mapped domain for visitors that are not apart of the Commons.
  • Add redirect module. Mercator has a separate module housed at a different Github repository for redirecting subdomains to mapped domains. I just moved the code into the mercator directory for better management.

3. Removal of older subdomain / HTTPS workarounds

I've mostly undone the work from #3587, #3890 and #5525 because HTTPS is now enforced on the Commons unlike before when we had a mix of HTTP and HTTPS assets. There are probably some other parts of the codebase that can benefit from a HTTPS audit, but for now, we're good.

I've also tested other things that might affect Mercator such as the upcoming two-factor feature and they work together well.

If anyone notices any problems on cdev, please let me know.

Actions #4

Updated by Boone Gorges almost 3 years ago

Hi Ray,

Thank you so much for working through this! I have been reading through your commits and PRs and also testing on cdev and I am pleased and impressed with the thorough and careful approach to the swap-out.

I have a question about redirect_to behavior. I tested the following:

1. Type into a browser
2. I'm led to
3. After entering credentials and clicking Log In, I'm led back to the same wp-login.php URL after some redirects. In the network tab, I see the following chain of requests:
- POST (this is the initial login request, which seems right)
- 302 to (this appears to be the correct behavior of wp-login.php's redirect_to parameter)
- 302 to This is the part that seems incorrect. I'm guessing that the asynchronous SSO for isn't completing before the wp-admin page loads.
- 302 to - is this the default Mercator behavior, to redirect logins through the main site?

This kind of flow feels important for two reasons. One is that admin notification emails - say, comment approval - will contain wp-admin links that should be properly redirected.

The other is that a future integration with CUNY's SSO may depend on this redirect behavior. There are many details to work out on that end, but I assume that part of the process will be for the IDP to send identity headers back to a central URL - maybe - from which point we will redirect to the originally requested URL.

Actions #5

Updated by Raymond Hoh almost 3 years ago

Thanks for testing, Boone.

I have a question about redirect_to behavior.

I thought I tested navigating directly to a mapped domain's admin URL when logged out, but I might have tested when I disabled the redirect to the main site to login.

Anyway, your bug is valid and I've worked around this by changing the login URL redirect.

Now, this is how the redirection works:

1. Go to
2. This takes you to the main site's login page -

What's happening here is I changed the redirect_to parameter here from to
3. After login, you get redirected to the mapped domain's frontend where Mercator's async SSO kicks in and you should be logged into the mapped domain.
4. Now, the final redirect occurs from the frontend's redirect_to and should take you to

This is available for testing on cdev. (Commit -

I believe this workflow will work with CUNY SSO. We just have to make sure we forward any mapped domain admin URLs first to the frontend and later back to the admin area.

Actions #6

Updated by Boone Gorges almost 3 years ago

Thanks, Ray! I've tested the new behavior and it looks good to me.

I'm still not 100% clear on how the CUNY SSO integration will work - Mercator or not - but your solution seems like it should be good. We'll assess after I've started that investigation.

Actions #7

Updated by Raymond Hoh almost 3 years ago

Hi Boone, I updated the ACTION_REQUIRED wiki entry yesterday. Let me know if you have any questions about the upgrade flow.

I'm also going to merge the mercator branch into 1.18.x branch to avoid having to maintain two branches.

Actions #8

Updated by Boone Gorges almost 3 years ago

Thanks, Ray!

Actions #9

Updated by Boone Gorges almost 3 years ago

  • Status changed from New to Resolved

The migration is complete and mapping seems to be working properly. See eg

Actions #10

Updated by Raymond Hoh over 2 years ago

  • Related to Bug #13947: Elementor plugin problem added

Also available in: Atom PDF