diff --git a/SUMMARY.adoc b/SUMMARY.adoc index ae387c23da..3e1e9a1a21 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -30,6 +30,7 @@ .. link:topics/login-settings/remember-me.adoc[Remember Me] . link:topics/authentication.adoc[Authentication] .. link:topics/authentication/password-policies.adoc[Password Policies] + .. link:topics/authentication/otp-policies.adoc[OTP Policies] . link:topics/admin-permissions.adoc[Master Admin Access Control] . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control] . link:topics/client-registration.adoc[Client Registration] diff --git a/keycloak-images/otp-policy.png b/keycloak-images/otp-policy.png new file mode 100644 index 0000000000..d9d22eba72 Binary files /dev/null and b/keycloak-images/otp-policy.png differ diff --git a/rhsso-images/otp-policy.png b/rhsso-images/otp-policy.png new file mode 100644 index 0000000000..1fe2e9fd08 Binary files /dev/null and b/rhsso-images/otp-policy.png differ diff --git a/topics/authentication/otp-policies.adoc b/topics/authentication/otp-policies.adoc new file mode 100644 index 0000000000..c689f1d325 --- /dev/null +++ b/topics/authentication/otp-policies.adoc @@ -0,0 +1,57 @@ + +=== 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 got 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 in a bar 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) based. +For TOTP, your token generator will hash the current time and a share 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 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 implement 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 + +Hashing 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 + +Hashing 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 like a value of 10 or so. +Initial Counter:: + What is the value of the initial counter? + +