diff --git a/doc/tooling/tcm/index.rst b/doc/tooling/tcm/index.rst index 08983d482..01a48ed25 100644 --- a/doc/tooling/tcm/index.rst +++ b/doc/tooling/tcm/index.rst @@ -41,7 +41,7 @@ to read data. LDAP authorization is supported as well. tcm_cluster_management/index tcm_cluster_data_access tcm_cluster_migrations - tcm_access_control + tcm_access_control/index tcm_audit_log tcm_configuration tcm_backend_store diff --git a/doc/tooling/tcm/tcm_access_control/index.rst b/doc/tooling/tcm/tcm_access_control/index.rst new file mode 100644 index 000000000..69a2cd33d --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/index.rst @@ -0,0 +1,31 @@ +.. _tcm_access_control: + +Access control +============== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides means for managing user and client applications access +to its own functions and connected clusters: + +- :ref:`Local role-based access model ` allow flexible + access management with user accounts created inside |tcm|. +- :ref:`LDAP authentication ` enable authentication with an external + directory server. +- :ref:`Access control list ` enables fine-grained access + to entities stored on connected clusters. +- :ref:`API tokens ` enable integration with third-party applications. +- :ref:`Sessions management ` allow administrators to view and + revoke user sessions. + + +.. toctree:: + :maxdepth: 1 + + tcm_access_control_rbac + tcm_ldap_auth + tcm_access_control_list + tcm_api_tokens + tcm_sessions \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst b/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst new file mode 100644 index 000000000..81d45ac7d --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst @@ -0,0 +1,77 @@ +.. _tcm_access_control_list: + +Access control list +=================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| *access control list* (*ACL*) determines user access to particular data +and functions stored in clusters. You can use it to allow or deny access to specific +stored objects one by one. + +Each ACL entry specifies privileges that a |tcm| user has on a particular +space or a function. There are three access privileges that can be granted in the ACL: +read, write, and execute (for stored functions only). The privileges work as follows: + +- Spaces: + + - ``Read``: the user sees the space and its tuples on the **Tuples** and **Explorer** pages + - ``Write``: the user can add new and edit existing tuples of the space + +- Functions: + + - ``Read``: the user sees the function on the **Functions** tab of the instance details page. + - ``Write``: the user can edit or delete the function + - ``Execute``: the user can call the function + +.. important:: + + User access to space data and stored functions is primarily defined by the + :ref:`cluster permissions ` ``cluster.space.data.*`` and ``cluster.func.*``. + ACL only increases the access control granularity to particular objects. + Make sure that users have these permissions before enabling ACL for them. + +.. _tcm_access_control_list_enable: + +Enabling ACL for a user +~~~~~~~~~~~~~~~~~~~~~~~ + +To granularly manage a user's access to particular objects in a cluster, enable +the use of ACL in the user profile: + +#. Go to **Users** and click **Edit** in the **Actions** menu of the corresponding table row. + +#. In the user's **Clusters** list, add a cluster on which you want to use ACL + or click the pencil icon if the cluster is already on the list. + +#. Select the **Use Access Control List (ACL)** checkbox and save changes. + +#. Repeat two previous steps for each cluster on which you want to use ACL for this user. + +#. Click **Update** to save the user account. + +If the user doesn't exist yet, you can do the same when creating it. + +.. important:: + + When ACL use is enabled for a user, this user loses access to all spaces and + functions of the selected cluster except the ones explicitly specified in the ACL. + +.. _tcm_access_control_list_manage: + +Managing ACL +------------ + +The tools for managing ACL are located on the **ACL** page. + +To add an ACL entry: + +#. Click **Add**. +#. Select a user to which you want to grant access. +#. Select a cluster that stores the target object: a space or a function. +#. Select the target object type and enter its name. +#. Select the privileges you want to grant. + +To delete an ACL entry, click **Delete** in the **Actions** menu of the corresponding table row. diff --git a/doc/tooling/tcm/tcm_access_control.rst b/doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst similarity index 72% rename from doc/tooling/tcm/tcm_access_control.rst rename to doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst index 373123fee..ca4507258 100644 --- a/doc/tooling/tcm/tcm_access_control.rst +++ b/doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst @@ -1,9 +1,9 @@ -.. _tcm_access_control: +.. _tcm_access_control_rbac: -Access control -============== +Role-based access control +========================= -.. include:: index.rst +.. include:: ../index.rst :start-after: ee_note_tcm_start :end-before: ee_note_tcm_end @@ -57,7 +57,7 @@ There are two types of permissions in |tcm|: *administrative* and *cluster* perm Cluster permissions are assigned to users individually when creating or editing them. For a fine-grained control over user access to particular spaces and functions stored - in clusters, there is the :ref:`access control list `. + in clusters, there is the :ref:`access control list `. Permissions are predefined in |tcm|, there is no way to change, add, or delete them. The complete lists of administrative and cluster permissions in |tcm| are provided @@ -259,145 +259,6 @@ There are the following password policy settings: - **Digits (0-9)** - **Symbols (such as !@#$%^&\*()_+№"':,.;=][{}`?>/.)** -.. _tcm_access_control_acl: - -Access control list -------------------- - -|tcm|'s *access control list* (*ACL*) determines user access to particular data -and functions stored in clusters. You can use it to allow or deny access to specific -stored objects one by one. - -Each ACL entry specifies privileges that a |tcm| user has on a particular -space or a function. There are three access privileges that can be granted in the ACL: -read, write, and execute (for stored functions only). The privileges work as follows: - -- Spaces: - - - ``Read``: the user sees the space and its tuples on the **Tuples** and **Explorer** pages - - ``Write``: the user can add new and edit existing tuples of the space - -- Functions: - - - ``Read``: the user sees the function on the **Functions** tab of the instance details page. - - ``Write``: the user can edit or delete the function - - ``Execute``: the user can call the function - -.. important:: - - User access to space data and stored functions is primarily defined by the - :ref:`cluster permissions ` ``cluster.space.data.*`` and ``cluster.func.*``. - ACL only increases the access control granularity to particular objects. - Make sure that users have these permissions before enabling ACL for them. - -.. _tcm_access_control_acl_enable: - -Enabling ACL for a user -~~~~~~~~~~~~~~~~~~~~~~~ - -To granularly manage a user's access to particular objects in a cluster, enable -the use of ACL in the user profile: - -#. Go to **Users** and click **Edit** in the **Actions** menu of the corresponding table row. - -#. In the user's **Clusters** list, add a cluster on which you want to use ACL - or click the pencil icon if the cluster is already on the list. - -#. Select the **Use Access Control List (ACL)** checkbox and save changes. - -#. Repeat two previous steps for each cluster on which you want to use ACL for this user. - -#. Click **Update** to save the user account. - -If the user doesn't exist yet, you can do the same when creating it. - -.. important:: - - When ACL use is enabled for a user, this user loses access to all spaces and - functions of the selected cluster except the ones explicitly specified in the ACL. - -.. _tcm_access_control_acl_manage: - -Managing ACL -~~~~~~~~~~~~ - -The tools for managing ACL are located on the **ACL** page. - -To add an ACL entry: - -#. Click **Add**. -#. Select a user to which you want to grant access. -#. Select a cluster that stores the target object: a space or a function. -#. Select the target object type and enter its name. -#. Select the privileges you want to grant. - -To delete an ACL entry, click **Delete** in the **Actions** menu of the corresponding table row. - -.. _tcm_access_control_sessions: - -Sessions --------- - -Administrators can view and revoke user sessions in |tcm|. All active sessions -are listed on the **Sessions** page. To revoke a session, click **Revoke** in the -**Actions** menu of the corresponding table row. - -To revoke all sessions of a user, go to **Users** and click **Revoke all sessions** -in the **Actions** menu of the corresponding table row. - -.. _tcm_access_control_api_tokens: - -API tokens ----------- - -|tcm| uses the Bearer HTTP authentication scheme with *API tokens* to authenticate -external applications' requests to |tcm|. For example, these can be Prometheus -jobs that retrieve metrics of connected Tarantool clusters. - -The API tokens functionality is disabled by default. To enable it, set the -:ref:`feature.api-token ` configuration option to ``true``. - -.. code-block:: yaml - - feature: - api-token: true - -Each |tcm| API token belongs to the user that created it and has the same :ref:`access permissions `. -Thus, if a user has a permission to view a cluster's metrics in |tcm|, this user's -API tokens can be used to read this cluster's metrics with Prometheus. - -API tokens have expiration dates that are set during the token creation and cannot -be changed. - -.. _tcm_access_control_api_tokens_manage: - -Managing API tokens -~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Each user, including **Default Admin** and other administrators, can create only - their own tokens. There is no way to create a token for another user. - -To create a |tcm| API token: - -#. Open the user settings by clicking the user's name in the top-right corner. -#. Go to the **API tokens** tab and click **Add**. -#. Specify the token expiration date and an optional description and click **Add**. - -The created token is shown in a dialog. - -.. important:: - - An API token is shown only once after its creation. There is no way to view - it again after you close the dialog. Make sure to copy the token in a safe place. - -To delete an API token, click **Delete** in the actions menu of the corresponding -**API tokens** table row. - -Administrators can also view information about users' API tokens and delete them -on the **Secrets** page. To open a user's secrets, click **Secrets** in the **Actions** -menu of the corresponding **Users** table row. .. _tcm_access_control_permissions_ref: diff --git a/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst b/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst new file mode 100644 index 000000000..813dc9cb5 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst @@ -0,0 +1,57 @@ +.. _tcm_access_control_api_tokens: + +API tokens +========== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| uses the Bearer HTTP authentication scheme with *API tokens* to authenticate +external applications' requests to |tcm|. For example, these can be Prometheus +jobs that retrieve metrics of connected Tarantool clusters. + +The API tokens functionality is disabled by default. To enable it, set the +:ref:`feature.api-token ` configuration option to ``true``. + +.. code-block:: yaml + + feature: + api-token: true + +Each |tcm| API token belongs to the user that created it and has the same :ref:`access permissions `. +Thus, if a user has a permission to view a cluster's metrics in |tcm|, this user's +API tokens can be used to read this cluster's metrics with Prometheus. + +API tokens have expiration dates that are set during the token creation and cannot +be changed. + +.. _tcm_access_control_api_tokens_manage: + +Managing API tokens +------------------- + +.. note:: + + Each user, including **Default Admin** and other administrators, can create only + their own tokens. There is no way to create a token for another user. + +To create a |tcm| API token: + +#. Open the user settings by clicking the user's name in the top-right corner. +#. Go to the **API tokens** tab and click **Add**. +#. Specify the token expiration date and an optional description and click **Add**. + +The created token is shown in a dialog. + +.. important:: + + An API token is shown only once after its creation. There is no way to view + it again after you close the dialog. Make sure to copy the token in a safe place. + +To delete an API token, click **Delete** in the actions menu of the corresponding +**API tokens** table row. + +Administrators can also view information about users' API tokens and delete them +on the **Secrets** page. To open a user's secrets, click **Secrets** in the **Actions** +menu of the corresponding **Users** table row. \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst b/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst new file mode 100644 index 000000000..e60c22845 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst @@ -0,0 +1,175 @@ +.. _tcm_ldap_auth: + +LDAP authentication +=================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +In addition to its internal :ref:`role-based access control model `, +|tcm_full_name| can use an external LDAP (Lightweight Directory Access Protocol) +directory server for user authentication and authorization. + +When LDAP authentication is enabled, |tcm| uses a connected LDAP directory server +to authenticates users who submit the login form. |tcm| constructs requests to +the servers according to configuration parameters described on this page. Permissions +of LDAP users in |tcm| are defined by LDAP group mapping. + +Both LDAP and secure LDAPS (LDAP over TLS) protocols are supported. + +.. _tcm_ldap_auth_enable: + +Enabling LDAP authentication +---------------------------- + +To allow LDAP user authentication in |tcm|, enable the ``ldap`` authentication method +in the :ref:`security.auth ` configuration option before startup: + +- In the YAML |tcm| configuration: + + .. code-block:: yaml + + security: + auth: + - ldap + +- In the command line: + + .. code-block:: console + + $ tcm --security.auth="ldap" + +.. note:: + + If both authentication methods -- LDAP and local -- are enabled, |tcm| tries them + for each login attempt in the order they are specified in the configuration. + +.. _tcm_ldap_auth_config: + +LDAP configuration +------------------ + +To enable LDAP user access to |tcm|, create an *LDAP configuration* that connects +|tcm| to the LDAP server that stores the users. An LDAP configuration +defines how |tcm| connects to the server and queries user data. To create an LDAP +configuration, go to the **LDAP** page in the **Settings** group and click **Add**. + +To edit an LDAP configuration, click **Edit** in the **Actions** menu of the corresponding row. + +To delete an LDAP configuration, click **Delete** in the **Actions** menu of the corresponding row. + +.. _tcm_ldap_auth_config_general: + +General settings +~~~~~~~~~~~~~~~~ + +Define the general configuration settings: + +* **Enabled**. Defines if the configuration is used. Turn the toggle off to + stop using the configuration. + + .. note:: + + If there are several enabled LDAP configurations, |tcm| attempts to use them + for user authentication in the order they are created. + +* **Automatically add non-existent users**. By default, |tcm| automatically saves + LDAP user information to its :ref:`backend store ` + upon their first login. Turn the toggle off if you don't want to save users from this LDAP server. + +.. _tcm_ldap_auth_config_connect: + +LDAP server connection +~~~~~~~~~~~~~~~~~~~~~~ + +Enter the LDAP server connection parameters: + +* **Endpoints**. URLs of the LDAP server. Example: ``127.0.0.1:5056``. +* **Request timeout**. The timeout for |tcm| requests to the LDAP server, in seconds. +* **Enabled TLS**. If the server uses LDAPS, turn this toggle on and specify + TLS connection parameters, such as a certificate and a key file. + +.. _tcm_ldap_auth_config_query: + +LDAP queries +~~~~~~~~~~~~ + +To define how |tcm| queries the LDAP server for user authentication and authorization, +fill in the fields of the **Queries** step: + +- **Query user** and **Query password**. Credentials of the LDAP user on behalf + of which all LDAP queries are executed: a distinguished name (DN) and a password. + Example DN: + + .. code-block:: text + + cn=admin,cn=users,dc=tarantool,dc=io + +- **Base DN**. The DN of a directory that serves as a root for making all LDAP requests. + Example: ``dc=tarantool,dc=io``. +- **Username regex**. A regular expression that defines a username template for + this LDAP configuration. When a user enters their username on the login page, + |tcm| matches it against username regular expressions of all enabled LDAP + configurations and selects the one to use for this user authentication. + + Example: a regex to match employee email addresses within the specified domain. + + .. code-block:: text + + ^([\w\-\.]+)@tarantool.io$ + +- (Optional) **Template DN**. A template for building a DN to send in an authentication bind request. + Use the numbers in curly braces as placeholders to replace with username regex parts: + ``{0}``, ``{1}``, and so on. + + Example: + + .. code-block:: text + + cn={0},cn=users,dc=tarantool,dc=io + + When used with the **Username regex** shown above, it substitutes ``{0}`` with + the username part of the email address (before ``@``) entered into the login form. + For example, the username ``user1@tarantool.io`` forms the following DN for bind request: + + .. code-block:: text + + cn=user1,cn=users,dc=tarantool,dc=io + +- (Optional) **Template query**. A template for querying the LDAP server for the DN. This + way is used if **Template DN** is not provided. +- **Group query template**. A template for querying groups to which a user belongs + for authorization purposes. Learn more in :ref:`tcm_ldap_auth_config_permissions`. + Example: + + .. code-block:: text + + ``(&(objectCategory=person)(objectClass=user)(cn={0}))`` + + +.. _tcm_ldap_auth_config_permissions: + +LDAP user permissions +~~~~~~~~~~~~~~~~~~~~~ + +Permissions of LDAP users in |tcm| are defined by the groups to which they belong. +You can map |tcm| administrative and cluster :ref:`permissions ` +to LDAP groups on the **Groups** step of the configuration creation. + +To assign permissions to an LDAP group, click **Add group**. In the dialog that opens, +enter the group name, for example, ``CN=Admins,CN=Builtin,DC=tarantool,DC=io``. +Then, select administrative permission to grant to this group in the **Permissions** list. + +To grant cluster permissions, click **Add cluster**. Select a cluster and the cluster +permissions to grant to the group. Save the group. + +Each user has permissions of all LDAP groups to which they belong. + + +.. _tcm_ldap_auth_config_disable: + +Disabling LDAP configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To stop using an LDAP configuration, open its **Edit** page and turn off the **Enabled** toggle. \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst b/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst new file mode 100644 index 000000000..d8a585c36 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst @@ -0,0 +1,15 @@ +.. _tcm_access_control_sessions: + +Sessions +======== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| administrators can view and revoke user sessions in the web interface. +All active sessions are listed on the **Sessions** page. To revoke a session, click +**Revoke** in the **Actions** menu of the corresponding table row. + +To revoke all sessions of a |tcm| user, go to **Users** and click **Revoke all sessions** +in the **Actions** menu of the corresponding table row. diff --git a/doc/tooling/tcm/tcm_cluster_data_access.rst b/doc/tooling/tcm/tcm_cluster_data_access.rst index 5ec470023..c71ee0f6d 100644 --- a/doc/tooling/tcm/tcm_cluster_data_access.rst +++ b/doc/tooling/tcm/tcm_cluster_data_access.rst @@ -13,7 +13,7 @@ web interface. You can view, add, edit, and delete tuples from spaces. .. note:: A |TCM| user's access to specific clusters and spaces is determined by their - :ref:`cluster permissions ` and :ref:`access control list `. + :ref:`cluster permissions ` and :ref:`access control list `. Data access is implemented in |tcm| on a per-instance basis: you can access data stored on one cluster instance at a time. For sharded clusters that use the diff --git a/doc/tooling/tcm/tcm_configuration.rst b/doc/tooling/tcm/tcm_configuration.rst index d9627b993..f9929c1c0 100644 --- a/doc/tooling/tcm/tcm_configuration.rst +++ b/doc/tooling/tcm/tcm_configuration.rst @@ -13,6 +13,10 @@ Configuration This topic describes how to configure |tcm_full_name|. For the complete list of |tcm| configuration parameters, see the :ref:`TCM configuration reference `. +.. note:: + + To learn about Tarantool cluster configuration, see :ref:`configuration`. + Configuration structure ----------------------- diff --git a/doc/tooling/tcm/tcm_ui_overview.rst b/doc/tooling/tcm/tcm_ui_overview.rst index 2647e5133..b0dd7d0b5 100644 --- a/doc/tooling/tcm/tcm_ui_overview.rst +++ b/doc/tooling/tcm/tcm_ui_overview.rst @@ -267,7 +267,7 @@ The **ACL** page displays the |tcm| access control list. :width: 700 :alt: TCM ACL page -On this page, you can add and delete ACL entries. Learn more in :ref:`tcm_access_control_acl`. +On this page, you can add and delete ACL entries. Learn more in :ref:`tcm_access_control_list`. .. _tcm_ui_users: diff --git a/doc/tooling/tt_cli/replicaset.rst b/doc/tooling/tt_cli/replicaset.rst index 286c6c6ce..af803802f 100644 --- a/doc/tooling/tt_cli/replicaset.rst +++ b/doc/tooling/tt_cli/replicaset.rst @@ -251,7 +251,7 @@ To expel an instance from a Cartridge cluster: .. _tt-replicaset-vshard: vshard ------ +------ .. code-block:: console