Skip to content

Commit f58d72a

Browse files
committed
Authentication
1 parent 8bade30 commit f58d72a

File tree

1 file changed

+98
-0
lines changed

1 file changed

+98
-0
lines changed

doc/concepts/configuration/configuration_authentication.rst

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,101 @@
33
Authentication
44
==============
55

6+
.. _enterprise-auth-restrictions:
7+
8+
Authentication restrictions
9+
---------------------------
10+
11+
Tarantool Enterprise Edition provides the ability to apply additional restrictions for user authentication.
12+
For example, you can specify the minimum time between authentication attempts
13+
or turn off access for guest users.
14+
15+
In the configuration below, :ref:`security.auth_retries <configuration_reference_security_auth_retries>` is set to ``2``,
16+
which means that Tarantool lets a client try to authenticate with the same username three times.
17+
At the fourth attempt, the authentication delay configured with :ref:`security.auth_delay <configuration_reference_security_auth_delay>` is enforced.
18+
19+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml
20+
:language: yaml
21+
:start-at: security:
22+
:end-at: disable_guest
23+
:dedent:
24+
25+
The :ref:`disable_guest <configuration_reference_security_disable_guest>` option turns off access over remote connections from unauthenticated or :ref:`guest <authentication-passwords>` users.
26+
27+
28+
.. _enterprise-password-policy:
29+
30+
Password policy
31+
---------------
32+
33+
A password policy allows you to improve database security by enforcing the use
34+
of strong passwords, setting up a maximum password age, and so on.
35+
When you create a new user with
36+
:doc:`box.schema.user.create </reference/reference_lua/box_schema/user_create>`
37+
or update the password of an existing user with
38+
:doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`,
39+
the password is checked against the configured password policy settings.
40+
41+
In the example below, the following options are specified:
42+
43+
- :ref:`password_min_length <configuration_reference_security_password_min_length>` specifies that a password should be at least 10 characters.
44+
- :ref:`password_enforce_uppercase <configuration_reference_security_password_enforce_uppercase>`, :ref:`password_enforce_digits <configuration_reference_security_password_enforce_digits>`, and :ref:`password_enforce_specialchars <configuration_reference_security_password_enforce_specialchars>` specify that a password should contain uppercase letters, digits, and at least one special character.
45+
- :ref:`password_lifetime_days <configuration_reference_security_password_lifetime_days>` sets a maximum password age to 365 days.
46+
- :ref:`password_history_length <configuration_reference_security_password_history_length>` specifies that a new password should differ from the last three passwords.
47+
48+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml
49+
:language: yaml
50+
:start-at: security:
51+
:end-at: password_history_length
52+
:dedent:
53+
54+
55+
56+
57+
.. _enterprise-authentication-protocol:
58+
59+
Authentication protocol
60+
-----------------------
61+
62+
By default, Tarantool uses the
63+
`CHAP <https://en.wikipedia.org/wiki/Challenge-Handshake_Authentication_Protocol>`_
64+
protocol to authenticate users and applies ``SHA-1`` hashing to
65+
:ref:`passwords <authentication-passwords>`.
66+
Note that CHAP stores password hashes in the ``_user`` space unsalted.
67+
If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table <https://en.wikipedia.org/wiki/Rainbow_table>`_.
68+
69+
In the Enterprise Edition, you can enable
70+
`PAP <https://en.wikipedia.org/wiki/Password_Authentication_Protocol>`_ authentication
71+
with the ``SHA256`` hashing algorithm.
72+
For PAP, a password is salted with a user-unique salt before saving it in the database,
73+
which keeps the database protected from cracking using a rainbow table.
74+
75+
To enable PAP, specify the :ref:`security.auth_type <configuration_reference_security_auth_type>` option as follows:
76+
77+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml
78+
:language: yaml
79+
:start-at: security:
80+
:end-at: pap-sha256
81+
:dedent:
82+
83+
For new users, the :doc:`box.schema.user.create </reference/reference_lua/box_schema/user_create>` method generates authentication data using ``PAP-SHA256``.
84+
For existing users, you need to reset a password using
85+
:doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`
86+
to use the new authentication protocol.
87+
88+
.. warning::
89+
90+
Given that ``PAP`` transmits a password as plain text,
91+
Tarantool requires configuring :ref:`SSL/TLS <configuration_connections_ssl>`
92+
for a connection.
93+
94+
The examples below show how to specify the authentication protocol using the ``auth_type`` parameter when connecting to an instance using :doc:`net.box </reference/reference_lua/net_box>`:
95+
96+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua
97+
:language: lua
98+
:start-at: local connection
99+
:end-before: return connection
100+
:dedent:
101+
102+
If the authentication protocol isn't specified explicitly on the client side,
103+
the client uses the protocol configured on the server via ``security.auth_type``.

0 commit comments

Comments
 (0)