:orphan:

.. _redhat-enterprise-linux-identity-management:

===================================================================
Configure Red Hat Enterprise Linux Identity Management with MongoDB
===================================================================

.. default-domain:: mongodb

.. include:: /includes/attention-docs-eol.rst


.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: twocols

Overview
--------

`Red Hat Enterprise Linux (RHEL) 6.4 <https://www.redhat.com/products/enterprise-linux/>`_
and up includes a complete
`Identity Management solution <https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Identity_Management_Guide/index.html>`_
called Red Hat Enterprise Linux IdM. IdM integrates Kerberos authentication, directory
services, certificate management, DNS, and NTP into a single service.

MongoDB Enterprise can leverage RHEL IdM's Kerberos authentication and
certificate management infrastructure to generate and maintain the SSL
certificates required to encrypt data in motion. The following guide
provides instructions for integrating MongoDB Enterprise with RHEL IdM.

Requirements
------------

- Red Hat Enterprise Linux instance with IdM server deployed (see
  `Installing IdM Server
  <https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Identity_Management_Guide/installing-ipa.html>`_ for
  more information)

- `MongoDB Enterprise 2.4
  <http://www.mongodb.com/products/mongodb-enterprise>`_

Setup Procedure
---------------

Preparing a New MongoDB Server for Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You will need to install MongoDB and the RHEL IdM client pacakages on
your RHEL IdM client instance.

1. Install MongoDB Enterprise. MongoDB Enterprise has additional
   requirements: you should first download and install those packages,
   and then download the archive for MongoDB Enterprise. The following
   commands download the prerequisite packages and then download and
   untar the MongoDB Enterprise package.

   .. code-block:: sh

      yum install openssl net-snmp net-snmp-libs net-snmp-utils cyrus-sasl cyrus-sasl-lib cyrus-sasl-devel cyrus-sasl-gssapi

      curl http://downloads.mongodb.com/linux/mongodb-linux-x86_64-subscription-rhel62-2.4.4.tgz > mongodb.tgz
      tar -zxvf mongodb.tgz
      cp -R -n mongodb-linux-x86_64-subscription-rhel62-2.4.4/ mongodb

   For a more detailed MongoDB installation tutorial, or to install an
   older version of MongoDB Enterprise (pre 2.4.x), see
   :manual:`Installing MongoDB Enterprise
   </tutorial/install-mongodb-enterprise/>`.

2. Next install the IdM client and tools:

   .. code-block:: sh

      yum install ipa-client ipa-admintools

Configure Hostname and DNS Resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For RHEL IdM's services (e.g. Kerberos) to function properly, you must
set a hostname on the system and update its
DNS server to point to the RHEL IdM server instance IP address. You can
update the hostname using commands that resemble the following:

.. code-block:: sh

    $ nano /etc/sysconfig/network
    HOSTNAME=idmclient.example.com
    $ service network restart
    $ hostname -f idmclient.example.com

Next, update the DNS settings to point to the IP address of the RHEL
IdM server:

.. code-block:: sh

    $ nano /etc/resolv.conf
    search example.com
    nameserver 10.192.206.229

Install the IdM Client
~~~~~~~~~~~~~~~~~~~~~~

.. note::

   To run the IdM client installation you will need to have an
   adminstrative user (e.g. admin@EXAMPLE.COM) complete the enrollment
   process.

Having installed MongoDB Enterprise and correctly configured your
Hostname and DNS Resolution, you can install the RHEL IdM client. The
installation process provides prompts for guidance.

If the IdM server was properly configured and the DNS information in
the previous step is correct, the process should be able to auto-detect
the required information.

If the auto-detection fails, consult the `IdM client documentation <https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Identity_Management_Guide/setting-up-clients.html>`_.

If your installation is successful, the client installation process
should return something that resembles the following:

.. code-block:: sh

    $ ipa-client-install --enable-dns-updates
    Discovery was successful!
    Hostname: idmclient.example.com
    Realm: EXAMPLE.COM
    DNS Domain: example.com
    IPA Server: idmhost.example.com
    BaseDN: dc=example,dc=com

A prompt will ask if you wish to configure the system using the
auto-detected values. You should answer yes, as in the following:

.. code-block:: sh

    Continue to configure the system with these values? [no]: yes
    User authorized to enroll computers: admin@EXAMPLE.COM
    Synchronizing time with KDC...
    Password for admin@EXAMPLE.COM:
    Enrolled in IPA realm EXAMPLE.COM
    Created /etc/ipa/default.conf
    New SSSD config will be created
    Configured /etc/sssd/sssd.conf
    Configured /etc/krb5.conf for IPA realm EXAMPLE.COM
    trying https://idmhost.example.com/ipa/xml
    Hostname (idmclient.example.com) not found in DNS
    DNS server record set to: idmclient.example.com -> 10.190.178.79
    Adding SSH public key from /etc/ssh/ssh_host_dsa_key.pub
    Adding SSH public key from /etc/ssh/ssh_host_rsa_key.pub
    Forwarding 'host_mod' to server u'https://idmhost.example.com/ipa/xml'
    SSSD enabled
    Configured /etc/openldap/ldap.conf
    NTP enabled
    Configured /etc/ssh/ssh_config
    Configured /etc/ssh/sshd_config
    Client configuration complete.

Add Reverse DNS Lookup for the Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After installing the IdM client, you must authenticate with Kerberos
as an administrative user (e.g. admin@EXAMPLE.COM) using the following
command:

.. code-block:: sh

    $ kinit admin

This enables you to access the :program:`ipa` command-line interface.

You will also need to add a reverse DNS entry to the IdM server.
[SOMETHING] uses the reverse DNS entry to ensure that Kerberos
authentication works properly.

