Connecting to MongoDB and Azure DocumentDB in Sitecore over SSL

Refuting Connection Refused

I've wrote a little recent about Sitecore Azure PaaS and using Azure's DocumentDB MongoDB API. If you're enough to use it, there is one more interesting but easy issue to overcome. You have to modify Sitecore to connect to MongoDB over SSL.

Error: Target Machine Actively Refused Connection

By default Sitecore's MongoDB driver does use an encrypted connection. Azure's DocumentDB (and there MongoDB API) only work with encrypted connections. So when you try to connect out-of-the-box say with Sitecore 7.x or 8.x you'll get errors.

Enabled SSL In MongoDB

Sitecore, you are so beautiful. Your pipeline-based architecture is here to save us yet again. The MongoDB Driver configuration pipeline is found at /configuration/sitecore/pipelines/updateMongoDriverSettings.

At Fishtank, this is the config file we use to enable an SSL connection to DocumentDB.

<configuration xmlns:patch="">
        <processor type="Fishtank.Pipelines.MongoDBConfiguration.EnableAzureSSL,Fishtank.Pipelines.MongoDBConfiguration" />

And here is the code for the pipeline.

using Sitecore.Analytics.Pipelines.UpdateMongoDriverSettings;
using MongoDB.Driver;
using System.Security.Authentication;

namespace Fishtank.Pipelines.MongoDBConfiguration
    public class EnableAzureSSL : UpdateMongoDriverSettingsProcessor
        public override void UpdateSettings(UpdateMongoDriverSettingsArgs args)
            if (args?.MongoSettings == null) return;

            args.MongoSettings.UseSsl = true;
            args.MongoSettings.VerifySslCertificate = false;
            args.MongoSettings.SslSettings = new SslSettings
                EnabledSslProtocols = SslProtocols.Tls12

Install Into Sitecore Via Package

If you're standing up a net-new Sitecore PaaS instance on Azure, the easiest way to get this change in (especially if you're just experimenting) is to use Sitecore's default package installer.

Installing the package below will drop a standalone assembly and supporting config into the appropriate folders:



DocumentDB forces a secure connection. This makes a lot of sense. When MongoDB hosted on-prem it can be unencrypted because it's behind a firewall. But DocumentDB is a service that by definition will live external to your infrastruct1ure (virtually defined or hybrid networks aside) so it makes sense to force encryption. If you hit this hiccup, hopefully this helps shortcut the problem for you. Thanks!

👋 Hey Sitecore Enthusiasts!

Sign up to our bi-weekly newsletter for a bite-sized curation of valuable insight from the Sitecore community.

What’s in it for you?

  • Stay up-to-date with the latest Sitecore news
  • New to Sitecore? Learn tips and tricks to help you navigate this powerful tool
  • Sitecore pro? Expand your skill set and discover troubleshooting tips
  • Browse open careers and opportunities
  • Get a chance to be featured in upcoming editions
  • Learn our secret handshake
  • And more!
Sitecore Snack a newsletter by Fishtank Consulting

Meet Dan Cruickshank

President | Sitecore MVP x 11

Dan is the founder of Fishtank. He's a multi-time Sitecore MVP and Coveo MVP award winner. Outside of technology, he is widely considered to be a top 3 father (routinely receiving "Father of the Year" accolades from his family) and past his prime on the basketball court.

Connect with Dan