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

=== One Time Password (OTP) policies

{project_name} has several policies for setting up a FreeOTP or Google Authenticator One-Time Password generator.

.Procedure

. Click *Authentication* in the menu.
. Click the *Policy* tab.
. Click the *OTP Policy* tab.

.Otp Policy
image:images/otp-policy.png[OTP Policy]

{project_name} generates a QR code on the OTP set-up page, based on information configured in the *OTP Policy* tab. FreeOTP and Google Authenticator scan the QR code when configuring OTP.

==== Time-based or counter-based one time passwords

The algorithms available in {project_name} for your OTP generators are time-based and counter-based.

With Time-Based One Time Passwords (TOTP), the token generator will hash the current time and a shared secret.  The server validates the OTP by comparing the hashes within a window of time to the submitted value.  TOTPs are valid for a short window of time.

With Counter-Based One Time Passwords (HOTP), {project_name} uses a shared counter rather than the current time. The {project_name} server increments the counter with each successful OTP login. Valid OTPs change after a successful login. 

TOTP is more secure than HOTP because the matchable OTP is valid for a short window of time, while the OTP for HOTP is valid for an indeterminate amount of time. HOTP is more user-friendly than TOTP because no time limit exists to enter the OTP.

HOTP requires a database update every time the server increments the counter. This update is a performance drain on the authentication server during heavy load. To increase efficiency,  TOTP does not remember passwords used, so there is no need to perform database updates. The drawback is that it is possible to re-use TOTPs in the valid time interval. 

==== TOTP configuration options

===== OTP hash algorithm

The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512.

===== Number of digits

The length of the OTP.  Short OTP's are user-friendly, easier to type, and easier to remember. Longer OTP's are more secure than shorter OTP's.

===== Look around window

The number of intervals the server attempts to match the hash. This option is present in {project_name} if the clock of the TOTP generator or authentication server becomes out-of-sync. The default value of 1 is adequate. For example, if the time interval for a token is 30 seconds, the default value of 1 means it will accept valid tokens in the 90-second window (time interval 30 seconds + look ahead 30 seconds + look behind 30 seconds). Every increment of this value increases the valid window by 60 seconds (look ahead 30 seconds + look behind 30 seconds).

===== OTP token period

The time interval in seconds the server matches a hash. Each time the interval passes, the token generator generates a TOTP.

===== Reusable code

Determine whether OTP tokens can be reused in the authentication process or user needs to wait for the next token.
Users cannot reuse those tokens by default, and the administrator needs to explicitly specify that those tokens can be reused.

==== HOTP configuration options

===== OTP hash algorithm
  
The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512.

===== Number of digits

The length of the OTP.  Short OTPs are user-friendly, easier to type, and easier to remember. Longer OTPs are more secure than shorter OTPs.

===== Look around window
The number of previous and following intervals the server attempts to match the hash. This option is present in {project_name} if the clock of the TOTP generator or authentication server become out-of-sync. The default value of 1 is adequate. This option is present in {project_name} to cover when the user's counter gets ahead of the server.

===== Initial counter

The value of the initial counter.