55 lines
3.6 KiB
Text
55 lines
3.6 KiB
Text
|
|
=== OTP Policies
|
|
|
|
{{book.project.name}} has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password
|
|
generator. Click on the `Authentication` left menu item and go to the `OTP Policy` tab.
|
|
|
|
.OTP Policy
|
|
image:../../{{book.images}}/otp-policy.png[]
|
|
|
|
Any policies you set here will be used to validate one-time passwords. When configuring OTP, FreeOTP and Google Authenticator
|
|
can scan a QR code that is generated on the OTP set up page that {{book.project.name}} has. The bar code is also
|
|
generated from information configured on the `OTP Policy` tab.
|
|
|
|
==== TOTP vs. HOTP
|
|
|
|
There are two different algorithms to choose from for your OTP generators. Time Based (TOTP) and Counter Based (HOTP).
|
|
For TOTP, your token generator will hash the current time and a shared secret. The server validates the OTP by comparing
|
|
the all hashes within a certain window of time to the submitted value. So, TOTPs are valid only for a short window of time (usually 30 seconds).
|
|
For HOTP a shared counter is used instead of the current time. The server increments the counter with each successful OTP login. So, valid OTPs only
|
|
change after a successful login.
|
|
|
|
TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can
|
|
be valid for an indeterminate amount of time. HOTP is much more user friendly as the user won't have to hurry to enter in their
|
|
OTP before the time interval is up. With the way {{book.project.name}} has implemented TOTP this distinction becomes a little more
|
|
blurry. HOTP requires a database update every time the server wants to increment the counter. This can be a performance drain
|
|
on the authentication server when there is heavy load. So, to provide a more efficient alternative, TOTP does not remember passwords
|
|
used. This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval. For future
|
|
versions of {{book.project.name}} it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval.
|
|
|
|
==== TOTP Configuration Options
|
|
|
|
OTP Hash Algorithm::
|
|
Default is SHA1, more secure options are SHA256 and SHA512.
|
|
Number of Digits::
|
|
How many characters is the OTP? Short means more user friendly as it is less the user has to type. More means more security.
|
|
Look Ahead Window::
|
|
How many intervals ahead should the server try and match the hash? This exists so just in case the clock of the TOTP generator
|
|
or authentication server get out of sync. The default value of 1 is usually good enough. For example, if the time interval
|
|
for a new token is every 30 seconds, the default value of 1 means that it will only accept valid tokens in that 30 second window.
|
|
Each increment of this config value will increase the valid window by 30 seconds.
|
|
OTP Token Period::
|
|
Time interval in seconds a new TOTP will be generated by the token generator. And, the time window the server is matching a hash.
|
|
|
|
==== HOTP Configuration Options
|
|
|
|
OTP Hash Algorithm::
|
|
Default is SHA1, more secure options are SHA256 and SHA512.
|
|
Number of Digits::
|
|
How many characters is the OTP? Short means more user friendly as it is less the user has to type. More means more security.
|
|
Look Ahead Window::
|
|
How many counters ahead should the server try and match the hash? The default value is 1. This exists to cover the case
|
|
where the user's counter gets ahead of the server's. This can often happen as users often increment the counter
|
|
manually too many times by accident. This value really should be increased to a value of 10 or so.
|
|
Initial Counter::
|
|
What is the value of the initial counter?
|