From ddd0f7c22b8ebd5f4805da553d590ab35a358a9e Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Tue, 24 Aug 2021 14:54:19 +0200 Subject: [PATCH] DOCSP-18009: Refactor Security Users section --- source/core/authentication.txt | 4 +- source/core/localhost-exception.txt | 67 ++++++ source/core/security-users.txt | 181 +++++++--------- source/includes/access-create-user.rst | 7 +- .../includes/extracts-create-users-base.yaml | 10 +- source/includes/extracts-create-users.yaml | 4 +- source/includes/extracts-sessions.yaml | 7 +- source/includes/fact-authenticate.rst | 20 -- source/includes/intro-rbac.rst | 10 - ...eate-admin-then-enable-authentication.yaml | 200 +++++++++--------- .../steps-deploy-replica-set-with-auth.yaml | 5 + source/tutorial/authenticate-a-user.txt | 77 +++++++ source/tutorial/create-users.txt | 13 +- 13 files changed, 352 insertions(+), 253 deletions(-) create mode 100644 source/core/localhost-exception.txt delete mode 100644 source/includes/fact-authenticate.rst delete mode 100644 source/includes/intro-rbac.rst create mode 100644 source/tutorial/authenticate-a-user.txt diff --git a/source/core/authentication.txt b/source/core/authentication.txt index ce36e9da38c..10f882b8f12 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -30,7 +30,8 @@ Getting Started To get started using access control, follow these tutorials: - :ref:`enable-access-control` -- :ref:`add-new-user` +- :ref:`create-users` +- :ref:`authentication-auth-as-user` .. _available-authentication-mechanisms: @@ -71,3 +72,4 @@ for more information. /core/authentication-mechanisms /core/authentication-mechanisms-enterprise /core/security-internal-authentication + /core/localhost-exception diff --git a/source/core/localhost-exception.txt b/source/core/localhost-exception.txt new file mode 100644 index 00000000000..a34955dee50 --- /dev/null +++ b/source/core/localhost-exception.txt @@ -0,0 +1,67 @@ +.. _localhost-exception: + +=================== +Localhost Exception +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. important:: + + On a :binary:`~bin.mongod` instance, the localhost exception only + applies when there are **no users or roles** created in the MongoDB + instance. + +The localhost exception allows you to enable access control and then +create the first user or role in the system. After you enable access +control, connect to the localhost interface and create the first user in +the ``admin`` database. + +If you create a user first, the user must have privileges to create +other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. + +.. warning:: + + Connections using the localhost exception have access to create + *only* the **first user or role**. + + Once you create any user or role, the localhost exception is + disabled. If you need to create a user and a role, you must create + the user first using one of the builtin :authrole:`userAdmin` or + :authrole:`userAdminAnyDatabase` roles. If you create a role first, + you won't be able to create a user. + +The ability to create a role first with the :method:`db.createRole()` +method is specifically for users authorizing with LDAP. See :ref:`LDAP +Authorization ` for more information. + +Localhost Exception for Sharded Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + - On a :binary:`~bin.mongos`, the localhost exception only applies + when there are no :ref:`sharded cluster users ` + or roles created. + - In a sharded cluster, the localhost exception applies to each shard + individually as well as to the cluster as a whole. + +Once you create a sharded cluster and add a :ref:`user administrator +` through the :binary:`~bin.mongos` instance, you +**must** still prevent unauthorized access to the individual shards. To +prevent unauthorized access to individual shards, follow one of the +following steps for each shard in your cluster: + +- :ref:`Create a user administrator ` on the shard's + primary. +- Disable the localhost exception at startup. To disable the localhost + exception, set the :parameter:`enableLocalhostAuthBypass` parameter to + ``0``. diff --git a/source/core/security-users.txt b/source/core/security-users.txt index b1ca89cf9cb..cea3991ac0c 100644 --- a/source/core/security-users.txt +++ b/source/core/security-users.txt @@ -10,90 +10,88 @@ Users .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -To authenticate a client in MongoDB, you must add a corresponding user to -MongoDB. +To authenticate a client in MongoDB, you must add a corresponding user +to MongoDB. +User Management +--------------- -User Management Interface -------------------------- +You can add a user with the :method:`db.createUser()` method using +:binary:`~bin.mongosh`. The first user you create must have privileges +to create other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. -To add a user, MongoDB provides the :method:`db.createUser()` method. -When adding a user, you can assign :doc:`roles ` to -the user in order to grant privileges. - -.. note:: +.. seealso:: - The first user created in the database should be a user administrator - who has the privileges to manage other users. See - :doc:`/tutorial/enable-authentication`. + :doc:`/tutorial/create-users` -You can also update existing users, such as to change password and grant -or revoke roles. For a full list of user management methods, see +You can grant a user privileges by assinging :doc:`roles +` to the user when you create the user. You can +also grant or revoke roles, as well as update passwords, by updating +existing users. For a full list of user management methods, see :ref:`user-management-methods`. +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` + A user is uniquely identified by the user's name and associated -authentication database. Starting in MongoDB 4.0.9, a users managed by -MongoDB are assigned a unique ``userId``. [#userid]_ +:ref:`authentication database `. MongoDB +associates a user with a unique ``userId`` upon creation in MongoDB. + +LDAP Managed Users +~~~~~~~~~~~~~~~~~~ + +:ref:`LDAP managed users ` created on an LDAP +server do not have an associated document in the :doc:`system.users +` collection, and therefore don't +have a :data:`~admin.system.users.userId` field associated with them. -.. seealso:: - :doc:`/tutorial/create-users` - .. _authentication-database: .. _user-authentication-database: Authentication Database ----------------------- -When adding a user, you create the user in a specific database. This -database is the authentication database for the user. - -A user can have privileges across different databases; that is, a user's -privileges are not limited to their authentication database. By assigning -to the user roles in other databases, a user created in one database can -have permissions to act on other databases. For more information on -roles, see :doc:`/core/authorization`. - -The user's name and authentication database serve as a unique identifier -for that user. [#userid]_ That is, if two users have the same name but are created -in different databases, they are two separate users. If you intend to -have a single user with permissions on multiple databases, create a -single user with roles in the applicable databases instead of creating -the user multiple times in different databases. +When you add a user, you create the user in a specific database. The +database you create the user in is the authentication database for the +user. -.. [#userid] +However, a user's privileges are not limited to their authentication +database. Therefore, a user can have privileges across different +databases. For more information on roles, see +:doc:`/core/authorization`. - Starting in version 4.0.9, MongoDB associates a user with a unique - ``userId`` upon creation in MongoDB. - - :ref:`LDAP managed users ` created on the LDAP server - do not have an associated document in the :doc:`system.users - ` collection, and hence, do not - have a :data:`~admin.system.users.userId` field associated with them. +A user's name and authentication database serve as a unique identifier +for that user. MongoDB associates a user with a unique ``userId`` upon +creation in MongoDB. However, :ref:`LDAP managed users ` +created on an LDAP server do not have an associated document in the +:doc:`system.users ` collection, and +therefore don't have a :data:`~admin.system.users.userId` field +associated with them. -.. _authentication-auth-as-user: - -Authenticate a User -------------------- - -.. include:: /includes/fact-authenticate.rst +If two users have the same name but are created in different databases, +they are two separate users. If you want to have a single user with +permissions on multiple databases, create a single user with a role for +each applicable database. Centralized User Data --------------------- For users created in MongoDB, MongoDB stores all user information, including :data:`name `, :data:`password -`, and the :data:`user's authentication +`, and the user's :data:`authentication database `, in the :doc:`system.users ` collection in the ``admin`` database. -Do not access this collection directly but instead use the :ref:`user -management commands `. - +Do not modify this collection directly. To manage users, use the +designated :ref:`user management commands `. .. _sharding-localhost: .. _sharding-security: @@ -101,9 +99,11 @@ management commands `. Sharded Cluster Users --------------------- -To create users for a sharded cluster, connect to the -:binary:`~bin.mongos` instance and add the users. Clients then -authenticate these users through the :binary:`~bin.mongos` instances. +To create users for a sharded cluster, connect to a +:binary:`~bin.mongos` instance and add the users. To authenticate as a +user created on a :binary:`~bin.mongos` instance, you must authenticate +through a :binary:`~bin.mongos` instance. + In sharded clusters, MongoDB stores user configuration data in the ``admin`` database of the :term:`config servers `. @@ -112,62 +112,33 @@ In sharded clusters, MongoDB stores user configuration data in the Shard Local Users ~~~~~~~~~~~~~~~~~ -However, some maintenance operations, such as :dbcommand:`cleanupOrphaned`, -:dbcommand:`compact`, :method:`rs.reconfig()`, require direct connections to -specific shards in a sharded cluster. To perform these operations, you must -connect directly to the shard and authenticate as a *shard local* -administrative user. - -To create a *shard local* administrative user, connect directly to the shard -and create the user. MongoDB stores *shard local* users in the ``admin`` -database of the shard itself. - -These *shard local* users are completely independent from the users added to -the sharded cluster via :binary:`~bin.mongos`. *Shard local* users are local to the -shard and are inaccessible by :binary:`~bin.mongos`. - -Direct connections to a shard should only be for shard-specific maintenance and -configuration. In general, clients should connect to the sharded cluster -through the :binary:`~bin.mongos`. - -.. _localhost-exception: - -Localhost Exception -------------------- - -The localhost exception allows you to enable access control and then -create the first user in the system. With the localhost exception, after -you enable access control, connect to the localhost interface and create -the first user in the ``admin`` database. The first user must have -privileges to create other users, such as a user with the -:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role. -Connections using the localhost exception *only* have access to create -the first user on the ``admin`` database. - -.. versionchanged:: 3.4 - - MongoDB 3.4 extended the localhost exception to permit execution of the - :method:`db.createRole()` method. This method allows users authorizing via - LDAP to create a role inside of MongoDB that maps to a role defined - in LDAP. See :ref:`LDAP Authorization ` for more - information. +Some maintenance operations, such as :dbcommand:`cleanupOrphaned`, +:dbcommand:`compact`, or :method:`rs.reconfig()`, require direct +connections to specific shards in a sharded cluster. To perform these +operations, you must connect directly to the shard and authenticate as a +*shard local* administrative user. -The localhost exception applies only when there are no users created in the -MongoDB instance. +To create a *shard local* administrative user, connect directly to the +primary of the shard and create the user. For instructions on how to +create a shard local user administrator see the +:doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` +tutorial. -In the case of a sharded cluster, the localhost exception applies to each shard -individually as well as to the cluster as a whole. Once you create a sharded -cluster and add a user administrator through the :binary:`~bin.mongos` instance, -you must still prevent unauthorized access to the individual shards. Follow one -of the following steps for each shard in your cluster: +MongoDB stores *shard local* users in the ``admin`` database of the +shard itself. These *shard local* users are independent from +the users added to the sharded cluster through a :binary:`~bin.mongos`. +*Shard local* users are local to the shard and are inaccessible by +:binary:`~bin.mongos`. -- Create an administrative user, or +Direct connections to a shard should only be used for shard-specific +maintenance and configuration or for targeted analytics workloads. In +general, clients should connect to the sharded cluster through the +:binary:`~bin.mongos`. -- Disable the localhost exception at startup. To disable the localhost - exception, set the :parameter:`enableLocalhostAuthBypass` parameter to ``0``. .. toctree:: :titlesonly: :hidden: /tutorial/create-users + /tutorial/authenticate-a-user diff --git a/source/includes/access-create-user.rst b/source/includes/access-create-user.rst index b99dc1352bb..7e22b00aa66 100644 --- a/source/includes/access-create-user.rst +++ b/source/includes/access-create-user.rst @@ -6,7 +6,6 @@ :ref:`action ` on the role's database. The :authrole:`userAdmin` and -:authrole:`userAdminAnyDatabase` built-in roles -provide :authaction:`createUser` and -:authaction:`grantRole` actions on their respective :doc:`resources -`. +:authrole:`userAdminAnyDatabase` built-in roles provide +:authaction:`createUser` and :authaction:`grantRole` actions on their +respective :doc:`resources `. diff --git a/source/includes/extracts-create-users-base.yaml b/source/includes/extracts-create-users-base.yaml index 55df6eea5f0..d7df57c8f5b 100644 --- a/source/includes/extracts-create-users-base.yaml +++ b/source/includes/extracts-create-users-base.yaml @@ -1,10 +1,10 @@ ref: _create-user-intro content: | - Users that will authenticate to MongoDB using an external authentication - mechanism, such as {{mechanism}}, must be created in the ``$external`` database, - which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` to consult an - external source for authentication. - + Users that authenticate to MongoDB using an external authentication + mechanism, such as {{mechanism}}, must be created in the ``$external`` + database, which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` + to consult an external source for authentication. + .. include:: /includes/extracts/sessions-external-username-limit.rst ... \ No newline at end of file diff --git a/source/includes/extracts-create-users.yaml b/source/includes/extracts-create-users.yaml index a519296f8a2..08e9c11156f 100644 --- a/source/includes/extracts-create-users.yaml +++ b/source/includes/extracts-create-users.yaml @@ -2,7 +2,7 @@ ref: create-user-intro-kerberos inherit: ref: _create-user-intro file: extracts-create-users-base.yaml -replacement: +replacement: mechanism: "Kerberos" --- ref: create-user-intro-ldap @@ -18,4 +18,4 @@ inherit: file: extracts-create-users-base.yaml replacement: mechanism: "x.509 Client Certificate Authentication" -... +... diff --git a/source/includes/extracts-sessions.yaml b/source/includes/extracts-sessions.yaml index c5b7ec20130..e98bd15a55e 100644 --- a/source/includes/extracts-sessions.yaml +++ b/source/includes/extracts-sessions.yaml @@ -101,11 +101,10 @@ content: | ref: sessions-external-username-limit content: | - .. versionchanged:: 3.6.3 + To use :ref:`sessions` with ``$external`` authentication users + (Kerberos, LDAP, or x.509 users), the usernames cannot be greater + than 10k bytes. - To use sessions with ``$external`` authentication users (i.e. - Kerberos, LDAP, x.509 users), the usernames cannot be greater - than 10k bytes. --- ref: sessions-cursor-timeout content: | diff --git a/source/includes/fact-authenticate.rst b/source/includes/fact-authenticate.rst deleted file mode 100644 index 1cb3cf469f5..00000000000 --- a/source/includes/fact-authenticate.rst +++ /dev/null @@ -1,20 +0,0 @@ -To authenticate as a user, you must provide a username, password, and -the :ref:`authentication database ` -associated with that user. - -To authenticate using :binary:`~bin.mongosh`, either: - -- Use the :binary:`~bin.mongosh` command-line authentication options - (:option:`--username `, - :option:`--password `, and - :option:`--authenticationDatabase `) - when connecting to the :binary:`~bin.mongod` or - :binary:`~bin.mongos` instance, or - -- Connect first to the :binary:`~bin.mongod` or :binary:`~bin.mongos` - instance, and then run the :dbcommand:`authenticate` command or the - :method:`db.auth()` method against the :ref:`authentication database - `. - -For examples of authenticating using a MongoDB driver, see the -`driver documentation `__. diff --git a/source/includes/intro-rbac.rst b/source/includes/intro-rbac.rst deleted file mode 100644 index 59d30a68acd..00000000000 --- a/source/includes/intro-rbac.rst +++ /dev/null @@ -1,10 +0,0 @@ -MongoDB employs role-based access control (RBAC) to determine access -for users. A user is granted one or more :ref:`roles ` that -determine the user's access or privileges to MongoDB :ref:`resources -` and the :ref:`actions ` -that user can perform. A user should have only the minimal set of -privileges required to ensure a system of :term:`least privilege`. - -Each application and user of a MongoDB system should map to a distinct -user. This *access isolation* facilitates -access revocation and ongoing user maintenance. diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index a74e380c674..a3ca858308b 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -4,21 +4,21 @@ level: 4 ref: start-without-auth pre: | - Start a standalone :binary:`~bin.mongod` instance without access - control. + Start a standalone :binary:`~bin.mongod` instance without access + control. - Open a terminal and run the following command: + Open a terminal and run the following command: action: language: sh code: | mongod --port 27017 --dbpath /var/lib/mongodb post: | - The :binary:`~bin.mongod` instance in this tutorial uses - :option:`port 27017 ` and the ``/var/lib/mongodb`` - data directory. The tutorial assumes that the ``/var/lib/mongodb`` - directory exists and is the default :setting:`~storage.dbPath`. You - may specify a different data directory or port as needed. + The :binary:`~bin.mongod` instance in this tutorial uses + :option:`port 27017 ` and the ``/var/lib/mongodb`` + data directory. The tutorial assumes that the ``/var/lib/mongodb`` + directory exists and is the default :setting:`~storage.dbPath`. You + may specify a different data directory or port as needed. --- stepnum: 2 @@ -27,16 +27,17 @@ level: 4 ref: connect pre: | - Open a new terminal and connect to the database deployment with - :binary:`~bin.mongosh`: + Open a new terminal and connect to the database deployment with + :binary:`~bin.mongosh`: action: language: sh code: | mongosh --port 27017 post: | - If you are connecting to an existing deployment, specify additional - command line options, such as ``--host``, as needed to connect. + If you are connecting to a different deployment, specify additional + command line options, such as :option:`--host `, as + needed to connect. --- stepnum: 3 title: Create the user administrator @@ -44,31 +45,23 @@ level: 4 ref: create-user-admin pre: | - .. _create-user-admin: + .. _create-user-admin: - .. important:: Localhost Exception + .. important:: Localhost Exception - You can create the user administrator either before or after - enabling access control. If you enable access control before - creating any user, MongoDB provides a :ref:`localhost exception - ` which allows you to create a user - administrator in the ``admin`` database. Once created, you must - authenticate as the user administrator to create additional users. + You can create the user administrator either before or after + enabling access control. If you enable access control before + creating any user, MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. - The :authrole:`userAdminAnyDatabase` role allows this user to: + Using :binary:`~bin.mongosh`: - - create users, - - grant or revoke roles from users, - - and create or modify customs roles. - - You can assign your user additional :ref:`built-in roles - ` or :ref:`user-defined roles ` - as needed. - - Using :binary:`~bin.mongosh`, switch to the ``admin`` database and - add the user ``myUserAdmin`` in the ``admin`` database with the - :authrole:`userAdminAnyDatabase` role and the - :authrole:`readWriteAnyDatabase` role: + 1. switch to the ``admin`` database + 2. add the ``myUserAdmin`` user with the + :authrole:`userAdminAnyDatabase` and + :authrole:`readWriteAnyDatabase` roles": action: language: javascript @@ -87,16 +80,26 @@ action: ) post: | - .. tip:: + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The :authrole:`userAdminAnyDatabase` role allows this user to: + + - create users + - grant or revoke roles from users + - create or modify customs roles - .. include:: /includes/extracts/mongosh-password-prompt.rst + You can assign your user additional :ref:`built-in roles + ` or :ref:`user-defined roles ` + as needed. - The database where you create the user (in this example, ``admin``) - is the user's :ref:`authentication database - `. Although the user needs to - authenticate to this database, the user can have roles in other - databases. The user's authentication database doesn't limit the - user's privileges. + The database where you create the user, in this example ``admin``, + is the user's :ref:`authentication database + `. Although the user needs to + authenticate to this database, the user can have roles in other + databases. The user's authentication database doesn't limit the + user's privileges. --- title: Re-start the MongoDB instance with access control @@ -105,45 +108,45 @@ stepnum: 4 ref: restart-with-auth content: | - Shut down the :binary:`~bin.mongod` instance. Using - :binary:`~bin.mongosh`, issue the following command: + Shut down the :binary:`~bin.mongod` instance. Using + :binary:`~bin.mongosh`, issue the following command: - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { shutdown: 1 } ) + db.adminCommand( { shutdown: 1 } ) - Exit :binary:`~bin.mongosh`. + Exit :binary:`~bin.mongosh`. - Start the :binary:`~bin.mongod` with access control enabled. + Start the :binary:`~bin.mongod` with access control enabled. - - If you start the :binary:`~bin.mongod` from the command line, add - the :option:`--auth ` command line option: + - If you start the :binary:`~bin.mongod` from the command line, add + the :option:`--auth ` command line option: - .. code-block:: bash + .. code-block:: bash - mongod --auth --port 27017 --dbpath /var/lib/mongodb + mongod --auth --port 27017 --dbpath /var/lib/mongodb - - If you start the :binary:`~bin.mongod` using a - :ref:`configuration file `, add the - :setting:`security.authorization` configuration file setting: + - If you start the :binary:`~bin.mongod` using a + :ref:`configuration file `, add the + :setting:`security.authorization` configuration file setting: - .. code-block:: bash + .. code-block:: bash - security: - authorization: enabled + security: + authorization: enabled - Clients that connect to this instance must now authenticate - themselves and can only perform actions as determined by their - assigned roles. + Clients that connect to this instance must now authenticate + themselves and can only perform actions as determined by their + assigned roles. - .. important:: Localhost Exception + .. important:: Localhost Exception - You can create users either before or after enabling access - control. If you enable access control before creating any user, - MongoDB provides a :ref:`localhost exception - ` which allows you to create a user - administrator in the ``admin`` database. Once created, you must - authenticate as the user administrator to create additional users. + You can create users either before or after enabling access + control. If you enable access control before creating any user, + MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. --- title: Connect and authenticate as the user administrator @@ -151,50 +154,49 @@ level: 4 stepnum: 5 ref: auth-as-admin content: | - Using :binary:`~bin.mongosh`, you can: + Using :binary:`~bin.mongosh`, you can: - .. tabs:: + .. tabs:: - tabs: - - id: cmdline - name: Authenticate during Connection - content: | - Start :binary:`~bin.mongosh` with the :option:`-u - \ `, :option:`-p `, and the - :option:`--authenticationDatabase \ ` command line options: + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 --authenticationDatabase \ - "admin" -u "myUserAdmin" -p + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p - Enter your password when prompted. + Enter your password when prompted. - - id: authafter - name: Authenticate after Connection - content: | + - id: authafter + name: Authenticate after Connection + content: | - Using :binary:`~bin.mongosh`, connect to your database - deployment: + Using :binary:`~bin.mongosh`, connect to your database + deployment: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 + mongosh --port 27017 - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``admin``), and - use the :method:`db.auth(\, \) - ` method to authenticate: + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - .. tip:: + .. tip:: - .. include:: /includes/extracts/mongosh-password-prompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst - Enter the password when prompted. -... + Enter the password when prompted. diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 5cae223df0d..9283414a010 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -3,7 +3,9 @@ title: Create a keyfile. ref: deploy-repset-generate-keyfile level: 4 pre: | + .. include:: /includes/extracts/keyfile-intro-replica-set.rst + action: language: sh code: | @@ -140,7 +142,9 @@ title: Create the user administrator. level: 4 ref: deploy-repset-user-admin pre: | + .. important:: + After you create the first user, the :ref:`localhost exception ` is no longer available. @@ -164,6 +168,7 @@ pre: | :authrole:`userAdminAnyDatabase` role on the ``admin`` database. .. important:: + Passwords should be random, long, and complex to ensure system security and to prevent or delay malicious access. diff --git a/source/tutorial/authenticate-a-user.txt b/source/tutorial/authenticate-a-user.txt new file mode 100644 index 00000000000..e613ac4e47d --- /dev/null +++ b/source/tutorial/authenticate-a-user.txt @@ -0,0 +1,77 @@ +.. _authentication-auth-as-user: + +=================== +Authenticate a User +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +To authenticate as a user, you must provide a username, password, and +the :ref:`authentication database ` +associated with that user. + +.. important:: + + It is not possible to switch between users in the same + :binary:`~bin.mongosh` session. Authenticating as a different user + means the session has the privileges of **both** authenticated + users. To switch between users exit and relaunch + :binary:`~bin.mongosh`. + +Using :binary:`~bin.mongosh`, you can: + +.. tabs:: + + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p + + Enter your password when prompted. + + - id: authafter + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to the + :binary:`~bin.mongod` or :binary:`~bin.mongos` instance: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method or the :dbcommand:`authenticate` + command to authenticate against the :ref:`authentication + database `: + + .. code-block:: javascript + + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password when prompted. + +For examples using a MongoDB driver, see the +`driver documentation `__. diff --git a/source/tutorial/create-users.txt b/source/tutorial/create-users.txt index 8c819a7c855..044f97611dc 100644 --- a/source/tutorial/create-users.txt +++ b/source/tutorial/create-users.txt @@ -12,9 +12,16 @@ Create a User :depth: 3 :class: singlecol -With access control enabled, users are required to identify themselves -and can only perform actions that adhere to the permissions granted by -the :ref:`roles ` assigned to their user. +With access control enabled, users are required to identify themselves. +You have to grant a user one or more :ref:`roles `. A role grants +a user :ref:`privileges ` to perform certain :ref:`actions +` on MongoDB :ref:`resources +`. + +Each application and user of a MongoDB system should map to a distinct +user. This principle of *access isolation* facilitates access revocation +and ongoing user maintenance. To ensure a system of :term:`least +privilege`, only grant the minimal set of privileges required to a user. .. _add-user-prereq: