keycloak-scim/server_admin/topics/authentication/otp-policies.adoc

=== OTP Policies

{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:{project_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 {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
all the 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 {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 {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 during which the server will match a hash. Each time the interval passes, a new TOTP will be generated by the token generator.

==== 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?