To add a reverse DNS entry, you must first add a reverse DNS zone,
and then add a PTR record pointing to the IdM client host.

.. example::

   This example uses the following sample information:

   - IdM server hostname: ``idmhost.example.com``

   - IdM client hostname: ``idmclient.example.com``

   - IdM client IP address: ``1.2.3.4``

   - Reverse DNS name: ``3.2.1.in-addr.arpa.`` (reversed first three octets of the IP address)

   - DNS record: ``4`` (last octet of the IP address)

   The first command adds a reverse DNS zone.

   .. code-block:: sh

       $ ipa dnszone-add 178.190.10.in-addr.arpa. --name-server idmhost.example.com. --force

   The command will return output that resembles the following:

   .. code-block:: sh

       Zone name: 3.2.1.in-addr.arpa.
       Authoritative nameserver: idmhost.example.com.
       Administrator e-mail address: hostmaster.3.2.1.in-addr.arpa.
       SOA serial: 1372133625
       SOA refresh: 3600
       SOA retry: 900
       SOA expire: 1209600
       SOA minimum: 3600
       BIND update policy: grant EXAMPLE.COM krb5-subdomain 3.2.1.in-addr.arpa. PTR;
       Active zone: TRUE
       Dynamic update: FALSE
       Allow query: any;
       Allow transfer: none;

   Next, you will add a PTR record pointing to the IdM client host,
   using the following command:

   .. code-block:: sh

       $ ipa dnsrecord-add 3.2.1.in-addr.arpa. 79 --ptr-hostname idmclient.example.com.

   .. note::

      You **must** place a period (``.``) after zone names and host names.

Configure Authentication Type
-----------------------------

RHEL IdM supports authentication using Kerberos and also provides
support for SSL certificate management. The following sections provide
instructions for configuring authentication options.

Configure Kerberos Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now that you have successfully configured the RHEL IdM client and your
MongoDB server, you must create a MongoDB service entry on the IdM
server. This enables RHEL IdM to generate a keytab file, which MongoDB
requires in order to use Kerberos for user authentication.

1. Create the service entry:

   .. code-block:: sh

      ipa service-add mongodb/idmclient.example.com

   .. note::

      The service name must be ``mongodb/[hostname]@[domain]`` in order to
      be valid

2. Retrieve the MongoDB keytab file and place it on the IdM client:

   .. code-block:: sh

      ipa-getkeytab -s idmhost.example.com -p mongodb/idmclient.example.com -k /etc/mongodb.keytab

   To verify the keytab file is correct, use the :program:`klist`
   command to confirm principal naming details, use the following
   command:

   .. code-block:: sh

      klist -k /etc/mongodb.keytab

   The command should return the following output:

   .. code-block:: sh

      Keytab name: FILE:/etc/mongodb.keytab
      KVNO Principal
      ---- --------------------------------------------------------------------------
      1 mongodb/idmclient.example.com@EXAMPLE.COM

Configure SSL Certificate Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to Kerberos, RHEL IdM also provides support for SSL
certificate management. RHEL IdM can generate certificates for a MongoDB
server and MongoDB clients. This enables encryption "in-motion"
among MongoDB instances and from MongoDB clients.

1. To generate a MongoDB server certificate, first issue a certificate
   request using a command that resembles the following:

   .. code-block:: sh

      ipa-getcert request -r -f /etc/cert/mongodb-server.crt -k /etc/cert/mongodb-server.key -N CN=idmclient.example.com -D idmclient.example.com -K mongodb/idmclient.example.com

    Hostnames for the ``-D`` and ``CN`` parameters must match the
    hostname of the MongoDB server. The principal name for the
    ``-K`` parameter must match the MongoDB service name created
    when configuring Kerberos authentication.

#. When the request returns, concatenate the :file:`mongodb-server.key`
   and :file:`mongodb-server.crt` files to create a ``pem`` file:

   .. code-block:: sh

      cat /etc/cert/mongodb-server.key /etc/cert/mongodb-server.crt > /etc/cert/mongodb-server.pem

   .. note::

      The owner and group owner of the ``pem`` file must match the
      user that MongoDB is running under

MongoDB 2.4 supports the notion of a certificate authority (CA) that
cna establish a "trust chain" of certificates to verify authenticity.
On RHEL 6.x systems with the IdM client configured, you can access the
certificate authority at :file:`/etc/ipa/ca.crt`.

To generate a MongoDB client certificate, issue another certificate
request and create a ``pem`` file, with the following sequence of
commands:

.. code-block:: sh

   ipa-getcert request -f /etc/cert/mongodb-client.crt -k /etc/cert/mongodb-client.key
   cat /etc/cert/mongodb-client.key /etc/cert/mongodb-client.crt > /etc/cert/mongodb-client.pem

When the command returns, you will have created the
certificates necessary for MongoDB to operate with SSL (i.e. the server
certificate, CA certificate, and the client certificate).

Refer to the steps in :manual:`Connect to MongoDB with SSL
</tutorial/configure-ssl>` to configure MongoDB to use SSL encryption.

Next Steps
----------

Now that you have successfully set up RHEL Identity Management, and
configured Kerberos, you can refer to the following documents for further
configuration options and deployment instructions.

.. class:: toc

   :manual:`Deploying MongoDB with Kerberos authentication </tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
      Detailed instructions for deploying MongoDB using Kerberos
      authentication, including creating user privilege documents,
      staring MongoDB with Kerberos support, and provides
      troubleshooting guidelines.

   :doc:`Operational Procedures using RHEL IdM </tutorial/manage-red-hat-enterprise-linux-identity-management>`
      Details procedures for adding a new user, granting users access
      privileges, revoking access, and configuring password policies
      using RHEL IdM.

Additionally, consider the specific driver references for configuring
MongoDB drivers to connect to MongoDB using Kerberos authentication.

