Skip to content

Commit b241d6a

Browse files
p7novp7nov
committed
Add TCM access control draft
1 parent c0f4522 commit b241d6a

File tree

3 files changed

+393
-2
lines changed

3 files changed

+393
-2
lines changed

‎doc/reference/tooling/tcm/index.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,6 @@ You can create users and assign them roles that include required permissions.
2828
For example, a user can be an administrator of a specific cluster or only have the right
2929
to read data. LDAP authorization is supported as well.
3030

31-
.. TODO: table of contents
31+
.. toctree::
32+
33+
tcm_access_control

‎doc/reference/tooling/tcm/tcm_access_control.rst

Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
.. _tcm_access_control:
2+
3+
Access control
4+
==============
5+
6+
.. admonition:: Enterprise Edition
7+
:class: fact
8+
9+
|tcm_full_name| is a part of the `Enterprise Edition <https://www.tarantool.io/compare/>`_.
10+
11+
|tcm_full_name| features a role-based access control system. It enables flexible
12+
management of access to |tcm| functions, connected clusters, and stored data.
13+
There are three main entities in the |tcm| access system: permissions, roles,
14+
and users (or user accounts). They work as follows:
15+
16+
- Permissions correspond to specific functions or objects in
17+
|tcm| (*administrative permissions*) or operations on clusters (*cluster permissions*).
18+
- Roles are predefined sets of *administrative* permissions to
19+
assign to users.
20+
- Users have roles that define their access rights to |tcm| function and objects, and
21+
*cluster* permissions that are assigned for each cluster separately.
22+
23+
.. note::
24+
25+
|tcm| users, roles, and permissions are not to be confused with similar subjects
26+
of :ref:`Tarantool access control system <authentication>`. To access Tarantool
27+
instances directly, Tarantool users with corresponding roles are required.
28+
29+
.. _tcm_access_control_permissions:
30+
31+
Permissions
32+
-----------
33+
34+
Permissions define access to specific actions that users can do in |tcm|. For example,
35+
there are permissions to view connected clusters or to manage users.
36+
37+
There are two types of permissions in |tcm|: *administrative* and *cluster* permissions.
38+
39+
* *Administrative permissions* provide access to |tcm| functions. They define which
40+
pages and controls are available to users in the web UI. Typically, *read* permissions
41+
define pages shown in the left menu. *Write* permissions define the availability
42+
of controls for managing objects on the pages.
43+
For example, users with read permission to clusters can view the **Clusters** page
44+
but they don't see **Add**, **Edit**, or **Remove** buttons unless they have the
45+
write permission.
46+
47+
Administrative permissions are assigned to users through :ref:`roles <tcm_access_control_roles>`.
48+
49+
* *Cluster permissions* enable actions with connected Tarantool clusters.
50+
These permission are granted to users on a per-cluster level: each user has a separate
51+
set of permissions for each cluster.
52+
53+
Technically, cluster permissions define pages shown in the **Cluster** section
54+
of the left menu and controls available on these pages. For example, users
55+
with the read configuration permission to a cluster configuration see the **Configuration**
56+
page when this cluster is selected.
57+
58+
Cluster permissions are assigned to users individually when creating or editing them.
59+
60+
Permissions are predefined in |tcm|, there is no way to change, add, or delete them.
61+
The complete lists of administrative and cluster permissions in |tcm| are provided
62+
in the :ref:`Permissions reference <tcm_access_control_permissions_ref>`.
63+
64+
.. _tcm_access_control_roles:
65+
66+
Roles
67+
-----
68+
69+
Roles are groups of :ref:`administrative permissions <tcm_access_control_permissions>`
70+
that are assigned to users together.
71+
72+
The assigned roles define pages that users see in |tcm| and actions available
73+
on these pages.
74+
75+
.. note::
76+
77+
Roles don't include cluster permissions. Access to connected clusters
78+
is configured for each user individually.
79+
80+
Default roles
81+
~~~~~~~~~~~~~
82+
83+
|tcm| comes with default roles that cover three common usage scenarios:
84+
85+
- **Super Admin Role** is a default role with all available
86+
:ref:`administrative permissions <tcm_access_control_permissions_admin>`.
87+
Additionally, the users with this role automatically gain all
88+
:ref:`cluster permissions <tcm_access_control_permissions_cluster>`
89+
to all clusters.
90+
- **Cluster Admin Role** is a default role for cluster administration. It includes
91+
administrative permissions for cluster management.
92+
- **Default User Role** is a default role for working with clusters. It includes
93+
basic administrative *read* permissions that are required to log in to |tcm|
94+
and navigate to a cluster.
95+
96+
Managing roles
97+
~~~~~~~~~~~~~~
98+
99+
Administrators can create new roles, edit, and delete existing ones.
100+
101+
Roles are listed on the **Roles** page.
102+
103+
To create a new role, click **Add**, enter the role name, and select the permissions
104+
to include in the role.
105+
106+
To edit an existing role, click **Edit** in the **Actions** menu of the corresponding
107+
table row.
108+
109+
To delete a role, click **Delete** in the **Actions** menu of the corresponding
110+
table row.
111+
112+
.. note::
113+
114+
You can delete a role only if there are no users with this role.
115+
116+
Users
117+
-----
118+
119+
|tcm| users gain access to objects and actions through assigned :ref:`roles <tcm_access_control_roles>`
120+
and :ref:`cluster permissions <tcm_access_control_permissions>`.
121+
Each user can have any number of roles, including zero. Users without roles
122+
have access only to clusters that are assigned to them.
123+
124+
|tcm| uses password authentication for users. For information on password management,
125+
see the :ref:`Passwords <tcm_access_control_password>` section below.
126+
127+
Default admin
128+
~~~~~~~~~~~~~
129+
130+
There is one default user **Default Admin**. It has all the available permissions,
131+
both administrative and cluster ones. When new clusters are added in |tcm|,
132+
**Default Admin** automatically receives all cluster permissions for them as well.
133+
134+
Managing users
135+
~~~~~~~~~~~~~~
136+
137+
Administrators can create new users, edit, and delete existing ones.
138+
139+
The tools for managing users are located on the **Users** page.
140+
141+
To create a user:
142+
143+
1. Click **Add**.
144+
2. Fill in the user information: username, full name, and description.
145+
3. Generate or enter a password.
146+
4. Select roles to assign to user.
147+
5. Add clusters to give the user access to, and select cluster permissions for
148+
each of them.
149+
150+
To edit a user, click **Edit** in the **Actions** menu of the corresponding table row.
151+
152+
To delete a user, click **Delete** in the **Actions** menu of the corresponding table row.
153+
154+
.. _tcm_access_control_password:
155+
156+
Passwords
157+
---------
158+
159+
|tcm| uses the general term *secret* for user authentication keys. A secret is any
160+
pair of a public and a private key that can be used for authentication. In |tcm| |tcm_version|,
161+
*password* is the only supported secret type. In this case, the public key is a username,
162+
and the private key is a password.
163+
164+
Users receive their first passwords during the account creation. It can be entered
165+
manually or generated automatically.
166+
167+
All passwords are governed by the :ref:`password policy <tcm_access_control_password_policy>`.
168+
It can be flexibly configured to follow security requirements of your organization.
169+
170+
Changing your password
171+
~~~~~~~~~~~~~~~~~~~~~~
172+
173+
To change your own password, click your name in the top-right corner and go to
174+
**Settings** > **Change password**.
175+
176+
Changing users' passwords
177+
~~~~~~~~~~~~~~~~~~~~~~~~~
178+
179+
Administrators can manage a user's passwords on this user's **Secrets** page.
180+
To open it, click **Secrets** in the **Actions** menu of the corresponding **Users** table row.
181+
182+
To change a user's password, click **Edit** in the **Actions** menu of the corresponding
183+
**Secrets** table row and enter the new password in the **New secret key** field.
184+
185+
Password expiry
186+
~~~~~~~~~~~~~~~
187+
188+
Passwords expire automatically after the expiration period defined in the :ref:`password policy <tcm_access_control_password_policy>`.
189+
When a user logs in to |tcm| with an expired password, the only action available to
190+
them is password change. All other |tcm| functions and objects are unavailable until
191+
the new password is set.
192+
193+
Administrators can also set users' password to expired manually.
194+
To set a user's password to expired, click **Expire** in the **Actions**
195+
menu of the corresponding **Secrets** table row.
196+
197+
.. important::
198+
199+
Password expiration can't be reverted.
200+
201+
Blocking passwords
202+
~~~~~~~~~~~~~~~~~~
203+
204+
To forbid users' access to |tcm|, administrators can temporarily block their
205+
passwords. A blocked password can't be used to log into |tcm| until it's
206+
unblocked manually or the blocking period expires.
207+
208+
To block a user's password, click **Block** in the **Actions** menu of the corresponding
209+
**Secrets** table row. Then provide a blocking reason and enter the blocking period.
210+
211+
To unblock a blocked password, click **Unblock** in the **Actions** menu of the corresponding
212+
**Secrets** table row.
213+
214+
.. _tcm_access_control_password_policy:
215+
216+
Password policy
217+
~~~~~~~~~~~~~~~
218+
219+
Password policy helps improve security and comply with security requirements that
220+
can apply to your organization.
221+
222+
You can edit the |tcm| password policy on the **Password policy** page.
223+
There are the following password policy settings:
224+
225+
- **Minimal password length**.
226+
- **Do not use last N passwords**.
227+
- **Password expiration in days**. After this number of days, the user loses access
228+
to any objects and functions except password change. After they change the password,
229+
all the access rights are returned.
230+
- **Password expiration warning in days**. After this number of days, the user
231+
sees a warning that they must change their password.
232+
- **Block after N login attempts**.
233+
- **User lockout time in seconds**.
234+
- **Password must include**. Characters and symbols that must be present in passwords:
235+
236+
- **Lowercase characters (a-z)**
237+
- **Uppercase characters (A-Z)**
238+
- **Digits (0-9)**
239+
- **Symbols (such as !@#$%^&\*()_+№"':,.;=][{}`?>/.)**
240+
241+
.. _tcm_access_control_sessions:
242+
243+
Sessions
244+
--------
245+
246+
Administrators can view and revoke user sessions in |tcm|. All active sessions
247+
are listed on the **Sessions** page. To revoke a session, click **Revoke** in the
248+
**Actions** menu of the corresponding table row.
249+
250+
To revoke all sessions of a user, go to **Users** and click **Revoke all sessions**
251+
in the **Actions** menu of the corresponding table row.
252+
253+
.. _tcm_access_control_permissions_ref:
254+
255+
Permissions reference
256+
---------------------
257+
258+
.. _tcm_access_control_permissions_admin:
259+
260+
Administrative permissions
261+
~~~~~~~~~~~~~~~~~~~~~~~~~~
262+
263+
The following administrative permissions are available in |tcm|:
264+
265+
.. list-table::
266+
:widths: 30 70
267+
:header-rows: 1
268+
269+
* - Permission
270+
- Description
271+
272+
* - ``admin.clusters.read``
273+
- View connected clusters
274+
275+
* - ``admin.clusters.write``
276+
- Edit cluster details and add new clusters
277+
278+
* - ``admin.users.read``
279+
- View users
280+
281+
* - ``admin.users.write``
282+
- Edit user details and add new users
283+
284+
* - ``admin.roles.read``
285+
- View roles
286+
287+
* - ``admin.roles.write``
288+
- Edit roles and add new roles
289+
290+
* - ``admin.lowlevel.state.read``
291+
- Read low-level information from |tcm| storage
292+
293+
* - ``admin.lowlevel.state.write``
294+
- Write low-level information from |tcm| storage
295+
296+
* - ``admin.addons.read``
297+
- View add-ons
298+
299+
* - ``admin.addons.write``
300+
- Edit add-on flags
301+
302+
* - ``admin.addons.upload``
303+
- Upload new add-ons
304+
305+
* - ``admin.auditlog.read``
306+
- View audit log configuration and read audit log in |tcm|
307+
308+
* - ``admin.auditlog.write``
309+
- Edit audit log configuration
310+
311+
* - ``admin.sessions.read``
312+
- View users' sessions
313+
314+
* - ``admin.sessions.write``
315+
- Revoke users' sessions
316+
317+
* - ``admin.ldap.read``
318+
- View LDAP configurations
319+
320+
* - ``admin.ldap.write``
321+
- Manage LDAP configurations
322+
323+
* - ``admin.passwordpolicy.read``
324+
- View password policy
325+
326+
* - ``admin.passwordpolicy.write``
327+
- Manage password policy
328+
329+
* - ``admin.devmode.toggle``
330+
- Toggle development mode
331+
332+
* - ``user.password.change``
333+
- Change own password
334+
335+
* - ``admin.secrets.read``
336+
- View users' secrets.
337+
338+
* - ``admin.secrets.write``
339+
- Manage users' secrets: add, edit, expire, block, delete.
340+
341+
.. _tcm_access_control_permissions_cluster:
342+
343+
Cluster permissions
344+
~~~~~~~~~~~~~~~~~~~
345+
346+
The following cluster permissions are available in |tcm|:
347+
348+
.. list-table::
349+
:widths: 35 65
350+
:header-rows: 1
351+
352+
* - Permission
353+
- Description
354+
355+
* - ``cluster.lowlevel.state.read``
356+
- Read low-level information from |tcm| storage
357+
358+
* - ``cluster.lowlevel.state.write``
359+
- Description
360+
361+
* - ``cluster.lowlevel.metrics.read``
362+
- Description
363+
364+
* - ``cluster.config.read``
365+
- View cluster configuration
366+
367+
* - ``cluster.config.write``
368+
- Manage cluster configuration
369+
370+
* - ``cluster.stateboard.read``
371+
- View cluster stateboard
372+
373+
* - ``cluster.explorer.read``
374+
- Read data from the cluster instances
375+
376+
* - ``cluster.explorer.write``
377+
- Write data to the cluster instances
378+
379+
* - ``cluster.explorer.call``
380+
- Execute stored functions on the cluster instances
381+
382+
* - ``cluster.explorer.eval``
383+
- Execute code on the cluster instances
384+
385+
* - ``cluster.space.read``
386+
- Read cluster data schema
387+
388+
* - ``cluster.space.write``
389+
- Modify cluster data schema

0 commit comments

Comments
 (0)