Skip to content

Commit e73218e

Browse files
andreyaksenovandreyaksenov
committed
Add box.cfg settings: authentication
1 parent 4597ecd commit e73218e

File tree

2 files changed

+221
-0
lines changed

2 files changed

+221
-0
lines changed

‎doc/reference/configuration/cfg_authentication.rst

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
.. _cfg_authentication:
2+
3+
.. admonition:: Enterprise Edition
4+
:class: fact
5+
6+
Authentication features are supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
7+
8+
* :ref:`auth_delay <cfg_auth_delay>`
9+
* :ref:`auth_retries <cfg_auth_retries>`
10+
* :ref:`auth_type <cfg_auth_type>`
11+
* :ref:`disable_guest <cfg_disable_guest>`
12+
* :ref:`password_min_length <cfg_password_min_length>`
13+
* :ref:`password_enforce_uppercase <cfg_password_enforce_uppercase>`
14+
* :ref:`password_enforce_lowercase <cfg_password_enforce_lowercase>`
15+
* :ref:`password_enforce_digits <cfg_password_enforce_digits>`
16+
* :ref:`password_enforce_specialchars <cfg_password_enforce_specialchars>`
17+
* :ref:`password_lifetime_days <cfg_password_lifetime_days>`
18+
* :ref:`password_history_length <cfg_password_history_length>`
19+
20+
21+
.. _cfg_auth_delay:
22+
23+
.. confval:: auth_delay
24+
25+
Specifies a period of time (in seconds) that a specific user should wait
26+
for the next attempt after failed authentication.
27+
28+
With the configuration below, Tarantool refuses the authentication attempt if the previous
29+
attempt was less than 5 seconds ago.
30+
31+
.. code-block:: lua
32+
33+
box.cfg{ auth_delay = 5 }
34+
35+
36+
| Since version: 2.11
37+
| Type: number
38+
| Default: 0
39+
| Environment variable: TT_AUTH_DELAY
40+
| Dynamic: yes
41+
42+
.. _cfg_auth_retries:
43+
44+
.. confval:: auth_retries
45+
46+
Specify the maximum number of authentication retries allowed before ``auth_delay`` is enforced.
47+
The default value is 0, which means ``auth_delay`` is enforced after the first failed authentication attempt.
48+
49+
The retry counter is reset after ``auth_delay`` seconds since the first failed attempt.
50+
For example, if a client tries to authenticate fewer than ``auth_retries`` times within ``auth_delay`` seconds, no authentication delay is enforced.
51+
The retry counter is also reset after any successful authentication attempt.
52+
53+
| Since version: 3.0.0
54+
| Type: number
55+
| Default: 0
56+
| Environment variable: TT_AUTH_RETRIES
57+
| Dynamic: yes
58+
59+
60+
.. _cfg_auth_type:
61+
62+
.. confval:: auth_type
63+
64+
Specify an authentication protocol:
65+
66+
- 'chap-sha1': use the `CHAP <https://en.wikipedia.org/wiki/Challenge-Handshake_Authentication_Protocol>`_ protocol to authenticate users with ``SHA-1`` hashing applied to :ref:`passwords <authentication-passwords>`.
67+
- 'pap-sha256': use `PAP <https://en.wikipedia.org/wiki/Password_Authentication_Protocol>`_ authentication with the ``SHA256`` hashing algorithm.
68+
69+
For new users, the :doc:`box.schema.user.create </reference/reference_lua/box_schema/user_create>` method
70+
will generate authentication data using ``PAP-SHA256``.
71+
For existing users, you need to reset a password using
72+
:doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`
73+
to use the new authentication protocol.
74+
75+
| Since version: 2.11
76+
| Type: string
77+
| Default value: 'chap-sha1'
78+
| Environment variable: TT_AUTH_TYPE
79+
| Dynamic: yes
80+
81+
82+
.. _cfg_disable_guest:
83+
84+
.. confval:: disable_guest
85+
86+
If **true**, disables access over remote connections
87+
from unauthenticated or :ref:`guest access <authentication-passwords>` users.
88+
This option affects both
89+
:doc:`net.box </reference/reference_lua/net_box>` and
90+
:ref:`replication <replication-master_replica_bootstrap>` connections.
91+
92+
| Since version: 2.11
93+
| Type: boolean
94+
| Default: false
95+
| Environment variable: TT_DISABLE_GUEST
96+
| Dynamic: yes
97+
98+
.. _cfg_password_min_length:
99+
100+
.. confval:: password_min_length
101+
102+
Specifies the minimum number of characters for a password.
103+
104+
The following example shows how to set the minimum password length to 10.
105+
106+
.. code-block:: lua
107+
108+
box.cfg{ password_min_length = 10 }
109+
110+
| Since version: 2.11
111+
| Type: integer
112+
| Default: 0
113+
| Environment variable: TT_PASSWORD_MIN_LENGTH
114+
| Dynamic: yes
115+
116+
117+
.. _cfg_password_enforce_uppercase:
118+
119+
.. confval:: password_enforce_uppercase
120+
121+
If **true**, a password should contain uppercase letters (A-Z).
122+
123+
| Since version: 2.11
124+
| Type: boolean
125+
| Default: false
126+
| Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE
127+
| Dynamic: yes
128+
129+
130+
.. _cfg_password_enforce_lowercase:
131+
132+
.. confval:: password_enforce_lowercase
133+
134+
If **true**, a password should contain lowercase letters (a-z).
135+
136+
| Since version: 2.11
137+
| Type: boolean
138+
| Default: false
139+
| Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE
140+
| Dynamic: yes
141+
142+
143+
.. _cfg_password_enforce_digits:
144+
145+
.. confval:: password_enforce_digits
146+
147+
If **true**, a password should contain digits (0-9).
148+
149+
| Since version: 2.11
150+
| Type: boolean
151+
| Default: false
152+
| Environment variable: TT_PASSWORD_ENFORCE_DIGITS
153+
| Dynamic: yes
154+
155+
156+
.. _cfg_password_enforce_specialchars:
157+
158+
.. confval:: password_enforce_specialchars
159+
160+
If **true**, a password should contain at least one special character (such as ``&|?!@$``).
161+
162+
| Since version: 2.11
163+
| Type: boolean
164+
| Default: false
165+
| Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS
166+
| Dynamic: yes
167+
168+
169+
.. _cfg_password_lifetime_days:
170+
171+
.. confval:: password_lifetime_days
172+
173+
Specifies the maximum period of time (in days) a user can use the same password.
174+
When this period ends, a user gets the "Password expired" error on a login attempt.
175+
To restore access for such users, use :doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`.
176+
177+
.. note::
178+
179+
The default 0 value means that a password never expires.
180+
181+
The example below shows how to set a maximum password age to 365 days.
182+
183+
.. code-block:: lua
184+
185+
box.cfg{ password_lifetime_days = 365 }
186+
187+
| Since version: 2.11
188+
| Type: integer
189+
| Default: 0
190+
| Environment variable: TT_PASSWORD_LIFETIME_DAYS
191+
| Dynamic: yes
192+
193+
194+
.. _cfg_password_history_length:
195+
196+
.. confval:: password_history_length
197+
198+
Specifies the number of unique new user passwords before an old password can be reused.
199+
200+
In the example below, a new password should differ from the last three passwords.
201+
202+
.. code-block:: lua
203+
204+
box.cfg{ password_history_length = 3 }
205+
206+
| Since version: 2.11
207+
| Type: integer
208+
| Default: 0
209+
| Environment variable: TT_PASSWORD_HISTORY_LENGTH
210+
| Dynamic: yes
211+
212+
.. note::
213+
Tarantool uses the ``auth_history`` field in the
214+
:doc:`box.space._user </reference/reference_lua/box_space/_user>`
215+
system space to store user passwords.
216+

‎doc/reference/configuration/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,11 @@ Logging
6060

6161
.. include:: cfg_logging.rst
6262

63+
Authentication
64+
--------------
65+
66+
.. include:: cfg_authentication.rst
67+
6368
Flight recorder
6469
---------------
6570

0 commit comments

Comments
 (0)