From cd59416dc4801c586c0fe1ba136e08b3a635197b Mon Sep 17 00:00:00 2001 From: ravind Date: Mon, 21 Nov 2016 18:35:04 -0500 Subject: [PATCH] DOCS-9079: Kerberos/Active Directory tutorial Tutorial covers using Kerberos for authentication and Active Directory for authorization. This is an Enterprise Only feature. --- source/core/kerberos.txt | 3 + .../fact-confirm-enterprise-binaries.rst | 3 +- ...s-kerberos-auth-activedirectory-authz.yaml | 625 ++++++++++++++++++ .../kerberos-auth-activedirectory-authz.txt | 210 ++++++ 4 files changed, 840 insertions(+), 1 deletion(-) create mode 100644 source/includes/steps-kerberos-auth-activedirectory-authz.yaml create mode 100644 source/tutorial/kerberos-auth-activedirectory-authz.txt diff --git a/source/core/kerberos.txt b/source/core/kerberos.txt index a3e5bda2b16..a59a34e8389 100644 --- a/source/core/kerberos.txt +++ b/source/core/kerberos.txt @@ -1,3 +1,5 @@ +.. _security-kerberos: + ======================= Kerberos Authentication ======================= @@ -219,3 +221,4 @@ for details. /tutorial/control-access-to-mongodb-with-kerberos-authentication /tutorial/control-access-to-mongodb-windows-with-kerberos-authentication /tutorial/troubleshoot-kerberos + /tutorial/kerberos-auth-activedirectory-authz.txt diff --git a/source/includes/fact-confirm-enterprise-binaries.rst b/source/includes/fact-confirm-enterprise-binaries.rst index f72ffdf51f5..f55bca53564 100644 --- a/source/includes/fact-confirm-enterprise-binaries.rst +++ b/source/includes/fact-confirm-enterprise-binaries.rst @@ -1,4 +1,5 @@ -To verify MongoDB Enterprise binaries: +To verify MongoDB Enterprise binaries, pass the ``--version`` command line +option to the :program:`mongod` or :program:`mongos`: .. code-block:: sh diff --git a/source/includes/steps-kerberos-auth-activedirectory-authz.yaml b/source/includes/steps-kerberos-auth-activedirectory-authz.yaml new file mode 100644 index 00000000000..9117d7842c9 --- /dev/null +++ b/source/includes/steps-kerberos-auth-activedirectory-authz.yaml @@ -0,0 +1,625 @@ +title: Configure TLS/SSL for the server running MongoDB. +stepnum: 1 +ref: security-kerberos-activedirectory-authauthz-configTLS +level: 4 +content: | + + To connect to the :abbr:`AD (Active Directory)` (AD) server via TLS/SSL, the + :program:`mongod` or :program:`mongos` require access to the :abbr:`AD + (Active Directory)` server's Certificate Authority (CA) certificate. + + On Linux, specify the :abbr:`AD (Active Directory)` server's CA certificates + via the ``TLS_CACERT`` or ``TLS_CACERTDIR`` option in the ``ldap.conf`` file. + + Your platform's package manager creates the ``ldap.conf`` file while + installing MongoDB Enterprise's ``libldap`` dependency. For complete + documentation on the configuration file or the referenced options, see + `ldap.conf `_. + + On Microsoft :abbr:`Windows (Microsoft Windows)`, load the :abbr:`AD (Active + Directory)` server's Certificate Authority (CA) certificates with the + platform's credential management tool. The exact credential management tool + is :abbr:`Windows (Microsoft Windows)` version dependent. To use the tool, + refer to its documentation for your version of :abbr:`Windows (Microsoft + Windows)`. + + If :program:`mongod` or :program:`mongos` cannot access to the :abbr:`AD + (Active Directory)` CA files, they cannot create TLS/SSL connections to the + Active Directory server. + + Optionally, set :setting:`security.ldap.transportSecurity` to ``none`` + to disable TLS/SSL. + + .. warning:: + + Setting :setting:`~security.ldap.transportSecurity` to ``none`` transmits + plaintext information, including user credentials, between MongoDB and + the :abbr:`AD (Active Directory)` server. + +--- +title: (Windows only) Assign Service Principal Name to MongoDB Windows Service. +stepnum: 2 +ref: security-kerberos-activedirectory-authauthz-Windowsspn +level: 4 +pre: | + + For MongoDB servers running on the :abbr:`Windows (Microsoft Windows)` + operating system, you must use `setspn.exe + `_ to + assign the service principal name (SPN) to the account running the MongoDB + service. + + .. code-block:: powershell + + setspn.exe -S / + + .. example:: + + For example, if a :program:`mongod` runs as a service named ``mongodb`` on + ``mongodbserver.example.com`` with the service account name + ``mongodb_dev@example.com``, the command to assign the SPN would look as + follows: + + .. code-block:: powershell + + setspn.exe -S mongodb/mongodbserver.example.com mongodb_dev@example.com + + .. note:: + + :abbr:`Windows (Microsoft Windows)` Server 2003 does not support + ``setspn.exe -S``. For complete documentation on ``setspn.exe``, see + `setspn.exe + `_. + +--- +title: (Linux only) Create keytab file for the MongoDB server. +stepnum: 2 +ref: security-kerberos-activedirectory-authauthz-keytab +level: 4 +content: | + + For MongoDB servers running on the Linux platform, you must ensure the + server has a copy of the :ref:`keytab file ` specific to the + MongoDB instance running on that server. + + You must grant the Linux user running the MongoDB service read permissions + on the keytab file. Take note of the full path of the keytab file location. + +--- +title: Connect to the MongoDB server. +stepnum: 4 +ref: security-nativeldap-activedirectory-preconnect +level: 4 +pre: | + + Connect to the MongoDB server using the :program:`mongo` shell using the + :option:`--host` and :option:`--port` options. + + .. code-block:: shell + + mongo --host --port + + If your MongoDB server currently enforces authentication, you must + authenticate to the ``admin`` database as a user with role management + privileges, such as those provided by :authrole:`userAdmin` or + :authrole:`userAdminAnyDatabase`. Include the appropriate + :option:`--authenticationMechanism` for the + MongoDB server's configured authentication mechanism. + + .. code-block:: shell + + mongo --host --port --username --password --authenticationDatabase="admin" --authenticationMechanism="" + + .. note:: + + For :abbr:`Windows (Microsoft Windows)` MongoDB deployments, you should replace :program:`mongo` with + :program:`mongo.exe` + +--- +title: Create user administrative role. +ref: security-nativeldap-activedirectory-authz-userAdmin +level: 4 +stepnum: 5 +pre: | + + To manage MongoDB users using :abbr:`AD (Active Directory)`, you need to + create at least one role on the ``admin`` database that can create and + manage roles, such as those provided by :authrole:`userAdmin` or + :authrole:`userAdminAnyDatabase`. + + The role's name must exactly match the Distinguished Name of an :abbr:`AD + (Active Directory)` group. The group must have at least one :abbr:`AD + (Active Directory)` user as a member. + + Given the available :ref:`Active Directory groups + `,the following operation: + + - Creates a role named for the :abbr:`AD (Active Directory)` group + ``CN=dba,CN=Users,DC=example,DC=com``, and + + - Assigns it the :authrole:`userAdminAnyDatabase` role on the ``admin`` + database. + + .. code-block:: javascript + + var admin = db.getSiblingDB("admin") + admin.createRole( + { + role: "CN=dba,CN=Users,DC=example,DC=com", + privileges: [], + roles: [ "userAdminAnyDatabase" ] + } + ) + + You could alternatively grant the :authrole:`userAdmin` role for each + database the user should have user administrative privileges on. These roles + provide the necessary privileges for role creation and management. + + .. important:: + + Consider applying the `principle of least privilege + `_ + when configuring MongoDB roles, :abbr:`AD (Active Directory)` groups, or group + membership. + +--- +title: Create a MongoDB configuration file. +stepnum: 6 +ref: security-kerberos-activedirectory-authauthz-configfile +level: 4 +pre: | + + A MongoDB :doc:`configuration file ` is a + plain-text YAML file with the ``.conf`` file extension. + + * If you are upgrading an existing MongoDB deployment, copy the + current configuration file and work from that copy. + + * (Linux Only) If this is a new deployment *and* you used your platform's + package manager to install MongoDB Enterprise, the installation includes + the ``/etc/mongod.conf`` default configuration file. Use that default + configuration file, or make a copy of that file to work from. + + * If no such file exists, create an empty file with the ``.conf`` extension + and work from that new configuration file. + +--- +title: Configure MongoDB to connect to Active Directory`. +stepnum: 7 +ref: security-kerberos-activedirectory-authauthz-configuremongodb +level: 4 +pre: | + + In the MongoDB configuration file, set :setting:`security.ldap.servers` to + the host and port of the :abbr:`AD (Active Directory)` server. If your + :abbr:`AD (Active Directory)` infrastructure includes multiple :abbr:`AD + (Active Directory)` servers for the purpose of replication, specify the host + and port of the servers as a comma-delimited list to + :setting:`security.ldap.servers`. + + .. example:: + + To connect to an :abbr:`AD (Active Directory)` server located at + ``activedirectory.example.net``, include the following in the + configuration file: + + .. code-block:: yaml + + security: + ldap: + servers: "activedirectory.example.net" + + MongoDB must bind to the :abbr:`AD (Active Directory)` server to perform queries. By + default, MongoDB uses the simple authentication mechanism to bind itself to + the :abbr:`AD (Active Directory)` server. + + Alternatively, you can configure the following settings in the configuration + file to bind to the :abbr:`AD (Active Directory)` server using ``SASL``: + + - Set :setting:`security.ldap.bind.method` to ``sasl`` + + - :setting:`security.ldap.bind.saslMechanisms`, specifying a string of + comma-separated SASL mechanisms the :abbr:`AD (Active Directory)` server + supports. + + This tutorial uses the default ``simple`` LDAP authentication mechanism. + +--- +title: Configure MongoDB for Kerberos authentication. +stepnum: 8 +ref: security-kerberos-activedirectory-authauthz-configurebinding +level: 4 +pre: | + + In the MongoDB configuration file, set :setting:`security.authentication` to + `enabled` and :setting:`setParameter` :parameter:`authenticationMechanisms` + to ``GSSAPI`` + + + To enable authentication via Kerberos, include the following in + the configuration file: + + .. code-block:: yaml + + security: + authentication: "enabled" + setParameter: + authenticationMechanisms: "GSSAPI" + +--- +title: Configure LDAP Query Template for authorization. +ref: security-kerberos-activedirectory-authauthz-querytemplate +level: 4 +stepnum: 9 +pre: | + + In the MongoDB configuration file, set + :setting:`security.ldap.authz.queryTemplate` to an `RFC4516 + `_ formatted LDAP query URL template. + In the template, use the ``{USER}`` placeholder to substitute the + authenticated username into the LDAP query URL. Design the query template to + retrieve the authenticated user's groups. + + .. note:: + + A full description of `RFC4515 `_, + RFC4516, or :abbr:`AD (Active Directory)` queries is out of scope for + this tutorial. The :setting:`~security.ldap.authz.queryTemplate` provided + in this tutorial is an example only, and may not be applicable for your + specific :abbr:`AD (Active Directory)` deployment. + + .. example:: + + The following query template returns any groups that list ``{USER}`` as a + member, following recursive group memberships. This LDAP query assumes + that group objects track user membership by storing full user + Distinguished Name (DN) using the ``member`` attribute. The query + includes the :abbr:`AD (Active Directory)` specific matching rule OID + ``1.2.840.113556.1.4.1941`` for `LDAP_MATCHING_RULE_IN_CHAIN + `_. This + matching rule is an :abbr:`AD (Active Directory)` specific extension to + LDAP search filters. + + .. code-block:: yaml + + security: + ldap: + authz: + queryTemplate: + "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" + + Using the query template, MongoDB substitutes ``{USER}`` with the + authenticated username to query the LDAP server. + + For example, a user authenticates as + ``CN=sam,CN=Users,DC=dba,DC=example,DC=com``. MongoDB creates an LDAP + query based on the :setting:`~security.ldap.authz.queryTemplate`, + substituting the ``{USER}`` token with the provided username. The Active + Directory server performs a recursive group lookup for any group that + either directly or transitively lists the user as a member. Based on the + :ref:`Active Directory groups `, the + :abbr:`AD (Active Directory)` server returns + ``CN=dba,CN=Users,DC=example,DC=com`` and + ``CN=engineering,CN=Users,DC=example,DC=com``. + + MongoDB maps each returned group :abbr:`DN (Distinguished Name)` to a role + on the ``admin`` database. For each mapped group :abbr:`DN (Distinguished + Name)`, if there is an existing role on the ``admin`` database whose name + exactly matches the :abbr:`DN (Distinguished Name)`, MongoDB grants the user + the roles and privileges assigned to that role. + + The matching rule ``LDAP_MATCHING_RULE_IN_CHAIN`` requires providing the + full :abbr:`DN (Distinguished Name)` of the authenticating user. Since + Kerberos requires authenticating with a user's ``userPrincipalName``, you + must transform the incoming usernames into :abbr:`DNs (Distinguished Name)` + using :setting:`security.ldap.userToDNMapping`. The next step provides + guidance on transforming incoming usernames to support the + :setting:`~security.ldap.authz.queryTemplate`. + +--- +title: Transform incoming usernames for authentication via Active Directory. +stepnum: 10 +ref: security-kerberos-activedirectory-authauthz-transform +level: 4 +pre: | + + In the MongoDB configuration file, set + :setting:`~security.ldap.userToDNMapping` to transform the authenticating + user's provided username into an :abbr:`AD (Active Directory)` DN to support + the :setting:`~security.ldap.authz.queryTemplate`. + + .. example:: + + The following :setting:`~security.ldap.userToDNMapping` configuration + uses the ``match`` regular expression filter to capture the provided + username. MongoDB inserts the captured username into the ``ldapQuery`` + query template before executing the query. + + .. code-block:: yaml + + security: + ldap: + userToDNMapping: + '[ + { + match : "(.+)", + ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" + } + ]' + + You must modify the given sample configuration to match your deployment. For + example, the ``ldapQuery`` base :abbr:`DN (Distinguished Name)` must match + the base :abbr:`DN (Distinguished Name)` which contains your user entities. + Other modifications may be necessary to support your :abbr:`AD (Active + Directory)` deployment. + + .. example:: + + A user authenticates as ``alice@ENGINEERING.EXAMPLE.COM``. MongoDB first + applies any transformations specified in + :setting:`~security.ldap.userToDNMapping`. Based on the provided + configuration, MongoDB captures the username in the ``match`` stage and + executes an LDAP query: + + .. code-block:: yaml + + DC=example,DC=com??sub?(userPrincipalName=alice@ENGINEERING.EXAMPLE.COM) + + Based on the configured :ref:`Active Directory + users`, the :abbr:`AD (Active Directory)` + server should return + ``CN=alice,CN=Users,DC=engineering,DC=example,DC=com``. + + MongoDB then executes the LDAP query configured in + :setting:`~security.ldap.authz.queryTemplate`, replacing the ``{USER}`` + token with the *transformed* username + ``CN=alice,CN=Users,DC=engineering,DC=example,DC=com``. + +--- +title: Configure query credentials. +stepnum: 11 +ref: security-kerberos-activedirectory-authauthz-credentials +level: 4 +pre: | + + MongoDB requires credentials for performing queries on the :abbr:`AD (Active + Directory)` server. + + Configure the following settings in the configuration file: + + - :setting:`security.ldap.bind.queryUser`, specifying the Kerberos user the + :program:`mongod` or :program:`mongos` binds as for performing queries on + the :abbr:`AD (Active Directory)` server. + + - :setting:`security.ldap.bind.queryPassword`, specifying the password for + the specified :setting:`~security.ldap.bind.queryUser`. + + .. code-block:: yaml + + security: + ldap: + bind: + queryUser: "mongodbadmin@dba.example.com" + queryPassword: "secret123" + + On :abbr:`Windows (Microsoft Windows)` MongoDB servers, you can set + :setting:`security.ldap.bind.useOSDefaults` to ``true`` to use the + credentials of the OS user instead of ``queryUser`` and ``queryPassword``. + + The :setting:`~security.ldap.bind.queryUser` must + have permission to perform all LDAP queries on behalf of MongoDB. +--- +title: Add additional configuration settings. +stepnum: 12 +optional: true +ref: security-nativeldap-activedirectory-configfile +level: 4 +pre: | + + Add any additional configuration options required for your deployment. See + the :doc:`/reference/configuration-options` manual page for documentation on + the available options. + +--- +title: Start the MongoDB server with Kerberos authentication and :abbr:`AD (Active Directory)` authorization. +ref: security-nativeldap=activedirectory-authz-startserver +level: 4 +stepnum: 13 +pre: | + + Start the MongoDB server with the :option:`--config` option, specifying the + path to the configuration file created during this procedure. If the + MongoDB server is currently running, make the appropriate preparations to + stop the server. + + ``Linux MongoDB Servers`` + + On Linux, you must specify the ``KRB5_KTNAME`` environmental variable, + specifying the path to the keytab file for the MongoDB server. + + .. code-block:: shell + + env KRB5_KTNAME mongod --config + + + ``Microsoft Windows MongoDB Servers`` + + On :abbr:`Windows (Microsoft Windows)`, you must start the MongoDB server as + the service principal account as configured earlier in the procedure: + + .. code-block:: shell + + mongod.exe --config + +--- +title: Connect to the MongoDB server. +ref: security-nativeldap-activedirectory-authz-localhost +level: 4 +stepnum: 14 +pre: | + + Connect to the MongoDB server, authenticating as a user whose direct or + transitive group membership corresponds to a MongoDB role on the ``admin`` + database with :authrole:`userAdmin`, :authrole:`userAdminAnyDatabase`, + or a custom role with equivalent privileges. + + Previously in this procedure, you configured the + ``dn:CN=dba,CN=Users,DC=example,DC=com`` role on the ``admin`` database with + the required permissions. This role corresponds to an :abbr:`AD (Active + Directory)` group. Based on the configured :ref:`AD users + `, you can authenticate as the user + ``sam/dba@example.com`` and receive the required permissions. + + Use the :program:`mongo` shell to authenticate to the MongoDB + server, set the following options: + + - :option:`--host` with the hostname of the MongoDB server + - :option:`--port` with the port of the MongoDB server + - :option:`--username` to the user's ``userPrincipalName`` + - :option:`--password` to the user's password + - :option:`--authenticationMechanism` to ``"GSSAPI"`` + - :option:`--authenticationDatabase` to ``"$external"`` + + .. code-block:: shell + + mongo --username sam@DBA.EXAMPLE.COM --password secret123 --authenticationMechanisms="GSSAPI" --authenticationDatabase "$external" --host --port + + :abbr:`Windows (Microsoft Windows)` MongoDB deployments must use + :program:`mongo.exe` instead of :program:`mongo`. + + Given the configured :ref:`Active Directory users + `, the user authenticates successfully and + receives the appropriate permissions. + + .. note:: + + If you want to authenticate as an existing non-``$external`` user, set + :option:`--authenticationMechanism` to ``SCRAM-SHA-1``. This requires + that the MongoDB server's :setting:`setParameter` + :parameter:`authenticationMechanisms` includes ``SCRAM-SHA-1``. + +--- +title: Create roles for mapping returned :abbr:`AD (Active Directory)` groups. +ref: security-nativeldap-activedirectory-authz-rolecreation +level: 4 +stepnum: 15 +pre: | + + For each group on the :abbr:`AD (Active Directory)` server you wish to use + for MongoDB authorization, you must create a matching role on the MongoDB + server's ``admin`` database. + + .. example:: + + The following operation creates a role named after the :abbr:`AD (Active + Directory)` group DN ``CN=PrimaryApplication,CN=Users,DC=example,DC=com``, + assigning roles and privileges appropriate to that group: + + .. code-block:: javascript + + db.getSiblingDB("admin").createRole( + { + role: "CN=PrimaryApplication,CN=Users,DC=example,DC=com", + privileges: [], + roles: [ + { role: "readWrite", db: "PrimaryApplication" } + ] + } + ) + + Given the configured :ref:`Active Directory groups + `, MongoDB grants a user authenticating + as either ``sam@DBA.EXAMPLE.COM`` or ``alice@ENGINEERING.EXAMPLE.COM`` the + :authrole:`readWrite` role on the ``PrimaryApplication`` database. + + .. note:: + + To manage roles on the ``admin`` database, you must be authenticated as a + user with :authrole:`userAdmin` on ``admin``, + :authrole:`userAdminAnyDatabase`, or a custom role on with equivalent + privileges. + +--- +title: Transition existing users from ``$external`` to the Active Directory server. +ref: security-nativeldap-activedirectory-authz-transitionusers +level: 4 +stepnum: 16 +optional: true +pre: | + + If upgrading an existing installation with :ref:`users ` configured + on the ``$external`` database, you must meet the following requirements + for each user to ensure access after configuring MongoDB for + Kerberos authentication and :abbr:`AD (Active Directory)` authorization: + + - User has a corresponding user object on the :abbr:`AD (Active Directory)` + server. + + - User has membership in the appropriate groups on the :abbr:`AD (Active + Directory)` server. + + - MongoDB contains the roles on the ``admin`` database named for the user's + :abbr:`AD (Active Directory)` groups, such that the authorized user + retains its privileges. + + .. example:: + + The following user exists on the ``$external`` database: + + .. code-block:: javascript + + { + user : "joe@ANALYTICS.EXAMPLE.COM", + roles: [ + { role : "read", db : "web_analytics" }, + { role : "read", db : "PrimaryApplication" } + ] + } + + Assuming the user belongs to the :abbr:`AD (Active Directory)` group + ``CN=marketing,CN=Users,DC=example,DC=com``, the following operation + creates a matching role with the appropriate privileges: + + .. code-block:: javascript + + db.getSiblingDB("admin").createRole( + { + role: "CN=marketing,CN=Users,DC=example,DC=com", + privileges: [], + roles: [ + { role: "read", db: "web_analytics" } + { role: "read", db: "PrimaryApplication" } + ] + } + ) + + Based on the configured :setting:`~security.ldap.authz.queryTemplate`, + MongoDB authorizes any user who has direct or transitive membership in the + ``CN=marketing,CN=Users,DC=example,DC=com`` group to perform + :authrole:`read` operations on the ``web_analytics`` and + ``PrimaryApplication`` databases. + + .. important:: + + When configuring a role for a corresponding :abbr:`AD (Active Directory)` + group, remember that *all* users with membership in that group can + receive the assigned roles and privileges. Consider applying the + `principle of least privilege + `_ + when configuring MongoDB roles, :abbr:`AD (Active Directory)` groups, + or group membership. + + If you want to continue allowing users on non-``$external`` databases to + access MongoDB, you must include ``SCRAM-SHA-1`` in the + :setting:`setParameter` :parameter:`authenticationMechanisms` configuration + option. + + .. code-block:: yaml + + setParameter: + authenticationMechanisms: "GSSAPI,SCRAM-SHA-1" + + Alternatively, transition non-``$external`` users to :abbr:`AD (Active + Directory)` by following the above procedure. + +... diff --git a/source/tutorial/kerberos-auth-activedirectory-authz.txt b/source/tutorial/kerberos-auth-activedirectory-authz.txt new file mode 100644 index 00000000000..451f378bfb5 --- /dev/null +++ b/source/tutorial/kerberos-auth-activedirectory-authz.txt @@ -0,0 +1,210 @@ +================================================================================= +Configure MongoDB with Kerberos Authentication and Active Directory Authorization +================================================================================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 3.4 + + `MongoDB Enterprise + `_ supports + querying an LDAP server for the LDAP groups to which an authenticated user + belongs. MongoDB maps the LDAP distinguished names (DN) of each returned + group to :ref:`roles ` on the ``admin`` database. MongoDB authorizes + the user based on the mapped roles and their associated privileges. See + :ref:`LDAP Authorization ` for more information. + +MongoDB Enterprise supports authentication using a :doc:`Kerberos service +`. Kerberos is an industry standard authentication protocol +for large client/server systems. + +This tutorial describes how to configuring MongoDB to perform authentication +through a Kerberos server and authorization through an Active Directory (AD) +server via the platform libraries. + +Prerequisites +------------- + +.. important:: + + Thoroughly familiarize yourself with the following subjects before proceeding: + + - :ref:`Kerberos Authentication ` + - :ref:`LDAP Authorization ` + - `Active Directory `_ + + +A full description of :abbr:`AD (Active Directory)` is beyond the scope of this tutorial. +This tutorial assumes prior knowledge of :abbr:`AD (Active Directory)`. + +MongoDB supports using SASL mechanisms for binding between the MongoDB server +and :abbr:`AD (Active Directory)`. A full description of SASL, SASL mechanisms, or the +specific :abbr:`AD (Active Directory)` configuration requirements for a given SASL +mechanism are beyond the scope of this tutorial. This tutorial assumes prior +knowledge of SASL and its related subject matter. + +Setting up and configuring a Kerberos deployment is beyond the scope of +this document. This tutorial assumes you have configured a +:ref:`Kerberos service principal ` for each +:program:`mongod` and :program:`mongos` instance in your MongoDB +deployment, and you have a valid :ref:`keytab file ` for +for each :program:`mongod` and :program:`mongos` instance. + +.. include:: /includes/fact-kerberos-FQDN-repica-sets.rst + +.. include:: /includes/fact-confirm-enterprise-binaries.rst + +Considerations +-------------- + +This tutorial explains configuring MongoDB for Kerberos authentication and +:abbr:`AD (Active Directory)` authorization. + +To perform this procedure on your own MongoDB server, you must modify the +given procedures with respect to your own specific infrastructure, especially +Kerberos configurations, constructing :abbr:`AD (Active Directory)` queries, or managing +users. + +Transport Layer Security +~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, MongoDB creates a TLS/SSL connection when binding to the :abbr:`AD +(Active Directory)` server. This requires configuring the host of the MongoDB +server to have access to the AD server's Certificate Authority (CA) +certificates. + +This tutorial provides instructions for the required host configurations. + +This tutorial assumes you have access to the AD server's CA certificates and +can create a copy of the certificates on the MongoDB server. + +.. _kerb-auth-ldap-authz-adschema: + +Example Active Directory Schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This tutorial uses the following example :abbr:`AD (Active Directory)` objects as the basis +for the provided queries, configurations, and output. Each object shows only +a subset of the possible attributes. + +.. _kerb-auth-ldap-authz-userObj: + +User Objects +++++++++++++ + +.. code-block:: shell + + dn:CN=bob,CN=Users,DC=marketing,DC=example,DC=com + userPrincipalName: bob@marketing.example.com + memberOf: CN=marketing,CN=Users,DC=example,DC=com + + dn:CN=alice,CN=Users,DC=engineering,DC=example,DC=com + userPrincipalName: alice@engineering.example.com + memberOf: CN=web,CN=Users,DC=example,DC=com + memberOf: CN=PrimaryApplication,CN=Users,DC=example,DC=com + + dn:CN=sam,CN=Users,DC=dba,DC=example,DC=com + userPrincipalName: sam@dba.example.com + memberOf: CN=dba,CN=Users,DC=example,DC=com + memberOf: CN=PrimaryApplication,CN=Users,DC=example,DC=com + + dn:CN=joe,CN=Users,DC=analytics,DC=example,DC=com + userPrincipalName: joe@analytics.example.com + memberof: CN=marketing,CN=Users,DC=example,DC=com + +.. _kerb-auth-ldap-authz-groupObj: + +Group Objects ++++++++++++++ + +.. code-block:: shell + + dn:CN=marketing,CN=Users,DC=example,DC=com + member:CN=bob,CN=Users,DC=marketing,DC=example,DC=com + member:CN=joe,CN=Users,DC=analytics,DC=example,DC=com + + dn:CN=engineering,CN=Users,DC=example,DC=com + member:CN=web,CN=Users,DC=example,DC=com + member:CN=dba,CN=users,DC=example,DC=com + + dn:CN=web,CN=Users,DC=example,DC=com + member:CN=alice,CN=Users,DC=engineering,DC=example,DC=com + + dn:CN=dba,CN=Users,DC=example,DC=com + member:CN=sam,CN=Users,DC=dba,DC=example,DC=com + + dn:CN=PrimaryApplication,CN=Users,DC=example,DC=com + member:CN=sam,CN=Users,DC=dba,DC=example,DC=com + member:CN=alice,CN=Users,DC=engineering,DC=example,DC=com + + +Active Directory Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This tutorial uses a username and password for performing queries on the +:abbr:`AD (Active Directory)` server. The credentials provided must have +sufficient privileges on the AD server for supporting queries related to +:setting:`security.ldap.userToDNMapping` or +:setting:`security.ldap.authz.queryTemplate`. + +Replica Sets +~~~~~~~~~~~~ + +MongoDB LDAP authorization requires *every* :program:`mongod` in the replica +set to be on at least MongoDB 3.4.0 or later. + +Sharded Clusters +~~~~~~~~~~~~~~~~ + +MongoDB LDAP authorization requires *every* :program:`mongod` and +:program:`mongos` in the sharded cluster to be on at least MongoDB 3.4.0 or +later. + +Procedure +--------- + +.. include:: /includes/steps/kerberos-auth-activedirectory-authz.rst + +This procedure produces the following configuration file: + +.. code-block:: yaml + + security: + authentication: "enabled" + ldap: + servers: activedirectory.example.net" + bind: + queryUser: "mongodbadmin@dba.example.com" + queryPassword: "secret123" + userToDNMapping: + '[ + { + match: "(.+)" + ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" + } + ]' + authz: + queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" + setParameter: + authenticationMechanism: "GSSAPI" + +.. important:: + + The given sample configuration requires modification to match your :abbr:`AD + (Active Directory)` schema, directory structure, and configuration. You may + also require additional :doc:`configuration file options + ` for your deployment. + +For more information on configuring roles and privileges, see: + +- :ref:`role-based access control ` + +- :ref:`privilege actions ` + +- :doc:`collection level access control `