Configure MongoDB with Kerberos Authentication on Windows

New in version 2.6.

Overview

MongoDB Enterprise supports authentication using a Kerberosservice. Kerberos is an industry standardauthentication protocol for large client/server system. Kerberos allowsMongoDB and applications to take advantage of existing authenticationinfrastructure and processes.

Prerequisites

Setting up and configuring a Kerberos deployment is beyond the scope ofthis document. This tutorial assumes have configured a Kerberosservice principal for eachmongod.exe and mongos.exe instance.

For replica sets and sharded clusters, ensure that your configurationuses fully qualified domain names (FQDN) rather than IP addresses orunqualified hostnames. You must use the FQDN for GSSAPI to correctlyresolve the Kerberos realms and allow you to connect.

Procedures

Start mongod.exe without Kerberos.

For the initial addition of Kerberos users, start mongod.exewithout Kerberos support.

If a Kerberos user is already in MongoDB and has theprivileges required to create a user, you can startmongod.exe with Kerberos support.

Include additional settings as appropriate to your deployment.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

Connect to mongod.

Connect via the mongo.exe shell to the mongod.exeinstance. If mongod.exe has —auth enabled, ensureyou connect with the privileges required to create a user.

Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM>, toMongoDB in the $external database. Specify the Kerberos realm inALL UPPERCASE. The $external database allowsmongod.exe to consult an external source (e.g. Kerberos)to authenticate. To specify the user’s privileges, assignroles to the user.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

The following example adds the Kerberos principalreportingapp@EXAMPLE.NET with read-only access to therecords database:

  1. use $external
  2. db.createUser(
  3.    {
  4.      user: "reportingapp@EXAMPLE.NET",
  5.      roles: [ { role: "read", db: "records" } ]
  6.    }
  7. )

Add additional principals as needed. For every user you want toauthenticate using Kerberos, you must create a corresponding user inMongoDB.For moreinformation about creating and managing users, seeUser Management Commands.

Start mongod.exe with Kerberos support.

You must start mongod.exe as the service principalaccount.

To start mongod.exe with Kerberos support, setthe mongod.exe parameterauthenticationMechanisms to GSSAPI:

  1. mongod.exe --setParameter authenticationMechanisms=GSSAPI <additional mongod.exe options>

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

For example, the following starts a standalone mongod.exeinstance with Kerberos support:

  1. mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI --bind_ip localhost,<hostname(s)|ip address(es)>

Connect mongo.exe shell to mongod.exe and authenticate.

Connect the mongo.exe shell client as the Kerberosprincipal application@EXAMPLE.NET.

You can connect and authenticate from the command line.

Using cmd.exe:

  1. mongo.exe --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase=$external --username reportingapp@EXAMPLE.NET

Using Windows PowerShell:

  1. mongo.exe --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase='$external' --username reportingapp@EXAMPLE.NET

If you are connecting to a system whose hostname matches theKerberos name, ensure that you specify the fully qualifieddomain name (FQDN) for the —hostoption, rather than an IP address or unqualified hostname.

If you are connecting to a system whose hostname does notmatch the Kerberos name, use —gssapiHostNameto specify the Kerberos FQDN that it responds to.

Alternatively, you can first connect mongo.exe to themongod.exe, and then from the mongo.exe shell, usethe db.auth() method to authenticate in the$external database.

  1. use $external
  2. db.auth( { mechanism: "GSSAPI", user: "reportingapp@EXAMPLE.NET" } )

Additional Considerations

Configure mongos.exe for Kerberos

To start mongos.exe with Kerberos support, set themongos.exe parameter authenticationMechanismsto GSSAPI. You must start mongos.exe as theservice principal account:

  1. mongos.exe --setParameter authenticationMechanisms=GSSAPI <additional mongos options>

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

For example, the following starts a mongos instance withKerberos support:

  1. mongos.exe --setParameter authenticationMechanisms=GSSAPI --configdb shard0.example.net, shard1.example.net,shard2.example.net --keyFile C:\<path>\mongos.keyfile --bind_ip localhost,<hostname(s)|ip address(es)>

Modify or include any additional mongos.exe options as requiredfor your configuration. For example, instead of using—keyFile for internal authentication of sharded clustermembers, you can use x.509 member authentication instead.

Assign Service Principal Name to MongoDB Windows Service

Use setspn.exe to assign the service principal name (SPN) to theaccount running the mongod.exe and the mongos.exe service:

  1. setspn.exe -S <service>/<fully qualified domain name> <service account name>

Example

If mongod.exe runs as a service namedmongodb on testserver.mongodb.com with the service accountname mongodtest, assign the SPN as follows:

  1. setspn.exe -S mongodb/testserver.mongodb.com mongodtest

Incorporate Additional Authentication Mechanisms

Kerberos authentication (GSSAPI (Kerberos))can work alongside:

  • MongoDB’s SCRAM authentication mechanism:
  • MongoDB’s authentication mechanism for LDAP:
  • MongoDB’s authentication mechanism for x.509:

Specify the mechanisms as follows:

  1. --setParameter authenticationMechanisms=GSSAPI,SCRAM-SHA-256

Only add the other mechanisms if in use. This parameter setting doesnot affect MongoDB’s internal authentication of cluster members.