Rework the Access control topic #4024

andreyaksenov · 2024-01-26T10:39:00Z

Reworked the Access control topic:

Rewrote the part about Access Control concepts. Now concepts and how-to instructions are documented separately.
Added testable samples that show how to work with users and roles.
Added a separate how-to section that shows how to grant privileges for specific object types.
Added info from the Wiki page about combinations of different object types and privileges. Note that some low-level details might be missing in the updated topic.
Included new samples to reference:

Next step: #4035.

Lord-KA

Thank you for the patchset! Now access control documentation looks much better overall. See my minor comments below

doc/book/admin/access_control.rst

Lord-KA · 2024-02-08T13:13:11Z

doc/book/admin/access_control.rst

+
+In the example above, 'testuser' has the following privileges:
+
+*   The 'execute' privilege to the 'public' role means that this role is :ref:`assigned to a user <access_control_roles_granting_user>`.


Nit:

assigned to the user

(We are talking about 'testuser' here, or some other specific user that has this grant)

Maybe note here, that 'public' is granted to all users on creation?
(I know, that this is stated in the Roles section, but it could be helpful in describing a users privileges too)

assigned to the user

Exactly! Thanks for the catch

Maybe note here, that 'public' is granted to all users on creation?
(I know, that this is stated in the Roles section, but it could be helpful in describing a users privileges too)

I'd keep it as is because it is a how-to section and maintaining such info in several places might be hard if some privileges/roles change for the default user.

Exactly! Thanks for the catch

It seems like there is the same issue in other bullet-points below

It seems like there is the same issue in other bullet-points below

Thanks, fixed

doc/book/admin/access_control.rst

p7nov

Please see my comments

doc/book/admin/access_control.rst

p7nov · 2024-02-09T10:15:36Z

doc/book/admin/access_control.rst

-the current user is '**admin**'.
-When executing a :ref:`Lua initialization script <index-init_label>`,
-the current user is also ‘**admin**’.
+A user is a person or program that interacts with a Tarantool instance.


This definition looks too broad and vague without details.
I'd provide a more detailed explanation:

Technically, a user we talk about is an entity in Tarantool, not a person or external program.

But it corresponds (== can be used by) either to a person, or to a program, enabling them to do something

I feel that identify should work better here:

A user identifies a person or program that interacts with a Tarantool instance.

And this is eliminates the need of using the entity word that might add some confusion :)

p7nov · 2024-02-09T10:18:35Z

doc/book/admin/access_control.rst

-:doc:`/reference/reference_lua/box_session/user`.
+*   A database administrator is responsible for the overall management and administration of a database.
+    An administrator can create other users and grant them specified privileges.
+*   A regular user has limited access to certain data and stored functions. For example, such users can be used to let :ref:`connectors <index-box_connectors>` communicate to a database.


I don't think that regular user is definitive enough. Maybe write a more specific example?

Additionally, this example confused me: from the start, I expected this to be a person that works on data in specific spaces, but then it turned out that it's about connectors.

Good point. Removed information about connectors because this is a specific case. Both admin and regular user might work directly or using a connector.
Also, added info that users can get privileges from dbadmin.

p7nov · 2024-02-09T10:22:54Z

doc/book/admin/access_control.rst

+*   A database administrator is responsible for the overall management and administration of a database.
+    An administrator can create other users and grant them specified privileges.
+*   A regular user has limited access to certain data and stored functions. For example, such users can be used to let :ref:`connectors <index-box_connectors>` communicate to a database.
+*   Users used in communications between Tarantool instances. For example, such users can be created to maintain replication and sharding in a Tarantool cluster.


These users: are they people or programs? I think a deeper explanation is needed here.

p7nov · 2024-02-09T10:23:37Z

doc/book/admin/access_control.rst

-The current user can be changed:
+There are two built-in users in Tarantool:
+
+*   'admin' is a user with all available administrative permissions.


Let's use the code style (double backticks) for all user, role, privilege, etc. names on this page.

p7nov · 2024-02-09T10:54:46Z

doc/book/admin/access_control.rst

-Here a Lua function is created that will be executed under the user ID of its
+    box.schema.user.grant(user-name, privileges, object-type, object-name[, {options}])
+
+*   ``user-name``: the name of the user that gets the specified privileges.


Hyphenated user-name looks grammatically incorrect (although I get why it is used here). Let's maybe change to either user or username?

Hmm.. In this case we need to fix this in all reference pages related to privileges (because I just copy-pasted this from the box.schema.user.grant page).

p7nov · 2024-02-09T10:59:52Z

doc/book/admin/access_control.rst

+Creating and altering spaces
+****************************
+
+In the example below, 'testuser' gets privileges allowing them to create :ref:`spaces <index-box_space>`:


The need to grant privileges to implicitly connected system objects is really hardcore. Can we maybe find a place to explain this in general before showing these lists of calls?

I hope, this should be enough:

Yes, but I have two concerns:

This text is too far from the section where this question came up. Hardly somebody will read the whole page of this size.

