Using Kerberos to authenticate Sitecore 8 to MongoDB 2.6 on Windows Server 2012

Overview

If you are configuring Sitecore 8 to authenticate against an on-premise MongoDB instance using Kerberos, you might run into issues getting the different environments in sync. In order to get them talking successfully, you need to be aware of the different settings to configure and how small missteps can cause communication failures.

This article will discuss some of those settings and possible issues you might encounter when running MongoDB 2.6 on Windows Server. Note that as of Sitecore 8.0u3, MongoDB 3.0 is not supported.

 

Configuring Kerberos

Before worrying about getting Sitecore to talk to MongoDB, it's important to verify you have Kerberos working correctly. Running through those steps is outside the scope of this article, but let's review the basic steps for getting Kerberos working on MongoDB:

1. Create A-Records for your MongoDB host
2. Create a service account to run MongoDB
3. Create a root user in the $external database
4. Install mongod.exe as a service
5. Create a Service Principal Name for the service
6. Configure the mongod.exe service to run using the service account
7. Verify connectivity using mongo.exe

Configuring Users

Case sensitivity is very important both to MongoDB and to Kerberos. You need to make sure that you maintain the casing of your user when you configure Sitecore and when you configure MongoDB.

Let's first go through the places where a user is specified, then touch on what you need to know to configure each of them.

The places where you'll specify the user are:

• AppPoolIdentity - The identity of the Application Pool that is running Sitecore
• AuthenticatedUser - The user MongoDB sees when you connect (this will be the same user as the AppPoolIdentity, but it WILL be case sensitive)
• ConnectionStringUser - The user you specify in your MongoDB connection strings
• ExternalUser - The user who was created in the $external database and who has permissions to see the Sitecore databases

 

AppPoolIdentity

You have two options for who runs the Sitecore application pool. You can either leave it as Network Service, or you can set it to run as a domain user. The option you choose will impact how you configure Sitecore to talk to MongoDB.

• Option 1 - You run Sitecore as a domain user.
• e.g., SCKerberos@REALM.COM
• Option 2 - You run Sitecore as Network Service

Note: Since IIS is not case sensitive, this setting is also not case sensitive.

AuthenticatedUser  
When you talk to MongoDB, you'll be doing it as a user. This user will be based on the SSPI principal and will be the case sensitive name of the AppPoolIdentity.

In the MongoDB logs, you'll see this log entry:

• Option 1
• [conn1] SSPI authenticated name: SCKerberos@REALM.COM
• Option 2
• [conn1] SSPI authenticated name: HOSTNAME$@REALM.COM

Note: This is case sensitive and will come from Active Directory.

ConnectionStringUser

In your connection strings, you'll specify the user who has permissions to access the MongoDB databases that Sitecore uses. The value you use here should match the AppPoolIdentity user.

Although you are running Sitecore as a specific user, you still need to pass the user in your connection string. In addition, you need to tell the MongoDB driver which authentication mechanism to use to authenticate the user.

Here is a connection string from ConnectionStrings.config for connecting to the analytics database on a server named "mongo.realm.com" that is running a standalone mongo instance. Note the use of "%40" to escape the "@" symbol, which is part of a Kerberos principal name, but is reserved in the MongoDB connection string.

• Option 1:

<add name="analytics" connectionString="mongodb://SCKerberos%40REALM.COM@mongo.realm.com/analytics?authMechanism=GSSAPI"/>

• Option 2

<add name="analytics" connectionString="mongodb://HOSTNAME$%40REALM.COM@mongo.realm.com/analytics?authMechanism=GSSAPI"/>

In the MongoDB logs, you'll see whatever value you set there in this log entry:

• Option 1
• [conn1] SSPI name provided by client: SCKerberos@REALM.COM
• Option 1
• [conn1] SSPI name provided by client: HOSTNAME$@REALM.COM 

Note: Since this user will be checked against the $external user list, it will be case sensitive

ExternalUser

You'll grant permissions in the $external database for Sitecore on any relevant databases. This user must match the name specified in your ConnectionStringUser.

Here are the commands you might use to create your users.

• Option 1

use $external
db.createUser(
    {
        user: "SCKerberos@REALM.COM",
        roles:
        [
            { role: "readWrite", db: "analytics" },
            { role: "readWrite", db: "tracking_live" },
            { role: "readWrite", db: "tracking_history" },
            { role: "readWrite", db: "tracking_contact" }
        ]
    }
)

• Option 2

use $external
db.createUser(
    {
        user: "HOSTNAME$@REALM.COM",
        roles:
        [
            { role: "readWrite", db: "analytics" },
            { role: "readWrite", db: "tracking_live" },
            { role: "readWrite", db: "tracking_history" },
            { role: "readWrite", db: "tracking_contact" }
        ]
    }
)

Note: This is case sensitive

Troubleshooting

When you attempt to connect, MongoDB will recognize the connection as coming from the AuthenticatedUser. It will then compare this to the ConnectionStringUser to make sure they match. If they match, it will then look for a user in the $external database that matches the AuthenticatedUser.

The default log level for MongoDB may not give enough details to find mismatches like this. You can increase the logging detail by specifying the --setParameter logLevel=5 option when you start up mongod.exe.

Here are some common issues:

• If your AuthenticatedUser and ConnectionStringUser do not match, you'll see a log entry like this:
• [conn1] GSSAPI authentication failed for sckerberos@REALM.COM on $external ; AuthenticationFailed SASL(-13): authentication failure: saslServerConnAuthorize: Requested identity not authenticated identity
• If your AuthenticatedUser does not match the AuthenticatedUser, you'll see a log entry like this:
• [conn1] auxpropMongoDBInternal failed to find privilege document: UserNotFound Could not find user SCKerberos@REALM.COM@$external
• If you are using a replica set, you need to make sure your connection strings include it. Here's an example of a connection to the analytics database on a replica set using Kerberos:
• <add name="analytics" connectionString="mongodb://SCKerberos%40REALM.COM@mongo1.realm.com,mongo2.realm.com/analytics?replicaSet=rsSitecore&amp;authMechanism=GSSAPI"/>

Other Considerations

While Kerberos does use SPNs, you will not need one for the Sitecore instance. Since Sitecore will be running as a user already, the ticket it creates will be based on that identity.

If you are using replica sets, you'll also need to use a keyfile since you will be running mongod.exe with the --auth flag.

Summary 

MongoDB can use Kerberos for authentication when working with Sitecore. However, it's important to make sure you pay attention to how you configure Sitecore. Something as simple as missing case sensitivity on a user in your connection string can be difficult to track down.