diff --git a/doc/book/admin/access_control.rst b/doc/book/admin/access_control.rst index 0d64cef62a..927f761785 100644 --- a/doc/book/admin/access_control.rst +++ b/doc/book/admin/access_control.rst @@ -36,7 +36,7 @@ There might be different types of users, for example: There are two built-in users in Tarantool: -* ``admin`` is a user with all available administrative permissions. +* ``admin`` is a user with all available administrative privileges. If the connection uses an :ref:`admin-console port `, the current user is ``admin``. For example, ``admin`` is used when connecting to an instance using :ref:`tt connect ` locally using the instance name: @@ -46,7 +46,7 @@ There are two built-in users in Tarantool: To allow remote :ref:`binary port ` connections using the ``admin`` user, you need to :ref:`set a password `. -* ``guest`` is a user with minimum permissions used by default for remote :ref:`binary port ` connections. +* ``guest`` is a user with minimum privileges used by default for remote :ref:`binary port ` connections. For example, ``guest`` is used when connecting to an instance using :ref:`tt connect ` using the IP address and port without specifying the name of a user: .. code-block:: console @@ -111,13 +111,13 @@ Privileges The privileges granted to a user determine which operations the user can perform, for example: -* The ``read`` and ``write`` privileges granted to the ``space`` :ref:`object ` allow a user to read or modify data in the specified space. -* The ``create`` privilege granted to the ``space`` object allows a user to create new spaces. -* The ``execute`` privilege granted to the ``function`` object allows a user to execute the specified function. -* The ``session`` privilege granted to a user allows connecting to an instance over IPROTO. +* The ``read`` and ``write`` permissions granted to the ``space`` :ref:`object ` allow a user to read or modify data in the specified space. +* The ``create`` permission granted to the ``space`` object allows a user to create new spaces. +* The ``execute`` permission granted to the ``function`` object allows a user to execute the specified function. +* The ``session`` permission granted to a user allows connecting to an instance over IPROTO. Note that some privileges might require read and write access to certain system spaces. -For example, the ``create`` privilege granted to the ``space`` object requires ``read`` and ``write`` privileges to the :ref:`_space ` system space. +For example, the ``create`` permission granted to the ``space`` object requires ``read`` and ``write`` permissions to the :ref:`_space ` system space. Similarly, granting the ability to create functions requires ``read`` and ``write`` access to the :ref:`_func ` space. .. NOTE:: @@ -286,7 +286,7 @@ Granting privileges to a user ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To grant the specified privileges to a user, use the :ref:`box.schema.user.grant() ` function. -In the example below, ``testuser`` gets read privileges to the ``writers`` space and read/write privileges to the ``books`` space: +In the example below, ``testuser`` gets read permissions to the ``writers`` space and read/write permissions to the ``books`` space: .. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua :language: lua @@ -337,18 +337,18 @@ To get information about privileges granted to a user, call :ref:`box.schema.use In the example above, ``testuser`` has the following privileges: -* The ``execute`` privilege to the ``public`` role means that this role is :ref:`assigned to the user `. +* The ``execute`` permission to the ``public`` role means that this role is :ref:`assigned to the user `. -* The ``read`` privilege to the ``writers`` space means that the user can read data from this space. +* The ``read`` permission to the ``writers`` space means that the user can read data from this space. -* The ``read,write`` privileges to the ``books`` space mean that the user can read and modify data in this space. +* The ``read,write`` permissions to the ``books`` space mean that the user can read and modify data in this space. -* The ``session,usage`` privileges to ``universe`` mean the following: +* The ``session,usage`` permissions to ``universe`` mean the following: * ``session``: the user can authenticate over an IPROTO connection. * ``usage``: lets the user use their privileges on database objects (for example, read and modify data in a space). -* The ``alter`` privilege lets ``testuser`` modify its own settings, for example, a password. +* The ``alter`` permission lets ``testuser`` modify its own settings, for example, a password. @@ -366,7 +366,7 @@ In the example below, write access to the ``books`` space is revoked: :end-before: End: Revoke space reading :dedent: -Revoking the ``session`` privilege from ``universe`` can be used to disallow a user to connect to a Tarantool instance: +Revoking the ``session`` permission to ``universe`` can be used to disallow a user to connect to a Tarantool instance: .. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua :language: lua @@ -455,7 +455,7 @@ Granting privileges to a role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To grant the specified privileges to a role, use the :ref:`box.schema.role.grant() ` function. -In the example below, the ``books_space_manager`` role gets read and write privileges to the ``books`` space: +In the example below, the ``books_space_manager`` role gets read and write permissions to the ``books`` space: .. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua :language: lua @@ -463,7 +463,7 @@ In the example below, the ``books_space_manager`` role gets read and write privi :end-before: Grant write privileges to a role :dedent: -The ``writers_space_reader`` role gets read privileges to the ``writers`` space: +The ``writers_space_reader`` role gets read permissions to the ``writers`` space: .. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua :language: lua @@ -534,7 +534,7 @@ To get information about privileges granted to a role, call :ref:`box.schema.rol - books --]] -If a role has the ``execute`` privilege to other roles, this means that these roles are :ref:`granted to this parent role `: +If a role has the ``execute`` permission to other roles, this means that these roles are :ref:`granted to this parent role `: .. code-block:: lua @@ -594,21 +594,21 @@ For example, the ``box.schema.user.grant()`` signature looks as follows: .. code-block:: lua - box.schema.user.grant(username, privileges, object-type, object-name[, {options}]) + box.schema.user.grant(username, permissions, object-type, object-name[, {options}]) * ``username``: the name of the user that gets the specified privileges. -* ``privileges``: a string value that represents :ref:`privileges ` granted to the user. If there are several privileges, they should be separated by commas without a space. -* ``object-type``: a type of :ref:`object ` to which privileges are granted. -* ``object-name``: the name of the object to which privileges are granted. - An empty string (``""``) or ``nil`` provided instead of ``object-name`` grants the specified privileges to all objects of the specified type. +* ``permissions``: a string value that represents :ref:`permissions ` granted to the user. If there are several permissions, they should be separated by commas without a space. +* ``object-type``: a type of :ref:`object ` to which permissions are granted. +* ``object-name``: the name of the object to which permissions are granted. + An empty string (``""``) or ``nil`` provided instead of ``object-name`` grants the specified permissions to all objects of the specified type. .. NOTE:: - ``object-name`` is ignored for the following combinations of privileges and object types: + ``object-name`` is ignored for the following combinations of permissions and object types: - * Any privilege granted to ``universe``. - * The ``create`` and ``drop`` privileges for the following object types: ``user``, ``role``, ``space``, ``function``, ``sequence``. - * The ``execute`` privilege for the following object types: ``lua_eval``, ``lua_call``, ``sql``. + * Any permission granted to ``universe``. + * The ``create`` and ``drop`` permissions for the following object types: ``user``, ``role``, ``space``, ``function``, ``sequence``. + * The ``execute`` permission for the following object types: ``lua_eval``, ``lua_call``, ``sql``. .. _access_control_grant_creating_any_obj: @@ -678,8 +678,8 @@ In the example below, ``testuser`` gets privileges allowing them to create :ref: box.schema.user.grant('testuser','read,write','space','_space_sequence') box.schema.user.grant('testuser','write', 'space', '_index') -To allow ``testuser`` to alter indexes in the 'writers' space, grant the privileges below. -This example assumes that indexes in the 'writers' space are not created by ``testuser``. +To allow ``testuser`` to alter indexes in the ``writers`` space, grant the privileges below. +This example assumes that indexes in the ``writers`` space are not created by ``testuser``. .. code-block:: lua @@ -689,7 +689,7 @@ This example assumes that indexes in the 'writers' space are not created by ``te box.schema.user.grant('testuser','read','space','_space_sequence') box.schema.user.grant('testuser','write','space','_index') -If ``testuser`` created indexes in the 'writers' space, granting the following privileges is enough to alter indexes: +If ``testuser`` created indexes in the ``writers`` space, granting the following privileges is enough to alter indexes: .. code-block:: lua @@ -899,8 +899,8 @@ Whenever ``public_user`` calls the function, it is executed on behalf of its cre .. _access_control_list: -All object types and privileges -------------------------------- +All object types and permissions +-------------------------------- .. _access_control_list_objects: @@ -938,8 +938,8 @@ Object types .. _access_control_list_privileges: -Privileges -~~~~~~~~~~ +Permissions +~~~~~~~~~~~ .. container:: table @@ -947,7 +947,7 @@ Privileges :header-rows: 1 :widths: 15 15 15 55 - * - Privilege + * - Permission - Object type - Granted to roles - Description @@ -955,31 +955,31 @@ Privileges - All - Yes - Allows reading data of the specified object. - For example, this privilege can be used to allow a user to select data from the specified space. + For example, this permission can be used to allow a user to select data from the specified space. * - ``write`` - All - Yes - Allows updating data of the specified object. - For example, this privilege can be used to allow a user to modify data in the specified space. + For example, this permission can be used to allow a user to modify data in the specified space. * - ``create`` - All - Yes - Allows creating objects of the specified type. - For example, this privilege can be used to allow a user to create new spaces. + For example, this permission can be used to allow a user to create new spaces. - Note that this privilege requires read and write access to certain system spaces. + Note that this permission requires read and write access to certain system spaces. * - ``alter`` - All - Yes - Allows altering objects of the specified type. - Note that this privilege requires read and write access to certain system spaces. + Note that this permission requires read and write access to certain system spaces. * - ``drop`` - All - Yes - Allows dropping objects of the specified type. - Note that this privilege requires read and write access to certain system spaces. + Note that this permission requires read and write access to certain system spaces. * - ``execute`` - ``role``, ``universe``, ``function``, ``lua_eval``, ``lua_call``, ``sql`` - Yes @@ -997,8 +997,8 @@ Privileges .. _access_control_list_objects_and_privileges: -Object types and privileges -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Object types and permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table @@ -1015,58 +1015,58 @@ Object types and privileges * ``session``: Allows a user to connect to an instance over IPROTO. * ``usage``: Allows a user to use their privileges on database objects (for example, read, write, and alter space). * ``create``: Allows creating users, roles, functions, spaces, and sequences. - This privilege requires read and write access to certain system spaces. + This permission requires read and write access to certain system spaces. * ``drop``: Allows creating users, roles, functions, spaces, and sequences. - This privilege requires read and write access to certain system spaces. + This permission requires read and write access to certain system spaces. * ``alter``: Allows altering user settings or space objects. * - ``user`` - * ``alter``: Allows modifying a user description, for example, change the password. * ``create``: Allows creating new users. - This privilege requires read and write access to the ``_user`` system space. + This permission requires read and write access to the ``_user`` system space. * ``drop``: Allows dropping users. - This privilege requires read and write access to the ``_user`` system space. + This permission requires read and write access to the ``_user`` system space. * - ``role`` - * ``execute``: Indicates that a role is assigned to the user or another role. * ``create``: Allows creating new roles. - This privilege requires read and write access to the ``_user`` system space. + This permission requires read and write access to the ``_user`` system space. * ``drop``: Allows dropping roles. - This privilege requires read and write access to the ``_user`` system space. + This permission requires read and write access to the ``_user`` system space. * - ``space`` - * ``read``: Allows selecting data from a space. * ``write``: Allows modifying data in a space. * ``create``: Allows creating new spaces. - This privilege requires read and write access to the ``_space`` system space. + This permission requires read and write access to the ``_space`` system space. * ``drop``: Allows dropping spaces. - This privilege requires read and write access to the ``_space`` system space. + This permission requires read and write access to the ``_space`` system space. * ``alter``: Allows modifying spaces. - This privilege requires read and write access to the ``_space`` system space. + This permission requires read and write access to the ``_space`` system space. - If a space is created by a user, they can read and write it without granting explicit privileges. + If a space is created by a user, they can read and write it without granting explicit permission. * - ``function`` - * ``execute``: Allows calling a function. * ``create``: Allows creating a function. - This privilege requires read and write access to the ``_func`` system space. + This permission requires read and write access to the ``_func`` system space. - If a function is created by a user, they can execute it without granting explicit privileges. + If a function is created by a user, they can execute it without granting explicit permission. * ``drop``: Allows dropping a function. - This privilege requires read and write access to the ``_func`` system space. + This permission requires read and write access to the ``_func`` system space. * - ``sequence`` - * ``read``: Allows using sequences in ``space_obj:create_index()``. * ``write``: Allows all operations for a sequence object. - ``seq_obj:drop()`` requires a write privilege to the ``_priv`` system space. + ``seq_obj:drop()`` requires a write permission to the ``_priv`` system space. * ``create``: Allows creating sequences. - This privilege requires read and write access to the ``_sequence`` system space. + This permission requires read and write access to the ``_sequence`` system space. - If a sequence is created by a user, they can read/write it without explicit privilege. + If a sequence is created by a user, they can read/write it without explicit permission. * ``drop``: Allows dropping sequences. - This privilege requires read and write access to the ``_sequence`` system space. + This permission requires read and write access to the ``_sequence`` system space. * ``alter``: Has no effect. - ``seq_obj:alter()`` and other methods require the ``write`` privilege. + ``seq_obj:alter()`` and other methods require the ``write`` permission. * - ``lua_eval`` - * ``execute``: Allows executing arbitrary Lua code using the IPROTO_EVAL request. * - ``lua_call`` - * ``execute``: Allows executing any user-defined function using the IPROTO_CALL request. - This privilege doesn't allow a user to call built-in Lua functions (for example, ``loadstring()`` or ``box.session.su()``) and functions defined in the ``_func`` system space. + This permission doesn't allow a user to call built-in Lua functions (for example, ``loadstring()`` or ``box.session.su()``) and functions defined in the ``_func`` system space. * - ``sql`` - * ``execute``: Allows executing arbitrary SQL expression using the IPROTO_PREPARE and IPROTO_EXECUTE requests. diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md new file mode 100644 index 0000000000..251d6a3b60 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md @@ -0,0 +1,11 @@ +# Credentials + +A sample application demonstrating how configure user credentials in a YAML configuration. + +## Running + +Start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml new file mode 100644 index 0000000000..d771d4f153 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml @@ -0,0 +1,30 @@ +credentials: + users: + dbadmin: + password: 'T0p_Secret_P@$$w0rd' + roles: [ super ] + sampleuser: + password: '123456' + roles: [ writers_space_reader ] + privileges: + - permissions: [ read, write ] + spaces: [ books ] + roles: + writers_space_reader: + privileges: + - permissions: [ read ] + spaces: [ writers ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + +# Load sample data +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua new file mode 100644 index 0000000000..d316d69e97 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua @@ -0,0 +1,36 @@ +function create_spaces() + box.schema.space.create('writers') + box.space.writers:format({ + { name = 'id', type = 'unsigned' }, + { name = 'name', type = 'string' } + }) + box.space.writers:create_index('primary', { parts = { 'id' } }) + + box.schema.space.create('books') + box.space.books:format({ + { name = 'id', type = 'unsigned' }, + { name = 'title', type = 'string' }, + { name = 'author_id', foreign_key = { space = 'writers', field = 'id' } }, + }) + box.space.books:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.writers:insert { 1, 'Leo Tolstoy' } + box.space.writers:insert { 2, 'Fyodor Dostoevsky' } + box.space.writers:insert { 3, 'Alexander Pushkin' } + + box.space.books:insert { 1, 'War and Peace', 1 } + box.space.books:insert { 2, 'Anna Karenina', 1 } + box.space.books:insert { 3, 'Resurrection', 1 } + box.space.books:insert { 4, 'Crime and Punishment', 2 } + box.space.books:insert { 5, 'The Idiot', 2 } + box.space.books:insert { 6, 'The Brothers Karamazov', 2 } + box.space.books:insert { 7, 'Eugene Onegin', 3 } + box.space.books:insert { 8, 'The Captain\'s Daughter', 3 } + box.space.books:insert { 9, 'Boris Godunov', 3 } + box.space.books:insert { 10, 'Ruslan and Ludmila', 3 } +end + +create_spaces() +load_data() diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md new file mode 100644 index 0000000000..3e63c1498a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md @@ -0,0 +1,18 @@ +# Credentials: environment variables + +A sample application demonstrating how set passwords in a YAML configuration using environment variables. + +## Running + +Before starting instances, set the `DBADMIN_PASSWORD` and `SAMPLEUSER_PASSWORD` environment variables, for example: + +```console +$ export DBADMIN_PASSWORD='T0p_Secret_P@$$w0rd' +$ export SAMPLEUSER_PASSWORD='123456' +``` + +Then, start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials_context_env +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml new file mode 100644 index 0000000000..017190f28c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml @@ -0,0 +1,25 @@ +config: + context: + dbadmin_password: + from: env + env: DBADMIN_PASSWORD + sampleuser_password: + from: env + env: SAMPLEUSER_PASSWORD + +credentials: + users: + dbadmin: + password: '{{ context.dbadmin_password }}' + sampleuser: + password: '{{ context.sampleuser_password }}' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md new file mode 100644 index 0000000000..7a76cd0296 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md @@ -0,0 +1,11 @@ +# Credentials: files + +A sample application demonstrating how load passwords to a YAML configuration from files. + +## Running + +Start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials_context_file +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml new file mode 100644 index 0000000000..20354193c7 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml @@ -0,0 +1,27 @@ +config: + context: + dbadmin_password: + from: file + file: secrets/dbadmin_password.txt + rstrip: true + sampleuser_password: + from: file + file: secrets/sampleuser_password.txt + rstrip: true + +credentials: + users: + dbadmin: + password: '{{ context.dbadmin_password }}' + sampleuser: + password: '{{ context.sampleuser_password }}' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt new file mode 100644 index 0000000000..3c0da6017c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt @@ -0,0 +1 @@ +T0p_Secret_P@$$w0rd \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt new file mode 100644 index 0000000000..4632e068d5 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt @@ -0,0 +1 @@ +123456 \ No newline at end of file diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index a2653fdd35..d1f250bc9f 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -395,18 +395,15 @@ Access control ~~~~~~~~~~~~~~ The ``credentials`` section allows you to create users and grant them the specified privileges. -In the example below, there are two users: +In the example below, a ``dbadmin`` user with the specified password is created: -* The *replicator* user is used for replication and has a corresponding role. -* The *storage* user has the ``sharding`` role. - -.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml :language: yaml :start-at: credentials: - :end-at: roles: [sharding] + :end-at: T0p_Secret :dedent: -To learn more, see the :ref:`Access control ` section. +To learn more, see the :ref:`configuration_credentials` section. .. _configuration_options_memory: @@ -451,5 +448,6 @@ To learn more about the persistence mechanism in Tarantool, see the :ref:`Persis configuration/configuration_etcd configuration/configuration_code configuration/configuration_connections + configuration/configuration_credentials configuration/configuration_authentication .. configuration/configuration_migrating diff --git a/doc/concepts/configuration/configuration_credentials.rst b/doc/concepts/configuration/configuration_credentials.rst new file mode 100644 index 0000000000..a3f3179f5c --- /dev/null +++ b/doc/concepts/configuration/configuration_credentials.rst @@ -0,0 +1,120 @@ +.. _configuration_credentials: + +Credentials +=========== + +Tarantool enables flexible management of access to various database resources by providing specific privileges to users. +You can read more about the main concepts of Tarantool access control system in the :ref:`authentication` section. + +This topic describes how to create users and grant them the specified privileges in the :ref:`credentials ` section of a YAML configuration. +For example, you can define users with the ``replication`` and ``sharding`` roles to maintain :ref:`replication ` and sharding in a Tarantool cluster. + + +.. _configuration_credentials_managing_users_roles: + +Managing users and roles +------------------------ + +.. _configuration_credentials_managing_users_roles_creating_user: + +Creating a user +~~~~~~~~~~~~~~~ + +You can create new or configure credentials of the existing users in the :ref:`credentials.users ` section. + +In the example below, a ``dbadmin`` user without a password is created: + +.. code-block:: yaml + + credentials: + users: + dbadmin: {} + +To set a password, use the :ref:`credentials.users.\.password ` option: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: T0p_Secret + :dedent: + +.. _configuration_credentials_managing_users_roles_granting_privileges: + +Granting privileges to a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To assign a role to a user, use the :ref:`credentials.users.\.roles ` option. +In this example, the ``dbadmin`` user gets privileges granted to the ``super`` built-in role: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: [ super ] + :dedent: + +To create a new role, define it in the :ref:`credentials.roles.* ` section. +In the example below, the ``writers_space_reader`` role gets privileges to select data in the ``writers`` space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-after: spaces: [ books ] + :end-at: spaces: [ writers ] + :dedent: + +Then, you can assign this role to a user using :ref:`credentials.users.\.roles ` (``sampleuser`` in the example below): + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ writers_space_reader ] + :dedent: + +You can grant specific privileges directly using :ref:`credentials.users.\.privileges `. +In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + +You can find the full example here: `credentials `_. + + + +.. _configuration_credentials_loading_secrets: + +Loading secrets from safe storage +--------------------------------- + +Tarantool enables you to load secrets from safe storage such as external files or environment variables. +To do this, you need to define corresponding options in the :ref:`config.context ` section. +In the examples below, ``context.dbadmin_password`` and ``context.sampleuser_password`` define how to load user passwords from ``*.txt`` files or environment variables: + +* This example shows how to load passwords from ``*.txt`` files: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + +* This example shows how to load passwords from environment variables: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + These environment variables should be set before :ref:`starting instances `. + +After configuring how to load passwords, you can set password values using :ref:`credentials.users.\.password ` as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: credentials: + :end-at: context.sampleuser_password + :dedent: + +You can find the full examples here: `credentials_context_file `_, `credentials_context_env `_. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index d9e3c915e3..791a7dc50d 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -332,6 +332,7 @@ The ``config`` section defines various parameters related to centralized configu ``config`` can be defined in the global :ref:`scope ` only. * :ref:`config.reload ` +* :ref:`config.context.* ` * :ref:`config.etcd.* ` .. _configuration_reference_config_reload: @@ -355,6 +356,105 @@ The ``config`` section defines various parameters related to centralized configu | Environment variable: TT_CONFIG_RELOAD +.. _configuration_reference_config_context_options: + +config.context.* +~~~~~~~~~~~~~~~~ + +This section describes options related to loading configuration settings from external storage such as external files or environment variables. + +* :ref:`config.context ` + + * :ref:`config.context.\ ` + + * :ref:`config.context.\.env ` + * :ref:`config.context.\.from ` + * :ref:`config.context.\.file ` + * :ref:`config.context.\.env ` + +.. _configuration_reference_config_context: + +.. confval:: config.context + + **Since:** :doc:`3.0.0 `. + + Specify how to load settings from external storage. + For example, this option can be used to load passwords from safe storage. + You can find examples in the :ref:`configuration_credentials_loading_secrets` section. + + | + | Type: map + | Default: nil + | Environment variable: TT_CONFIG_CONTEXT + + +.. _configuration_reference_config_context_name: + +.. confval:: config.context. + + The name of an entity that identifies a configuration value to load. + +.. _configuration_reference_config_context_name_env: + +.. confval:: config.context..env + + The name of an environment variable to load a configuration value from. + To load a configuration value from an environment variable, set :ref:`config.context.\.from ` to ``env``. + + **Example:** + + In this example, passwords are loaded from the ``DBADMIN_PASSWORD`` and ``SAMPLEUSER_PASSWORD`` environment variables: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets`. + + +.. _configuration_reference_config_context_name_from: + +.. confval:: config.context..from + + The type of storage to load a configuration value from. + There are the following storage types: + + * ``file``: load a configuration value from a file. + In this case, you need to specify the path to the file using :ref:`config.context.\.file `. + * ``env``: load a configuration value from an environment variable. + In this case, specify the environment variable name using :ref:`config.context.\.env `. + + +.. _configuration_reference_config_context_name_file: + +.. confval:: config.context..file + + The path to a file to load a configuration value from. + To load a configuration value from a file, set :ref:`config.context.\.from ` to ``file``. + + **Example:** + + In this example, passwords are loaded from the ``dbadmin_password.txt`` and ``sampleuser_password.txt`` files: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets`. + + +.. _configuration_reference_config_context_name_rstrip: + +.. confval:: config.context..rstrip + + (Optional) Whether to strip whitespace characters and newlines from the end of data. + + + .. _configuration_reference_config_etcd: @@ -545,116 +645,231 @@ This section describes options related to :ref:`storing configuration in etcd `. -- :ref:`credentials.roles.* ` -- :ref:`credentials.users.* ` -- :ref:`.privileges.* ` +* :ref:`credentials.roles.* ` +* :ref:`credentials.users.* ` +* :ref:`.privileges.* ` -.. _configuration_reference_credentials_roles: +.. _configuration_reference_credentials_roles_options: -.. confval:: credentials.roles +credentials.roles.* +~~~~~~~~~~~~~~~~~~~ - | Type: map - | Default: nil - | Environment variable: TT_CREDENTIALS_ROLES +* :ref:`credentials.roles ` + * :ref:`credentials.roles.\.roles ` + * :ref:`credentials.roles.\.privileges ` -.. _configuration_reference_credentials_users: +.. _configuration_reference_credentials_roles: -.. confval:: credentials.users +.. confval:: credentials.roles - | Type: map - | Default: nil - | Environment variable: TT_CREDENTIALS_USERS + An array of :ref:`roles ` that can be granted to users or other roles. + **Example:** + In the example below, the ``writers_space_reader`` role gets privileges to select data in the ``writers`` space: -.. _configuration_reference_credentials_role: + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-after: spaces: [ books ] + :end-at: spaces: [ writers ] + :dedent: -credentials.roles.* -~~~~~~~~~~~~~~~~~~~ + See also: :ref:`configuration_credentials_managing_users_roles`. + + | Type: map + | Default: nil + | Environment variable: TT_CREDENTIALS_ROLES .. _configuration_reference_credentials_roles_name_roles: .. confval:: credentials.roles..roles + An array of :ref:`roles ` granted to this role. .. _configuration_reference_credentials_roles_name_privileges: .. confval:: credentials.roles..privileges - See :ref:`privileges `. + An array of :ref:`privileges ` granted to this role. + + See :ref:`\.privileges.* `. -.. _configuration_reference_credentials_user: +.. _configuration_reference_credentials_users_options: credentials.users.* ~~~~~~~~~~~~~~~~~~~ +* :ref:`credentials.users ` + + * :ref:`credentials.users.\.password ` + * :ref:`credentials.users.\.roles ` + * :ref:`credentials.users.\.privileges ` + +.. _configuration_reference_credentials_users: + +.. confval:: credentials.users + + An array of :ref:`users `. + + **Example:** + + In this example, ``sampleuser`` gets the following privileges: + + * Privileges granted to the ``writers_space_reader`` role. + * Privileges to select and modify data in the ``books`` space. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles`. + + | Type: map + | Default: nil + | Environment variable: TT_CREDENTIALS_USERS + .. _configuration_reference_credentials_users_name_password: .. confval:: credentials.users..password + A user's password. + + **Example:** + + In the example below, a password for the ``dbadmin`` user is set: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: T0p_Secret + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets`. .. _configuration_reference_credentials_users_name_roles: .. confval:: credentials.users..roles + An array of :ref:`roles ` granted to this user. .. _configuration_reference_credentials_users_name_privileges: .. confval:: credentials.users..privileges - See :ref:`privileges `. + An array of :ref:`privileges ` granted to this user. + See :ref:`\.privileges.* `. -.. _configuration_reference_credentials_privileges: + +.. _configuration_reference_credentials_privileges_options: .privileges.* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _configuration_reference_credentials_users_name_privileges_permissions: +* :ref:`\.privileges ` + + * :ref:`\.privileges.permissions ` + * :ref:`\.privileges.spaces ` + * :ref:`\.privileges.functions ` + * :ref:`\.privileges.sequences ` + * :ref:`\.privileges.lua_eval ` + * :ref:`\.privileges.lua_call ` + * :ref:`\.privileges.sql ` + +.. _configuration_reference_credentials_privileges: + +.. confval:: .privileges + + Privileges that can be granted to a user or role using the following options: + + * :ref:`credentials.users.\.privileges ` + * :ref:`credentials.roles.\.privileges ` + +.. _configuration_reference_credentials_privileges_permissions: .. confval:: .privileges.permissions + :ref:`Permissions ` assigned to this user or a user with this role. + + **Example:** -.. _configuration_reference_credentials_users_name_privileges_spaces: + In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles`. + +.. _configuration_reference_credentials_privileges_spaces: .. confval:: .privileges.spaces + Spaces to which this user or a user with this role gets the specified permissions. + + **Example:** + + In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: -.. _configuration_reference_credentials_users_name_privileges_functions: + See also: :ref:`configuration_credentials_managing_users_roles`. + + +.. _configuration_reference_credentials_privileges_functions: .. confval:: .privileges.functions + Functions to which this user or a user with this role gets the specified permissions. -.. _configuration_reference_credentials_users_name_privileges_sequences: + +.. _configuration_reference_credentials_privileges_sequences: .. confval:: .privileges.sequences + Sequences to which this user or a user with this role gets the specified permissions. + -.. _configuration_reference_credentials_users_name_privileges_lua_eval: +.. _configuration_reference_credentials_privileges_lua_eval: .. confval:: .privileges.lua_eval + Whether this user or a user with this role can execute arbitrary Lua code. -.. _configuration_reference_credentials_users_name_privileges_lua_call: + +.. _configuration_reference_credentials_privileges_lua_call: .. confval:: .privileges.lua_call + Whether this user or a user with this role can call any global user-defined Lua function. + -.. _configuration_reference_credentials_users_name_privileges_sql: +.. _configuration_reference_credentials_privileges_sql: .. confval:: .privileges.sql + Whether this user or a user with this role can execute an arbitrary SQL expression. + diff --git a/doc/reference/reference_lua/box_schema/role_grant.rst b/doc/reference/reference_lua/box_schema/role_grant.rst index 99f9789a70..e9c840c832 100644 --- a/doc/reference/reference_lua/box_schema/role_grant.rst +++ b/doc/reference/reference_lua/box_schema/role_grant.rst @@ -6,16 +6,16 @@ box.schema.role.grant() .. module:: box.schema -.. function:: box.schema.role.grant(role-name, privilege, object-type, object-name [, option]) - box.schema.role.grant(role-name, privilege, 'universe' [, nil, option]) +.. function:: box.schema.role.grant(role-name, permissions, object-type, object-name [, option]) + box.schema.role.grant(role-name, permissions, 'universe' [, nil, option]) box.schema.role.grant(role-name, role-name [, nil, nil, option]) Grant :ref:`privileges ` to a role. :param string role-name: the name of the role - :param string privilege: one or more :ref:`privileges ` to grant to the role (for example, ``read`` or ``read,write``) - :param string object-type: a database :ref:`object type ` to grant privileges to (for example, ``space``, ``role``, or ``function``) - :param string object-name: the name of a function or space or sequence or role + :param string permissions: one or more :ref:`permissions ` to grant to the role (for example, ``read`` or ``read,write``) + :param string object-type: a database :ref:`object type ` to grant permissions to (for example, ``space``, ``role``, or ``function``) + :param string object-name: the name of a database object to grant permissions to :param table option: ``if_not_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the role already has the privilege @@ -25,7 +25,7 @@ box.schema.role.grant() **Variation:** instead of ``object-type, object-name`` say ``universe`` which means 'all object-types and all objects'. In this case, object name is omitted. - **Variation:** instead of ``privilege, object-type, object-name`` say + **Variation:** instead of ``permissions, object-type, object-name`` say ``role-name`` -- to grant a role to a role. **Example:** diff --git a/doc/reference/reference_lua/box_schema/role_revoke.rst b/doc/reference/reference_lua/box_schema/role_revoke.rst index f9cf898af5..2933da8dac 100644 --- a/doc/reference/reference_lua/box_schema/role_revoke.rst +++ b/doc/reference/reference_lua/box_schema/role_revoke.rst @@ -6,14 +6,14 @@ box.schema.role.revoke() .. module:: box.schema -.. function:: box.schema.role.revoke(role-name, privilege, object-type, object-name) +.. function:: box.schema.role.revoke(role-name, permissions, object-type, object-name) Revoke :ref:`privileges ` from a role. :param string role-name: the name of the role - :param string privilege: one or more :ref:`privileges ` to revoke from the role (for example, ``read`` or ``read,write``) - :param string object-type: a database :ref:`object type ` to revoke privileges from (for example, ``space``, ``role``, or ``function``) - :param string object-name: the name of a database object to revoke privileges from + :param string permissions: one or more :ref:`permissions ` to revoke from the role (for example, ``read`` or ``read,write``) + :param string object-type: a database :ref:`object type ` to revoke permissions from (for example, ``space``, ``role``, or ``function``) + :param string object-name: the name of a database object to revoke permissions from The role must exist, and the object must exist, but it is not an error if the role does not have the privilege. @@ -21,7 +21,7 @@ box.schema.role.revoke() **Variation:** instead of ``object-type, object-name`` say ``universe`` which means 'all object-types and all objects'. - **Variation:** instead of ``privilege, object-type, object-name`` say + **Variation:** instead of ``permissions, object-type, object-name`` say ``role-name``. See also: :ref:`access_control_roles`. diff --git a/doc/reference/reference_lua/box_schema/user_grant.rst b/doc/reference/reference_lua/box_schema/user_grant.rst index a5a1e36322..de4f17af3c 100644 --- a/doc/reference/reference_lua/box_schema/user_grant.rst +++ b/doc/reference/reference_lua/box_schema/user_grant.rst @@ -6,17 +6,17 @@ box.schema.user.grant() .. module:: box.schema -.. function:: box.schema.user.grant(username, privileges, object-type, object-name[, {options} ]) - box.schema.user.grant(username, privileges, 'universe'[, nil, {options} ]) +.. function:: box.schema.user.grant(username, permissions, object-type, object-name[, {options} ]) + box.schema.user.grant(username, permissions, 'universe'[, nil, {options} ]) box.schema.user.grant(username, role-name[, nil, nil, {options} ]) Grant :ref:`privileges ` to a user or to another role. :param string username: the name of a user to grant privileges to - :param string privileges: one or more :ref:`privileges ` to grant to the user (for example, ``read`` or ``read,write``) - :param string object-type: a database :ref:`object type ` to grant privileges to (for example, ``space``, ``role``, or ``function``) - :param string object-name: the name of a database object to grant privileges to + :param string permissions: one or more :ref:`permissions ` to grant to the user (for example, ``read`` or ``read,write``) + :param string object-type: a database :ref:`object type ` to grant permissions to (for example, ``space``, ``role``, or ``function``) + :param string object-name: the name of a database object to grant permissions to :param string role-name: the name of a role to grant to the user :param table options: ``grantor``, ``if_not_exists`` @@ -26,7 +26,7 @@ box.schema.user.grant() **Variation:** instead of ``object-type, object-name`` say ``universe`` which means 'all object-types and all objects'. In this case, object name is omitted. - **Variation:** instead of ``privilege, object-type, object-name`` say + **Variation:** instead of ``permissions, object-type, object-name`` say ``role-name`` (see section :ref:`Roles `). **Variation:** instead of diff --git a/doc/reference/reference_lua/box_schema/user_revoke.rst b/doc/reference/reference_lua/box_schema/user_revoke.rst index 1672262e27..6bc9559217 100644 --- a/doc/reference/reference_lua/box_schema/user_revoke.rst +++ b/doc/reference/reference_lua/box_schema/user_revoke.rst @@ -6,17 +6,17 @@ box.schema.user.revoke() .. module:: box.schema -.. function:: box.schema.user.revoke(username, privileges, object-type, object-name[, {options} ]) - box.schema.user.revoke(username, privileges, 'universe'[, nil, {options} ]) +.. function:: box.schema.user.revoke(username, permissions, object-type, object-name[, {options} ]) + box.schema.user.revoke(username, permissions, 'universe'[, nil, {options} ]) box.schema.user.revoke(username, role-name[, nil, nil, {options} ]) Revoke :ref:`privileges ` from a user or from another role. :param string username: the name of the user - :param string privilege: one or more :ref:`privileges ` to revoke from the user (for example, ``read`` or ``read,write``) - :param string object-type: a database :ref:`object type ` to revoke privileges from (for example, ``space``, ``role``, or ``function``) - :param string object-name: the name of a database object to revoke privileges from + :param string permissions: one or more :ref:`permissions ` to revoke from the user (for example, ``read`` or ``read,write``) + :param string object-type: a database :ref:`object type ` to revoke permissions from (for example, ``space``, ``role``, or ``function``) + :param string object-name: the name of a database object to revoke permissions from :param table options: ``if_exists`` The user must exist, and the object must exist, @@ -26,7 +26,7 @@ box.schema.user.revoke() **Variation:** instead of ``object-type, object-name`` say 'universe' which means 'all object-types and all objects'. - **Variation:** instead of ``privilege, object-type, object-name`` say + **Variation:** instead of ``permissions, object-type, object-name`` say ``role-name`` (see section :ref:`Roles `). **Variation:** instead of