Configuration: document the 'credentials' option (#4035)

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
+```

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'

doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml

@@ -0,0 +1 @@
+instance001:

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()

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
+```

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'

doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml

@@ -0,0 +1 @@
+instance001:

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
+```

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'

doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt

@@ -0,0 +1 @@
+T0p_Secret_P@$$w0rd

doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt

@@ -0,0 +1 @@
+123456

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 <authentication>` 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

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 <configuration_reference_credentials>` section of a YAML configuration.
+For example, you can define users with the ``replication`` and ``sharding`` roles to maintain :ref:`replication <replication-master_replica_configuring_credentials>` 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 <configuration_reference_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.\<username\>.password <configuration_reference_credentials_users_name_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.\<username\>.roles <configuration_reference_credentials_users_name_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.* <configuration_reference_credentials_roles_options>` 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.\<username\>.roles <configuration_reference_credentials_users_name_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.\<username\>.privileges <configuration_reference_credentials_users_name_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 <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/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 <configuration_reference_config_context_options>` 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 <configuration_run_instance>`.
+
+After configuring how to load passwords, you can set password values using :ref:`credentials.users.\<username\>.password <configuration_reference_credentials_users_name_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 <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file>`_, `credentials_context_env <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env>`_.