Navigation
This version of the documentation is archived and no longer supported. It will be removed on EOL_DATE. 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.
This version of the manual is no longer supported. It will be removed on EOL_DATE.

Configure the Automation Agent for Kerberos

On this page

MongoDB Enterprise supports

Kerberos. Kerberos is a network authentication protocol. Automation Agent can authenticate to MongoDB instances using Kerberos.

Important

In Ops Manager 1.8 and later, Ops Manager can manage agent authentication if Automation manages agents. Using Automation, you first need to specify the agent’s name, and, if using LDAP authorization, the LDAP group corresponding to the MongoDB role. Ops Manager creates the specified MongoDB user for each agent and configures the appropriate access for that agent user.

See Enable Kerberos Authentication for your Ops Manager Project for more information.

Prerequisites

Configure KDC to Issue Tickets with Four-Hour Minimum Lifetime

Kerberos tickets are only valid, or used to authenticate users, for a limited time. You must configure the Kerberos Key Distribution Center (KDC) to issue tickets that are valid for at least four hours. The Automation Agent periodically renews the ticket. The KDC service provides session tickets and temporary session keys to users and computers.

Add Kerberos as Authentication Mechanism for Deployment

MongoDB agents interact with the MongoDB databases in your deployment as a MongoDB user would. Each agent must be authenticated and then granted privileges according to what their roles are on your deployment. As a result, you must configure your MongoDB deployment and your agents 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 agents to use.

Adding an agent as a MongoDB user requires configuring an authentication mechanism. Agents can use any supported authentication mechanism, but all agents must use the same mechanism.

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

  • Deployment supports Kerberos authentication and
  • Agents use Kerberos authentication.

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

Configure Automation Agent Host to Use Kerberos

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

  • 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 Automation Agent

1

Create or choose a Kerberos UPN for each Agent.

Create or choose a Kerberos User Principal Name (UPN) for the agents you are running. The Monitoring and Backup agent should have their own UPNs.

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, a monitoring agent would set its UPN to: monitoring-agent@EXAMPLE.COM

2

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

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

Create a User and Assign Roles for the Automation Agent UPN

After creating the Kerberos UPN, create a user mapped to the agent’s UPN and grant it privileges on your MongoDB deployment.

Where you create the user depends upon if you are using LDAP authorization:

  • If you are using LDAP authorization, you must create a user and group for the agent on the LDAP server and map the LDAP group to a MongoDB role in your deployment’s admin database.
  • If you are not using LDAP authorization, you must create the agent’s user on the $external database in your MongoDB deployment.

Using LDAP to Authorize the MongoDB Agent User

If you are using LDAP Authorization in your MongoDB deployment, you must manage the MongoDB users for your agents through your LDAP Server.

Warning

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

For each MongoDB user representing an Ops Manager agent:

  1. Create a new LDAP user on your LDAP server named with the Agent’s UPN.
  2. Create an LDAP group whose name matched the agent’s role exactly.
  3. Create the agent’s role in your admin database with the appropriate permissions.
  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 agents Required Access for Backup Agent and Required Access for Monitoring 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.

Using MongoDB to Authorize the MongoDB Agent User

If you are using MongoDB to manage user authorization, you need to add each 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 an external source such as Kerberos.

Note

To discover the appropriate roles for the agents, see Required Access for Backup Agent and Required Access for Monitoring Agent.

From a mongo shell connected to your MongoDB deployment, issue the following commands to create the users:

 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" }
       ]
     }
   )

To learn about the required access for the Automation Agent, see Required Access for Monitoring Agent.

Edit the Automation Agent Configuration File

Edit the Automation Agent configuration file. The following table lists the default installation paths for some common platforms. Depending on your deployment, you may need to substitute the default path for the custom installation path used for your Ops Manager agent installation.

Operating System Path
RHEL, Ubuntu /etc/mongodb-mms/monitoring-agent.config
Linux Archive, macOS <userSelected>/monitoring-agent.config
Windows C:\MMSData\Automation\local.config
1

Add the krb5Principal value.

Set the krb5Principal to the Kerberos UPN for the Agent.

Example

krb5Principal=<agent>-agent@EXAMPLE.COM
2

Add the krb5Keytab value.

Set the krb5Keytab to the complete absolute path of the keytab file for the agent.

Example

krb5Keytab=/etc/mongodb-mms/<agent>-agent.keytab
3

Restart the agent.