From 5947d0d3b7c6a9ab0bb6c79dfe632d6bc0cc4bbe Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 21 Feb 2013 19:11:33 -0500 Subject: [PATCH] DOCS-699 authentication on sharded clusters --- source/administration/sharded-clusters.txt | 154 +++++++++++++----- ...-access-to-mongodb-with-authentication.txt | 15 +- 2 files changed, 123 insertions(+), 46 deletions(-) diff --git a/source/administration/sharded-clusters.txt b/source/administration/sharded-clusters.txt index 6e712403f4b..4e07f7936e0 100644 --- a/source/administration/sharded-clusters.txt +++ b/source/administration/sharded-clusters.txt @@ -286,59 +286,125 @@ To route a query to a :term:`cluster `, Sharded Cluster Security Considerations --------------------------------------- -.. note:: +MongoDB controls access to :term:`sharded clusters ` +through key files that store authentication information. The components +of sharded clusters use key files when authenticating to each other. You +create key files and then point your :program:`mongos` and +:program:`mongod` instances to the files, as described later in this +section. + +In addition to the MongoDB security described in this section, you +should run your sharded clusters only in trusted networking environments +that control access to the cluster using network rules. Your networking +environments should use restrictions that ensure only known traffic +reaches your :program:`mongos` and :program:`mongod` instances. + +This section describes authentication specific to sharded clusters. For +information on authentication across MongoDB, see +:ref:`security-authentication`. + +Access Control Privileges in Sharded Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In sharded clusters, MongoDB provides separate administrative privileges +for the sharded cluster and for each shard. Aside from that, the +available privileges are the same as for any MongoDB instance, as +described in :ref:`security-authentication`. + +For sharded clusters, MongoDB provides these separate administrative privileges: + +- Administrative privileges for the sharded cluster. These privileges + provide read-and-write access to the clusters's :term:`admin `, which lets the user run all administrative commands. + Administrative privileges also give the user read-and-write access to + all the cluster's databases. + + The credentials for administrative privileges on the cluster reside on + the config servers. To receive admin access to the cluster, you must + authenticate a session while connected to a :program:`mongos` instance + using the admin database. + +- Administrative privileges for an individual shard. A shard is a + :program:`mongod` instance for which sharding has been enabled. Each + shard has its own admin database that stores administrative + credentials and access for that shard only. These credentials are + *completely* distinct from the cluster-wide administrative + credentials. + + As with all :program:`mongod` instances, MongoDB provides two types of + administrative privileges for a shard: + + - Normal administrative privileges, which provide read-and-write + access to the admin database and access to all administrative + commands, and which provide read-and-write accees to all other + databases on that shard. + + - Read-only administrative privileges, which provide read-only access + to the admin database and to all other databases on that shard. + +Also, as with all :program:`mongod` instances, a MongoDB sharded cluster +provides the following non-administrative user privileges: + +- Normal privileges, which provide read-and-write access to a specific + database. Users with normal privilege can add users to the database. + +- Read-only privileges, which provide read-only access to a specific + database. - You should always run all :program:`mongod` components in trusted - networking environments that control access to the cluster using - network rules and restrictions to ensure that only known traffic - reaches your :program:`mongod` and :program:`mongos` instances. +For more information on privileges, see :ref:`security-authentication`. -.. warning:: Limitations +Enable Authentication in a Sharded Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. versionchanged:: 2.2 - Read only authentication is fully supported in shard - clusters. Previously, in version 2.0, sharded clusters would not - enforce read-only limitations. +.. versionadded:: 2.0 + Support for authentication with sharded clusters. - .. versionchanged:: 2.0 - Sharded clusters support authentication. Previously, in version - 1.8, sharded clusters will not support authentication and access - control. You must run your sharded systems in trusted - environments. +To control access to a sharded cluster, you create key files and then +set the :setting:`keyFile` option on *all* components of the sharded +cluster (all :program:`mongos` instances, all config server +:program:`mongod` instances, and all shard :program:`mongod` instances). The content of +the key file is arbitrary but must be the same on all cluster members. -To control access to a sharded cluster, you must set the -:setting:`keyFile` option on all components of the sharded cluster. Use -the :option:`--keyFile ` run-time option or the -:setting:`keyFile` configuration option for all :program:`mongos`, -configuration instances, and shard :program:`mongod` instances. +To enable authentication, do the following: -There are two classes of security credentials in a sharded cluster: -credentials for "admin" users (i.e. for the :term:`admin database`) and -credentials for all other databases. These credentials reside in -different locations within the cluster and have different roles: +1. Generate a key file to store authentication information, as described + in :ref:`generate-key-file`. -- Admin database credentials reside on the config servers, to receive - admin access to the cluster you *must* authenticate a session while - connected to a :program:`mongos` instance using the :term:`admin - database`. +#. On each component in the sharded cluster, enable authentication by + doing one of the following: -- Each shard has its own :term:`admin database`, which stores - administrative credentials and access for that shard only. + - In the configuration file, set the :setting:`keyFile` option to the + key file's path and then start the component. -- Other database credentials reside on the *primary* shard for the - database. + The following is an example :setting:`keyFile` option and path: -This means that you *can* authenticate to these users and databases -while connected directly to the *primary* shard for a database. You -**cannot** authenticate to a database in a sharded cluster that is not -the primary for that database. However, for clarity and consistency -all interactions between the client and the database should use a -:program:`mongos` instance. + .. code-block:: cfg -.. note:: + keyFile = /srv/mongodb/keyfile + + - When starting the component, set :option:`--keyFile ` option, + which is an option for both :program:`mongos` instances and + :program:`mongod` instances. Set the :option:`--keyFile ` + to the key file's path. + + .. note:: The :setting:`keyFile` setting implies :setting:`auth`, which + means in most cases you do not need to set :setting:`auth`. + +#. Add the first administrative user and then add subsequent users. See + :ref:`control-access-add-users`. + +Access a Sharded Cluster for which Authentication is Enabled +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To access a sharded cluster as an authenticated admin user, see +:ref:`control-access-admin-access`. + +To access a sharded cluster as an authenticated, non-admin user, see +either of the following: + +- :dbcommand:`authenticate` + +- :method:`db.auth()` - Individual shards can store administrative credentials to their - instance, which only permit access to a single shard. MongoDB - stores these credentials in the shards' :term:`admin databases - ` and these credentials are *completely* distinct - from the cluster-wide administrative credentials. +To terminate an authenticated session, see the :dbcommand:`logout` +command. diff --git a/source/tutorial/control-access-to-mongodb-with-authentication.txt b/source/tutorial/control-access-to-mongodb-with-authentication.txt index 68279f356f2..279cbf07e83 100644 --- a/source/tutorial/control-access-to-mongodb-with-authentication.txt +++ b/source/tutorial/control-access-to-mongodb-with-authentication.txt @@ -20,8 +20,10 @@ authentication and managing a MongoDB deployment with authentication. :option:`--keyFile ` options on the command line. -Adding Users ------------- +.. _control-access-add-users: + +Add Users +--------- When setting up authentication for the first time you must either: @@ -100,6 +102,8 @@ the following sequence of operations: Replace ```` and ```` with the credentials for this user. +.. _control-access-admin-access: + Administrative Access in MongoDB -------------------------------- @@ -223,9 +227,16 @@ authentication with specific MongoDB deployments: - :ref:`replica-set-security` - :ref:`sharding-security` +.. _generate-key-file: + Generate a Key File ------------------- +The key file must be less one kilobyte in size and may only contain +characters in the base64 set. The key file must not have group or "world" +permissions on UNIX systems. Key file permissions are not checked on +Windows systems. + Use the following command at the system shell to generate pseudo-random content for a key file: