otp.rdoc

doc/otp.rdoc
Last Update: 2023-10-09 15:48:54 -0700

Documentation for OTP Feature

The otp feature implements multifactor authentication via time-based one-time passwords (TOTP). It supports setting up TOTP authentication, logging in with TOTP authentication codes, and disabling TOTP authentication.

The otp feature requires the rotp and rqrcode gems.

Auth Value Methods

otp_already_setup_error_flash

The flash error to show if going to the OTP setup page when OTP is already setup.

otp_already_setup_redirect

Where to redirect if going to the OTP setup page when OTP has already been setup.

otp_auth_additional_form_tags

HTML fragment containing additional form tags to use on the OTP authentication form.

otp_auth_button

Text to use for button on OTP authentication form.

otp_auth_error_flash

The flash error to show if unable to authenticate via OTP.

otp_auth_failures_limit

The number of allowed OTP authentication failures before locking out.

otp_auth_form_footer

A footer to display at the bottom of the OTP authentication form.

otp_auth_label

The label for the OTP authentication code.

otp_auth_link_text

The text to use for the link from the multifactor auth page.

otp_auth_page_title

The page title to use on the OTP authentication form.

otp_auth_param

The parameter name for the OTP authentication code.

otp_auth_route

The route to the OTP authentication action. Defaults to otp-auth.

otp_class

The class to use for OTP authentication (default: ROTP::TOTP)

otp_digits

The number of digits to use in OTP authentication codes (rotp’s default is 6).

otp_disable_additional_form_tags

HTML fragment containing additional form tags to use on the form to disable OTP authentication.

otp_disable_button

The text to use for button on the form to disable OTP authentication.

otp_disable_error_flash

The flash error to show if unable to disable OTP authentication.

otp_disable_link_text

The text to use for the disable link from the multifactor manage page.

otp_disable_notice_flash

The flash notice to show after disabling OTP authentication.

otp_disable_page_title

The page title to use on the OTP disable form.

otp_disable_redirect

Where to redirect after disabling OTP authentication.

otp_disable_route

The route to the OTP disable action. Defaults to otp-disable.

otp_drift

The number of seconds the client and server are allowed to drift apart. The default is 30. Can be set to nil to not allow drift.

otp_interval

The number of seconds in which to rotate TOTP auth codes (rotp’s default is 30).

otp_invalid_auth_code_message

The error message to show when an invalid OTP authentication code is used.

otp_invalid_secret_message

The error message to show when an invalid OTP secret is submitted during OTP setup.

otp_issuer

The issuer to use in the OTP provisioning URL. Defaults to domain.

otp_keys_column

The column in the otp_keys_table containing the OTP secret.

otp_keys_failures_column

The column in the otp_keys_table containing the number of OTP authentication failures.

otp_keys_id_column

The column in the otp_keys_table containing the account id.

otp_keys_last_use_column

The column in otp_keys_table containing the last authentication timestamp.

otp_keys_table

The table name containing the OTP secrets.

otp_keys_use_hmac?

Whether to use HMACs for OTP keys. Defaults to whether hmac_secret has been set. Should be set to false if adding hmac_secret to Rodauth where the otp feature is already in use, as otherwise it will render existing OTP keys invalid.

otp_lockout_error_flash

The flash error show show when OTP authentication has been locked out due to numerous authentication failures.

otp_lockout_redirect

Where to redirect if going to OTP authentication page and OTP authentication has been locked out.

otp_provisioning_uri_label

The label used when displaying the OTP provisioning URI during OTP setup.

otp_secret_label

The label used when displaying the OTP secret during OTP setup.

otp_setup_additional_form_tags

HTML fragment containing additional form tags when setting up OTP authentication.

otp_setup_button

Text for the button when setting up OTP authentication.

otp_setup_error_flash

The flash error to show if OTP authentication setup was not successful.

otp_setup_link_text

The text to use for the setup link from the multifactor manage page.

otp_setup_notice_flash

The flash notice to show if OTP authentication setup was successful.

otp_setup_page_title

The page title to use on the form to setup OTP authentication.

otp_setup_param

The parameter name used for the OTP secret when setting up OTP authentication.

otp_setup_raw_param

The parameter name used for the raw OTP secret when setting up OTP authentication, when otp_keys_use_hmac? is true.

otp_setup_redirect

Where to redirect after sucessful OTP authentication setup.

otp_setup_route

The route to the OTP setup action. Defaults to otp-setup.

Auth Methods

after_otp_authentication_failure

Run arbitrary code after OTP authentication failure.

after_otp_disable

Run arbitrary code after OTP authentication has been disabled.

after_otp_setup

Run arbitrary code after OTP authentication has been setup.

before_otp_auth_route

Run arbitrary code before handling an OTP authentication route.

before_otp_authentication

Run arbitrary code before OTP authentication.

before_otp_disable

Run arbitrary code before OTP authentication disabling.

before_otp_disable_route

Run arbitrary code before handling an OTP authentication disable route.

before_otp_setup

Run arbitrary code before OTP authentication setup.

before_otp_setup_route

Run arbitrary code before handling an OTP authentication setup route.

otp

The object used for verifying OTP authentication attempts.

otp_add_key(secret)

Add an OTP key for the current account with the given secret.

otp_auth_view

The HTML to use for the OTP authentication form.

otp_available?

Whether OTP authentication is ready for use.

otp_disable_response

Return a response after successfully disabling OTP . By default, redirects to otp_disable_redirect.

otp_disable_view

The HTML to use for the OTP disable form.

otp_exists?

Whether the current account has setup OTP.

otp_key

The stored OTP secret for the account.

otp_last_use

The last time OTP authentication was successful for the account.

otp_locked_out?

Whether the current account has been locked out of OTP authentication.

otp_new_secret

A new secret to use when setting up OTP.

otp_provisioning_name

The provisioning name to use during OTP setup, defaults to the account’s email.

otp_provisioning_uri

The provisioning URI displayed during OTP setup.

otp_qr_code

The QR code containing the otp_provisioning_uri, by default an SVG image.

otp_record_authentication_failure

Record an OTP authentication failure.

otp_remove

Removes all stored OTP data for the current account.

otp_remove_auth_failures

Removes OTP authentication failures for the current account, used after successful multifactor authentication.

otp_setup_response

Return a response after successful OTP setup. By default, redirects to otp_setup_redirect.

otp_setup_view

The HTML to use for the form to setup OTP authentication.

otp_tmp_key(secret)

Set the secret to use for the temporary OTP key, during OTP setup.

otp_update_last_use

Update the last time OTP authentication was successful for the account. Return true if the authentication should be allowed, or false if it should not be allowed because the last authentication was too recent and indicates the possible reuse of a TOTP authentication code.

otp_valid_code_for_old_secret

Called when valid OTP authentication is performed using hmac_old_secret. This indicates the OTP needs to be rotated before support for the previous hmac secret value is removed. You can use this to track users who need their OTP rotated, and take appropriate action.

otp_valid_code?(auth_code)

Whether the given code is the currently valid OTP auth code for the account.

otp_valid_key?(secret)

Whether the given secret is a valid OTP secret.