diff --git a/source/includes/extracts-5.0-changes.yaml b/source/includes/extracts-5.0-changes.yaml index 7eb11a0ff65..7852eaedbdf 100644 --- a/source/includes/extracts-5.0-changes.yaml +++ b/source/includes/extracts-5.0-changes.yaml @@ -29,4 +29,15 @@ content: | Dropping the :term:`admin database` or the :term:`config database` can leave your cluster in an unusable state. +--- + +ref: mongosh-password-prompt +content: | + + The :method:`passwordPrompt()` method prompts you to enter the + password. You can also specify your password directly as a string. We + recommend to use the :method:`passwordPrompt()` method to avoid the + password being visible on your screen and potentially leaking the + password to your shell history. + ... diff --git a/source/includes/steps-authorization-create-users.yaml b/source/includes/steps-authorization-create-users.yaml new file mode 100644 index 00000000000..43be6ede609 --- /dev/null +++ b/source/includes/steps-authorization-create-users.yaml @@ -0,0 +1,184 @@ +title: Connect and authenticate +level: 4 +stepnum: 1 +ref: auth-as-admin +content: | + Using :binary:`~bin.mongosh`, connect to your primary + :binary:`~bin.mongod` or, in a sharded cluster, connect to your + :binary:`~bin.mongos` and authenticate as a user administrator or a + user with the :ref:`required privileges `: + + .. 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 your database + deployment: + + .. 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 to authenticate: + + .. 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. +--- +title: Create additional users for your deployment +level: 4 +stepnum: 2 +ref: create-additionalusers +pre: | + + .. note:: + + The following step uses :ref:`authentication-scram` authentication. + For additional information on other authentication mechanisms, see + :ref:`create-users-examples`. + + After authenticating as the user administrator, use the + :method:`db.createUser()` method to create additional users. You can assign + any :doc:`built-in roles ` or + :doc:`user-defined roles ` to the + users. + +action: + pre: | + The following operation adds a user ``myTester`` to the ``test`` + database who has the :authrole:`readWrite` role in the ``test`` + database as well as the :authrole:`read` role in the ``reporting`` + database. + + language: javascript + code: | + use test + db.createUser( + { + user: "myTester", + pwd: passwordPrompt(), // or cleartext password + roles: [ { role: "readWrite", db: "test" }, + { role: "read", db: "reporting" } ] + } + ) + +post: | + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The database where you create the user (in this example, ``test``) is + that user's :ref:`authentication database + `. Although the user authenticates to + this database, the user can have roles in other databases. The + user's authentication database does not limit the user's privileges. + + After creating the additional users, exit :binary:`~bin.mongosh`. + +--- +title: Connect to the instance and authenticate as ``myTester`` +level: 4 +ref: auth-as-mytester +content: | + + .. 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`. + + After exiting :binary:`~bin.mongosh` as ``myUserAdmin``, reconnect as + ``myTester``: + + .. tabs:: + + tabs: + - id: cmdline2 + 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 -u "myTester" \ + --authenticationDatabase "test" -p + + Enter the password for the user when prompted. + + - id: authafter2 + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to your database + deployment: + + .. 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 to authenticate: + + .. code-block:: javascript + + use test + db.auth("myTester", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password for the user when prompted. +--- +title: Insert a document as ``myTester`` +level: 4 +ref: insert-as-mytester +content: | + + As the user ``myTester``, you have privileges to perform read and + write operations in the ``test`` database (as well as perform read + operations in the ``reporting`` database). Once authenticated as + ``myTester``, insert a document into a collection in the ``test`` + database. For example, you can perform the following insert + operation in the ``test`` database: + + .. code-block:: javascript + + db.foo.insert( { x: 1, y: 1 } ) +... diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index 9f70d46eed9..a74e380c674 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -1,4 +1,4 @@ -title: Start MongoDB without access control. +title: Start MongoDB without access control stepnum: 1 level: 4 ref: start-without-auth @@ -6,119 +6,153 @@ pre: | Start a standalone :binary:`~bin.mongod` instance without access control. - - For example, open a terminal and issue the following: + + 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. + --- stepnum: 2 -title: Connect to the instance. +title: Connect to the instance level: 4 ref: connect pre: | - For example, open a new terminal and connect :binary:`~bin.mongosh` - to the instance: + Open a new terminal and connect to the database deployment with + :binary:`~bin.mongosh`: action: language: sh code: | - mongosh --port 27017 + mongosh --port 27017 post: | - Specify additional command line options as appropriate to connect - :binary:`~bin.mongosh` to your deployment, such as ``--host``. + If you are connecting to an existing deployment, specify additional + command line options, such as ``--host``, as needed to connect. --- stepnum: 3 -title: Create the user administrator. +title: Create the user administrator level: 4 ref: create-user-admin pre: | - From :binary:`~bin.mongosh`, add a user with the - :authrole:`userAdminAnyDatabase` role in the ``admin`` database. Include additional roles as - needed for this user. For example, the following - creates the user ``myUserAdmin`` in the ``admin`` database with the - :authrole:`userAdminAnyDatabase` role and the - :authrole:`readWriteAnyDatabase` role. + .. _create-user-admin: -action: - pre: | + .. 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. + + The :authrole:`userAdminAnyDatabase` role allows this user to: - .. tip:: + - create users, + - grant or revoke roles from users, + - and create or modify customs roles. - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + 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: + +action: language: javascript code: | + use admin db.createUser( { user: "myUserAdmin", pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "userAdminAnyDatabase", db: "admin" }, "readWriteAnyDatabase" ] + roles: [ + { role: "userAdminAnyDatabase", db: "admin" }, + { role: "readWriteAnyDatabase", db: "admin" } + ] } ) post: | - .. note:: - The database where you create the user (in this example, - ``admin``) is the user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can - have roles in other databases; i.e. the user's authentication - database does not limit the user's privileges. + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + 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. +title: Re-start the MongoDB instance with access control level: 4 stepnum: 4 ref: restart-with-auth content: | - - a. Shut down the :binary:`~bin.mongod` instance. For example, from - :binary:`~bin.mongosh`, issue the following command: - .. code-block:: javascript + Shut down the :binary:`~bin.mongod` instance. Using + :binary:`~bin.mongosh`, issue the following command: + + .. 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. + + .. 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. - Clients that connect to this instance must now authenticate - themselves as a MongoDB user. Clients can only perform actions as - determined by their assigned roles. --- -title: Connect and authenticate as the user administrator. +title: Connect and authenticate as the user administrator level: 4 stepnum: 5 ref: auth-as-admin content: | Using :binary:`~bin.mongosh`, you can: - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - .. tabs:: tabs: @@ -132,155 +166,35 @@ content: | .. code-block:: bash - mongosh --port 27017 --authenticationDatabase "admin" -u "myUserAdmin" -p + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p Enter your password when prompted. - id: authafter name: Authenticate after Connection content: | - - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: + + Using :binary:`~bin.mongosh`, connect to your database + deployment: .. code-block:: bash mongosh --port 27017 - In :binary:`~bin.mongosh`, switch to the authentication database (in this case, ``admin``), and - use :method:`db.auth(\, \) ` - method to authenticate: - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + use the :method:`db.auth(\, \) + ` method to authenticate: .. code-block:: javascript use admin db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - Enter the password when prompted. ---- -title: Create additional users as needed for your deployment. -level: 4 -stepnum: 6 -ref: create-additionalusers -pre: | - Once authenticated as the user administrator, use - :method:`db.createUser()` to create additional users. You can assign - any :doc:`built-in roles ` or - :doc:`user-defined roles ` to the - users. - -action: - pre: | - The following operation adds a user ``myTester`` to the ``test`` - database who has :authrole:`readWrite` role in the ``test`` - database as well as :authrole:`read` role in the ``reporting`` - database. - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst - - language: javascript - code: | - use test - db.createUser( - { - user: "myTester", - pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "readWrite", db: "test" }, - { role: "read", db: "reporting" } ] - } - ) - -post: | - - .. note:: - The database where you create the user (in this example, - ``test``) is that user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can have roles in other - databases; i.e. the user's authentication database does not limit - the user's privileges. - - After creating the additional users, disconnect - :binary:`~bin.mongosh`. ---- -title: Connect to the instance and authenticate as ``myTester``. -level: 4 -ref: auth-as-mytester -content: | - - After disconnecting :binary:`~bin.mongosh` as - ``myUserAdmin``, reconnect as ``myTester``. You can: - - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - - .. tabs:: - - tabs: - - id: cmdline2 - 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 -u "myTester" --authenticationDatabase "test" -p - - Enter the password for the user when prompted. - - - id: authafter2 - name: Authenticate after Connection - content: | - - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: - - .. code-block:: bash - - mongosh --port 27017 - - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``test``), and use - :method:`db.auth(\, \) ` - method to authenticate: - .. tip:: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst - .. code-block:: javascript - - use test - db.auth("myTester", passwordPrompt()) // or cleartext password - - Enter the password for the user when prompted. ---- -title: Insert a document as ``myTester``. -level: 4 -ref: insert-as-mytester -content: | - - As ``myTester``, you have privileges to perform read and write - operations in the ``test`` database (as well as perform read - operations in the ``reporting`` database). Once authenticated as - ``myTester``, insert a document into a collection in ``test`` - database. For example, you can perform the following insert - operation in the ``test`` database: - - .. code-block:: javascript - - db.foo.insert( { x: 1, y: 1 } ) + Enter the password when prompted. ... diff --git a/source/tutorial/create-users.txt b/source/tutorial/create-users.txt index 1ae14e6a128..8c819a7c855 100644 --- a/source/tutorial/create-users.txt +++ b/source/tutorial/create-users.txt @@ -1,46 +1,58 @@ -========= -Add Users -========= +.. _create-users: + +============= +Create a User +============= .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol -Overview --------- - -.. include:: /includes/intro-rbac.rst +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. .. _add-user-prereq: Prerequisites ------------- -If you have enabled access control for your deployment, you can use -the :ref:`localhost exception ` to create the first -user in the system. This first user must have privileges to create -other users. As of MongoDB 3.0, with the localhost exception, you -can only create users on the ``admin`` database. Once you create the -first user, you must authenticate as that user to add subsequent users. -:doc:`/tutorial/enable-authentication` provides more detail about -adding users when enabling access control for a deployment. +To be able to create users, you need to: + +- :ref:`enable access control ` +- :ref:`create a user administrator ` For routine user creation, you must possess the following permissions: .. include:: /includes/access-create-user.rst -.. _add-new-user: +.. _create-user-procedure: + +Procedure +--------- + +.. note:: -Examples --------- + The following procedure uses :ref:`authentication-scram` + authentication. For additional information on other authentication + mechanisms, see :ref:`create-users-examples`. -To create a user in a MongoDB deployment, you connect to the -deployment, and then use the :method:`db.createUser()` method -or :dbcommand:`createUser` command to add the user. +.. include:: /includes/steps/authorization-create-users.rst + +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` + + +.. _create-users-examples: +.. _add-new-user: + +Additional Examples +------------------- Username/Password Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,7 +62,7 @@ database with the specified name, password, and roles. .. tip:: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst .. code-block:: javascript @@ -68,19 +80,17 @@ database with the specified name, password, and roles. } ) -:doc:`/tutorial/enable-authentication` provides more details about -enforcing authentication for your MongoDB deployment. - Kerberos Authentication ~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/extracts/create-user-intro-kerberos.rst -For Kerberos authentication, you must add the Kerberos principal -as the username. You do not need to specify a password. +For Kerberos authentication, you must add the Kerberos principal as the +username. You do not need to specify a password. -The following operation adds the Kerberos principal ``reportingapp@EXAMPLE.NET`` -with read-only access to the ``records`` database. +The following operation adds the Kerberos principal +``reportingapp@EXAMPLE.NET`` with read-only access to the ``records`` +database: .. code-block:: javascript @@ -94,10 +104,13 @@ with read-only access to the ``records`` database. } ) -:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` -and :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` -provide more details about setting up Kerberos authentication for your -MongoDB deployment. +.. seealso:: + + For more information about setting up Kerberos authentication for + your MongoDB deployment, see the following tutorials: + + - :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` + - :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` LDAP Authentication ~~~~~~~~~~~~~~~~~~~ @@ -107,8 +120,8 @@ LDAP Authentication For LDAP authentication, you must specify a username. You do not need to specify the password, as that is handled by the LDAP service. -The following operation adds the ``reporting`` user -with read-only access to the ``records`` database. +The following operation adds the ``reporting`` user with read-only +access to the ``records`` database: .. code-block:: javascript @@ -122,9 +135,13 @@ with read-only access to the ``records`` database. } ) -:doc:`/tutorial/configure-ldap-sasl-activedirectory` and -:doc:`/tutorial/configure-ldap-sasl-openldap` provide more detail about -using authenticating using LDAP. +.. seealso:: + + For more information about setting up LDAP authentication for + your MongoDB deployment, see the following tutorials: + + - :doc:`/tutorial/configure-ldap-sasl-activedirectory` + - :doc:`/tutorial/configure-ldap-sasl-openldap` x.509 Client Certificate Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -152,6 +169,16 @@ user with read-only access to the ``records`` database. } ) -:doc:`/tutorial/configure-x509-client-authentication` provides details -about setting up x.509 Client Certificate authentication for your -MongoDB deployment. +.. seealso:: + + For more information about setting up x.509 Client Certificate + authentication for your MongoDB deployment, see the following + tutorials: + + - :doc:`/tutorial/configure-x509-client-authentication` + +Next Steps +---------- + +To manage users, assign roles, and create custom roles, see +:doc:`/tutorial/manage-users-and-roles`. diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt index 40888f252b9..e1b96235d36 100644 --- a/source/tutorial/enable-authentication.txt +++ b/source/tutorial/enable-authentication.txt @@ -1,3 +1,5 @@ +.. _enable-access-control: + ===================== Enable Access Control ===================== @@ -7,70 +9,46 @@ Enable Access Control .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -Overview --------- - -Enabling access control on a MongoDB deployment enforces -authentication, requiring users to identify themselves. When accessing -a MongoDB deployment that has access control enabled, users can only -perform actions as determined by their roles. +Enabling access control on a MongoDB deployment enforces authentication. +With access control enabled, users are required to identify themselves +and can only perform actions that adhere to the permissions granted by +the roles assigned to their user. -The following tutorial enables access control on a standalone +The following tutorial enables access control for a standalone :binary:`~bin.mongod` instance and uses the :ref:`default -authentication mechanism `. For all -supported authentication mechanisms, see +authentication mechanism `. For more +information about other authentication mechanisms, see :ref:`available-authentication-mechanisms`. -User Administrator ------------------- +If you would like to enable access control for a :doc:`replica set +` or a :doc:`sharded cluster `, please refer to +one of the following resources: -With access control enabled, ensure you have a user with -:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role in the -``admin`` database. This user can administrate user and roles such as: -create users, grant or revoke roles from users, and create or modify -customs roles. +- :doc:`/tutorial/deploy-replica-set-with-keyfile-access-control` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-replica-set` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime` +- :doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime` .. _enable-auth-procedure: -Procedure ---------- - -The following procedure first adds a user administrator to a MongoDB -instance running without access control and then enables access control. - -.. note:: - - The example MongoDB instance uses :option:`port 27017 ` and the data directory ``/var/lib/mongodb`` directory . The - example assumes the existence of the data directory - ``/var/lib/mongodb``. Specify a different data directory as - appropriate. - -.. include:: /includes/steps/create-admin-then-enable-authentication.rst +Enable Access Control for a Standalone ``mongod`` Instance +---------------------------------------------------------- .. seealso:: - :doc:`/tutorial/manage-users-and-roles`. + :ref:`available-authentication-mechanisms` -Additional Considerations -------------------------- - -Replica Sets and Sharded clusters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. include:: /includes/steps/create-admin-then-enable-authentication.rst -Replica sets and sharded clusters require internal authentication -between members when access control is enabled. For more details, -please see :doc:`/core/security-internal-authentication`. +Next Steps +---------- -Localhost Exception -~~~~~~~~~~~~~~~~~~~ +To create additional users, see :doc:`/tutorial/create-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 as needed. +To manage users, assign roles, and create custom roles, see +:doc:`/tutorial/manage-users-and-roles`.