Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.

Configure the MongoDB Agent for Kerberos

On this page

MongoDB Enterprise supports Kerberos. Kerberos is a network authentication protocol. The MongoDB Agent can authenticate to MongoDB instances that run Kerberos.

Prerequisites

Configure KDC to Issue Tickets with Four-Hour Minimum Lifetime

Kerberos tickets can authenticate users for a limited time. You must configure the Kerberos Key Distribution Center (KDC) to issue tickets that are valid for four hours or longer. The MongoDB Agent periodically renews the ticket. The KDC service provides session tickets and temporary session keys to users and hosts.

Add Kerberos as Authentication Mechanism for Deployment

The MongoDB Agent interacts with the MongoDB databases in your deployment as a MongoDB user would. As a result, you must configure your MongoDB deployment and the MongoDB Agent to support authentication.

You can specify the deployment’s authentication mechanisms when adding the deployment, or you can edit the settings for an existing deployment. At minimum, the deployment must enable the authentication mechanism you want the MongoDB Agent to use. The MongoDB Agent can use any supported authentication mechanism.

For the purposes of this tutorial, you must ensure the following:

  • Your deployment supports Kerberos authentication and
  • MongoDB Agent uses Kerberos authentication.

To learn how to enable Kerberos authentication, see Enable Kerberos Authentication for your Ops Manager Project.

Configure MongoDB Agent Host to Use Kerberos

Two Kerberos-related files must be installed on any host running Monitoring or Backup:

  • Create or configure the krb5.conf Kerberos configuration file.

    Platform Default Path Notes
    Linux /etc/krb5.conf  
    macOS /etc/krb5.conf (10.7+) The configuration file has varied with previous versions of Mac OS X. Refer to the documentation for your Kerberos implemention for your version of Mac OS X to find out where the Kerberos configuration file is stored.
    Windows %WINDIR%\krb5.ini This is the default path for non-Active Directory-based Kerberos implementations. Refer to the documentation for your Kerberos implemention for your version of Windows to find out where the Kerberos configuration file is stored.

  • On Linux systems: ensure kinit binary is located at /usr/bin/kinit. kinit obtains or renews a Kerberos ticket-granting ticket, which authenticates the Agent using Kerberos.

Procedures

Create Kerberos User Principal for the MongoDB Agent

1

Create or choose a Kerberos User Principal Name (UPN) for the MongoDB Agent.

An UPN is formatted in two parts so the service can be uniquely identified across the Kerberos realm:

Component Description
Service name The name of one service a host is providing to the Kerberos realm, such as pop, snmp, or ftp.
Kerberos realm

A set of managed hosts and services that share the same Kerberos database.

Note

By Kerberos naming convention, the <KERBEROS_REALM> must be in all UPPERCASE.

Example

In a Kerberos realm set as EXAMPLE.COM, the MongoDB Agent would set its UPN to: mongodb-agent@EXAMPLE.COM

2

Generate a keytab file for the Kerberos UPN of the MongoDB Agent.

Generate a keytab file (*.keytab) for the MongoDB Agent UPN and copy it to the host that runs the MongoDB Agent. Ensure that the operating system user that runs the MongoDB Agent is the same operating system user that owns the keytab file.

Create a User and Assign Roles for the MongoDB Agent UPN

When Automation is activated, Ops Manager manages MongoDB Agent authentication.

To configure Kerberos for MongoDB Agent authentication, see Enable Kerberos Authentication for your Ops Manager Project.

After creating the Kerberos UPN for the MongoDB Agent, create a MongoDB user on your deployment that corresponds to the MongoDB Agent’s UPN and grant it privileges.

Where you create the MongoDB user depends upon whether or not you are using LDAP authorization.

If you are using LDAP authorization in your MongoDB deployment, you must create an LDAP user and LDAP group for the MongoDB Agent on the LDAP server. After creating the LDAP user and group, map the LDAP group to a MongoDB role in your deployment’s admin database.

Warning

When using LDAP Authorization, do not create any MongoDB users in the $external database. MongoDB 3.4 and later does not start if a MongoDB user exists in the $external database and LDAP authorization is enabled.

For the MongoDB user representing the MongoDB Agent:

  1. Create a new LDAP user on your LDAP server named with the MongoDB Agent’s UPN.

  2. Create an LDAP group whose name matches the MongoDB Agent’s role.

  3. Create the MongoDB Agent’s role in your admin database with the appropriate permissions.

    Note

    When Automation is activated, Automation automatically creates a role for for the MongoDB Agent user for LDAP authentication.

  4. Assign the LDAP user to the LDAP group.

See also

To learn how to: See
Create an LDAP user Documentation for your LDAP implementation.
Create an LDAP group Documentation for your LDAP implementation.
Assign the appropriate roles for the MongoDB Agent Required Access for MongoDB Agent.
Map an LDAP group and MongoDB role LDAP Roles section of the LDAP authorization page in the MongoDB manual.
Configure LDAP authorization without Ops Manager automation LDAP Authorization page in the MongoDB manual.

If you are not using LDAP authorization, you must add the MongoDB Agent’s UPN as a user in $external database in your MongoDB deployment. Without LDAP authorization, MongoDB uses the $external database to authenticate a user against Kerberos.

Note

To discover the appropriate roles for the MongoDB Agent, see Required Access for MongoDB Agent.

From mongosh, issue the following commands to create the MongoDB user:

copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
   db.getSiblingDB("$external").createUser(
     {
       user : "<Kerberos Principal>",
       roles : [ 
         { role : "clusterAdmin", db : "admin" },
         { role : "readWriteAnyDatabase", db : "admin" },
         { role : "userAdminAnyDatabase", db : "admin" },
         { role : "dbAdminAnyDatabase", db : "admin" },
         { role : "backup", db : "admin" },
         { role : "restore", db : "admin" }
       ]
     }
   )

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.