Note that some looks like some rare or specific thing. To me, this whole point seems like a general concept of the Tarantool access model. I'd explain it in a stronger and more exact wording. Just a personal opinion, you decide.

This text is too far from the section where this question came up. Hardly somebody will read the whole page of this size.

Will add a note after the first example to remind a reader about this concept.

p7nov · 2024-02-09T11:04:11Z

doc/book/admin/access_control.rst

+Example
+~~~~~~~
+
+In the example below, the created Lua function is executed under the user ID of its
 creator, even if called by another user.

 First, the two spaces ('u' and 'i') are created, and a no-password user ('internal')


Let's use more self-explanatory and realistic entity names than u, i, and internal.

Okay :) just copy-pasted this example from old docs as is and was a bit lazy to fix this.

p7nov · 2024-02-09T11:05:43Z

doc/book/admin/access_control.rst

+        :header-rows: 1
+        :widths: 15 85
+
+        *   -   Object type


Wouldn't this look better in a three-column table?

Hmm.. Thought about this but cell merging in the first column is required for better readability. Does Sphinx support this?

AFAIR, no: tables in Sphinx/RST are a bit limited.

p7nov · 2024-02-09T11:07:14Z

doc/code_snippets/test/access_control/grant_user_privileges_test.lua

+g.test_user_with_password_created = function(cg)
+    cg.server:exec(function()
+        -- Create a user with a password --
+        box.schema.user.create('testuser', { password = 'foobar' })


Nit: most style guides recommend avoiding foo/bar anywhere in examples.

Usually password is "secret", or something similar.

Usually password is "secret", or something similar.

Thanks for your suggestion. Honestly, I try not to use meaningful words as password examples in docs because they make a reader think about the word meaning. IMO, passwords should look like some gibberish, well-known weak passwords (123456), or smth like P@$$word) to allow a reader quickly scan it und understand it is a password, not smth else. Not sure I'm right here :)

p7nov

LGTM in general, just some more ideas and qeustion.

p7nov · 2024-02-12T05:04:51Z

doc/book/admin/access_control.rst

 Access control
-================================================================================
+==============


Idea: use the words role-based access control system/model explicitly somewhere in the intro paragraph. This is a familiar term, it helps readers understand general concepts easier.

Privileges can be assigned directly to a user. So, role-based access control doesn't cover all possible capabilities of Tarantool access control system.

p7nov · 2024-02-12T05:06:54Z

doc/book/admin/access_control.rst


-Briefly:
+*   A *user* is a person or program that interacts with a Tarantool instance.
+*   An *object* is an entity to which access can be granted, for example, spaces, indexes, or functions.


Singular a space, an index, a function would be more precise, since we grant permissions per object, not for all spaces (functions) at once.

p7nov · 2024-02-12T05:08:11Z

doc/book/admin/access_control.rst

-Briefly:
+*   A *user* is a person or program that interacts with a Tarantool instance.
+*   An *object* is an entity to which access can be granted, for example, spaces, indexes, or functions.
+*   *Privileges* allow a user to perform certain operations on specific objects, for example, creating spaces, reading or updating data.


Maybe A privilege for consistency with other list items?

p7nov · 2024-02-12T05:10:50Z

doc/book/admin/access_control.rst

-the minimal privileges necessary for particular operations,
-to user 'U'.
+*   ``super`` has all available administrative permissions.
+*   ``public`` is automatically granted to new users when they are created.


Can we say anything specific or give a usage advice about this role? The current definition gives me no idea why is it needed and how to use it...

p7nov · 2024-02-12T05:14:24Z

doc/book/admin/access_control.rst

+*   ``super`` has all available administrative permissions.
+*   ``public`` is automatically granted to new users when they are created.
+*   ``replication`` can be granted to a user used to maintain :ref:`replication <replication_overview>` in a cluster.
+*   ``sharding`` can be granted to a user used to maintain :ref:`sharding <sharding>` in a cluster.


I'm still confused about the two last roles.
Are they purely internal/technical by purpose? Should a person ever use them manually or change their privileges?
I mean, if I need to administer a cluster, do I connect to an instance using these role and call some functions by hand? Or Tarantool only uses them under the hood?

Are they purely internal/technical by purpose?

AFAIU, yes. They are granted to corresponding service users in a cluster config.

Should a person ever use them manually or change their privileges?

No, they designed only for specific internal operations.

p7nov · 2024-02-12T05:26:33Z

doc/book/admin/access_control.rst

+Example
+~~~~~~~
+
+In the example below, the created Lua function is executed under the user ID of its


on behalf of sounds more natural than than under the user ID.

p7nov · 2024-02-12T05:29:03Z

doc/book/admin/access_control.rst

+    end
+
+    box.session.su('private_user')
+    box.schema.func.create('read_and_modify', {setuid= true})


I believe, this is what should be explained explicitly: setuid = true.
Most other code is pretty obvious, but this option is

new and unknown to readers

key - it is what sets the user for function execution

Added a link to the box.schema.func.create page where setuid is described in details.

p7nov · 2024-02-12T05:33:13Z

doc/book/admin/access_control.rst

+In the example below, the created Lua function is executed under the user ID of its
+creator, even if called by another user.
+
+First, the two spaces (``space1`` and ``space2``) are created, and a no-password user (``private_user``)


nit: no-password user sounds weird, especially when used three times in a row as a user's identifier in text. If it's really important, let's say it once and not repeat. Although I'd rephrase this completely.

Replaced no-password user with private_user in the next sentences.

p7nov · 2024-02-12T05:35:30Z

doc/book/admin/access_control.rst

+    box.schema.func.create('read_and_modify', {setuid= true})
+    box.session.su('admin')
+    box.schema.user.create('public_user', {password = 'secret'})
+    box.schema.user.grant('public_user', 'execute', 'function', 'read_and_modify')


Let's maybe write a conclusion sentence, smth like: now whenever public_user calls the function, it is executed on behalf of its creator, private_user

p7nov · 2024-02-12T05:39:44Z

doc/reference/reference_lua/box_schema/user_create.rst

@@ -21,7 +21,7 @@ box.schema.user.create()
    * ``password`` (default = '') - string; the ``password`` = *password*
      specification is good because in a :ref:`URI <index-uri>`
      (Uniform Resource Identifier) it is usually illegal to include a
-      user-name without a password.
+      username without a password.

    .. NOTE::


Wow, this surprised me a lot!
Isn't it important enough to mention in the Users section of Access control?

This is also described in Limitations: https://www.tarantool.io/en/doc/latest/book/box/limitations/.
I'd keep it as is because it might be hard to maintain such reference information is multiple places.

andreyaksenov force-pushed the config-credentials branch 2 times, most recently from 00722e9 to 39e6b0d Compare February 1, 2024 13:54

andreyaksenov linked an issue Feb 2, 2024 that may be closed by this pull request

[Config] Document the 'credentials' option #3666

Closed

andreyaksenov force-pushed the config-credentials branch 27 times, most recently from 4ec60c0 to c67366a Compare February 5, 2024 12:05

andreyaksenov force-pushed the config-credentials branch 2 times, most recently from 2733ee4 to 4530623 Compare February 8, 2024 08:00

Lord-KA reviewed Feb 8, 2024

View reviewed changes

andreyaksenov force-pushed the config-credentials branch from 425c886 to f3e510e Compare February 9, 2024 07:26

andreyaksenov requested a review from p7nov February 9, 2024 07:36

andreyaksenov added 5 commits February 9, 2024 11:05

Credentials: topic

642f95b

Credentials: tests

3b36fa7

Credentials: topic - update

5f25f00

Credentials: roles sample

4e3b3da

Credentials: update per review

c99cdfa

andreyaksenov force-pushed the config-credentials branch from f3e510e to c99cdfa Compare February 9, 2024 08:06

Credentials: update per review 2

04077b7

p7nov requested changes Feb 9, 2024

View reviewed changes

Credentials: update per review 3

99248cd

andreyaksenov force-pushed the config-credentials branch 2 times, most recently from 7220146 to 0ddf76b Compare February 9, 2024 14:37

andreyaksenov requested a review from p7nov February 9, 2024 14:50

Credentials: update per TW review

0f48f28

andreyaksenov force-pushed the config-credentials branch from 0ddf76b to 32a1c25 Compare February 9, 2024 15:14

Lord-KA approved these changes Feb 9, 2024

View reviewed changes

p7nov approved these changes Feb 12, 2024

View reviewed changes

andreyaksenov force-pushed the config-credentials branch 2 times, most recently from f825a30 to b2f3d67 Compare February 12, 2024 09:37

andreyaksenov added 2 commits February 12, 2024 12:48

Credentials: update per TW review - update reference

49f53c7

Credentials: update per TW review 2

f28b61b

andreyaksenov force-pushed the config-credentials branch from b2f3d67 to f28b61b Compare February 12, 2024 09:48

andreyaksenov merged commit 693828c into latest Feb 12, 2024
1 check passed

andreyaksenov deleted the config-credentials branch February 12, 2024 09:59

andreyaksenov changed the title ~~Document config credentials~~ Rework the Access control topic Feb 12, 2024

andreyaksenov mentioned this pull request Feb 12, 2024

Configuration: document the 'credentials' option #4035

Merged


		In the example above, 'testuser' has the following privileges:

		* The 'execute' privilege to the 'public' role means that this role is :ref:`assigned to a user <access_control_roles_granting_user>`.

Rework the Access control topic #4024

Rework the Access control topic #4024

Conversation

andreyaksenov commented Jan 26, 2024 • edited Loading

Lord-KA left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

p7nov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Feb 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Feb 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

p7nov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov commented Jan 26, 2024 •

edited

Loading

andreyaksenov Feb 12, 2024 •

edited

Loading

andreyaksenov Feb 9, 2024 •

edited

Loading