rodauth 1.23.0 → 2.4.0

data/doc/password_grace_period.rdoc

@@ -1,10 +1,24 @@
 = Documentation for Password Grace Period Feature
 
 The password grace period feature keeps track of the last time the
-user entered their password, and doesn't require they reenter their
+user entered their password in the session, and doesn't require they reenter their
 password for account modifications if they recently entered it correctly.
 
+If you would like to provide extra security before certain routes, you can use
+the confirm password feature to require users to reenter their password if they
+haven't entered it recently:
+
+  rodauth.require_password_authentication
+
+By default, this does not redirect if the session has been authenticated via
+password, but with the password_grace_period feature, it also redirects if the
+password has not been entered recently.
+
 == Auth Value Methods
 
-password_grace_period :: The number of seconds after a password entry until password reentry is required, 300 by default (5 minutes).
 last_password_entry_session_key :: The session key in which to store the last password entry time.
+password_grace_period :: The number of seconds after a password entry until password reentry is required, 300 by default (5 minutes).
+
+== Auth Methods
+
+password_recently_entered? :: Whether the password has last been entered within the grace period.

data/doc/password_pepper.rdoc

@@ -0,0 +1,44 @@
+= Documentation for Password Pepper Feature
+
+The password pepper feature appends a specified secret string to passwords
+before they are hashed. This way, if the password hashes get compromised, an
+attacker cannot use them to crack the passwords without also knowing the
+pepper.
+
+In the configuration block set the +password_pepper+ with your secret string.
+It's recommended for the password pepper to be at last 32 characters long and
+randomly generated.
+
+  password_pepper "<long secret key>"
+
+If your database already contains password hashes that were created without a
+password pepper, these will get automatically updated with a password pepper
+next time the user successfully enters their password.
+
+You can rotate the password pepper as well, just make sure to add the previous
+pepper to the +previous_password_peppers+ array. Password hashes using the old
+pepper will get automatically updated on the next successful password match.
+
+  password_pepper "new pepper"
+  previous_password_peppers ["old pepper", ""] 
+
+The empty string above ensures password hashes without pepper are handled as
+well.
+
+Note that each entry in +previous_password_peppers+ will multiply the amount of
+possible password checks during login, at least for incorrect passwords.
+
+Additionally, when using this feature with the disallow_password_reuse feature,
+the number of passwords checked when changing or resetting a password will be
+
+  (previous_password_peppers.length + 1) * previous_passwords_to_check
+
+So if you have 2 entries in +previous_password_peppers+, using the default
+value of 6 for +previous_passwords_to_check+, every time a password
+is changed, there will be 18 password checks done, which will be quite slow.
+
+== Auth Value Methods
+
+password_pepper :: The secret string appended to passwords before they are hashed.
+previous_password_peppers :: An array of password peppers that will be tried on an unsuccessful password match. Defaults to <tt>[""]</tt>, which allows introducing this feature with existing passwords.
+password_pepper_update? :: Whether to update password hashes that use a pepper from +previous_password_peppers+ with a new pepper. Defaults to +true+.

data/doc/recovery_codes.rdoc

@@ -1,8 +1,8 @@
 = Documentation for Recovery Codes Feature
 
-The recovery codes feature allows 2nd factor authentication via single use recovery
-codes.  It is usually used as a backup if OTP authentication is not available or
-has been locked out, but can be used by itself or as a backup to SMS codes.  It allows
+The recovery codes feature allows multifactor authentication via single use recovery
+codes.  It is usually used as a backup if other multifactor authentication methods are
+not available or have been locked out, but can be used by itself.  It allows
 users to view authentication recovery codes as well as regenerate recovery codes.
 
 Access to recovery codes is limited to authenticated sessions only, so users should
@@ -11,25 +11,31 @@ of them being required due to a missing / lost device.
 
 == Auth Value Methods
 
-add_recovery_codes_button :: Text to use for button on form to add recovery codes.
+add_recovery_codes_redirect :: Where to redirect to add recovery codes if recovery codes are the primary multifactor authentication and have not been setup yet.
+add_recovery_codes_button :: Text to use for button on the form to add recovery codes.
 add_recovery_codes_error_flash :: The flash error to show when adding recovery codes.
-add_recovery_codes_heading :: Text to use for heading above form to add recovery codes.
+add_recovery_codes_heading :: Text to use for heading above the form to add recovery codes.
+add_recovery_codes_page_title :: The page title to use on the add recovery codes form.
 add_recovery_codes_param :: The parameter name to use for adding recovery codes.
-add_recovery_auth_redirect :: Where to redirect to add recovery codes if recovery codes are the primary 2nd factor and have not been setup yet.
+auto_add_recovery_codes? :: Whether to automatically add recovery codes (or any missing recovery codes) when another multifactor authentication type is enabled (false by default).
 invalid_recovery_code_error_flash :: The flash error to show when an invalid recovery code is used.
 invalid_recovery_code_message :: The error message to show when an invalid recovery code is used.
 recovery_auth_additional_form_tags :: HTML fragment containing additional form tags when authenticating via a recovery code.
 recovery_auth_button :: The text to use for the button when authenticating via a recovery code.
+recovery_auth_link_text :: The text to use for the link from the multifactor auth page.
+recovery_auth_page_title :: The page title to use on the form to authenticate via a recovery code.
 recovery_auth_redirect :: Where to redirect after authenticating via an recovery code.
 recovery_auth_route :: The route to the recovery code authentication action.  Defaults to +recovery-auth+.
 recovery_codes_added_notice_flash :: The flash notice to show when recovery codes were added.
 recovery_codes_additional_form_tags :: HTML fragment containing additional form tags when adding recovery codes.
-recovery_codes_column :: The column in the recovery_codes_table containing the recovery code.
-recovery_codes_id_column :: The column in the recovery_codes_table containing the account id.
+recovery_codes_column :: The column in the +recovery_codes_table+ containing the recovery code.
+recovery_codes_id_column :: The column in the +recovery_codes_table+ containing the account id.
 recovery_codes_label :: The label for recovery codes.
-recovery_codes_limit :: The number of recovery codes to allow.
+recovery_codes_limit :: The number of recovery codes to setup.
+recovery_codes_link_text :: The text to use for the setup link from the multifactor manage page.
+recovery_codes_page_title :: The page title to use on the form to view recovery codes.
 recovery_codes_param :: The parameter name for the recovery code.
-recovery_codes_primary? :: Whether recovery codes are the primary second factor, true by default if neither the otp or sms_codes features are enabled.
+recovery_codes_primary? :: Whether recovery codes are a primary multifactor authentication type.  If not, they cannot be setup unless multifactor authentication is already setup.
 recovery_codes_route :: The route to the view recovery codes action. Defaults to +recovery-codes+.
 recovery_codes_table :: The table storing the recovery codes.
 view_recovery_codes_button :: Text for the button to view recovery codes.
@@ -41,8 +47,8 @@ add_recovery_code :: Add a recovery code for the given account.
 add_recovery_codes_view :: The HTML to use for the add recovery codes form.
 after_add_recovery_codes :: Run arbitrary code after adding recovery codes.
 before_add_recovery_codes :: Run arbitrary code before adding recovery codes.
-before_recovery_auth :: Run arbitrary code before recovery authentication.
-before_recovery_auth_route :: Run arbitrary code before handling recovery authentication route.
+before_recovery_auth :: Run arbitrary code before recovery code authentication.
+before_recovery_auth_route :: Run arbitrary code before handling recovery code authentication route.
 before_recovery_codes_route :: Run arbitrary code before handling view/add recovery codes route.
 before_view_recovery_codes :: Run arbitrary code before viewing recovery codes.
 can_add_recovery_codes? :: Whether the current account can add more recovery codes.

data/doc/release_notes/2.0.0.txt

@@ -0,0 +1,361 @@
+= New Features
+
+* A webauthn feature has been added, allowing multifactor
+  authentication using WebAuthn.  It allows for registering multiple
+  WebAuthn authenticators per account, authenticating using
+  WebAuthn, and removing WebAuthn authenticators.  This feature
+  depends on the webauthn gem.
+
+  WebAuthn in browsers requires javascript to work, but Rodauth's
+  approach has the javascript set hidden form inputs and then use a
+  standard form submission, making it easy to test applications
+  using WebAuthn without a full browser, as long as a software
+  WebAuthn authenticator can be used (the webauthn gem provides
+  such an authenticator).
+
+* A webauthn_login feature has been added, allowing passwordless
+  logins using WebAuthn.
+
+* A webauthn_verify_account feature has been added, which requires
+  setting up a WebAuthn authenticator during account verification.
+  This allows for setups where WebAuthn is the sole method of
+  authentication.
+
+* An active_sessions feature has been added, which disallows
+  session reuse after logout, and allows for a global logout of all
+  sessions for the account.  It also supports inactivity and
+  lifetime deadlines for sessions.  This also integrates with the
+  jwt_refresh feature to disable JWT access token usage after
+  logout.
+
+* An audit_logging feature has been added, which logs Rodauth
+  actions to a database table.  This hooks into all of Rodauth's
+  after_* hooks, and will implement audit logging for all
+  features that use such hooks.
+
+* The confirm_password feature can now operate as multifactor
+  authentication if the user has a password but was originally
+  authenticated using the webauthn_login feature.
+
+* The multifactor authentication support now better handles
+  multiple multifactor authentication methods.  When setting up
+  multifactor authentication, a page is provided linking to all
+  enabled multifactor authentication options.  When authenticating
+  via an additional factor, a page is provided linking to all
+  multifactor authentication options that have been setup and are
+  available for use.  There is also a page to disable all multifactor
+  authentication methods that have been setup, and revert to single
+  factor authentication.
+
+  To provide a better user experience, if there would only be a
+  single link on the pages to setup multifactor authentication
+  or authenticate with an additional factor, the user is redirected
+  directly to the appropriate page.
+
+* A translate configuration method has been added.  This is called
+  with a translation key and default value for the translation, and
+  allows for internationalizing Rodauth.  All translatable strings
+  are passed through this method, including flash messages, page
+  titles, button text, field error messages, and link texts.
+
+* login_return_to_requested_location? and
+  two_factor_auth_return_to_requested_location? configuration methods
+  have been added.  With these methods set to true, if
+  rodauth.require_login needs to redirect, it will store the current
+  page, and after logging in, the user will be redirected back to the
+  page.  Likewise, if rodauth.require_two_factor_authenticated needs
+  to redirect, it will store the current page, and after multifactor
+  authentication, the user will be redirected back to the page.
+
+* domain and base_url configuration methods have been added and it is
+  recommended that applications use them if they can be reached with
+  arbitrary Host headers.  If not set, Rodauth will use information
+  from the request, which can be provided by an attacker.
+
+* The *_url and *_path methods now accept an optional hash of query
+  parameters to use.
+
+* Many Rodauth forms will now use appropriate autocomplete and
+  inputmode attributes on form inputs.  You can modify the behavior
+  using the following configuration methods:
+  
+  * autocomplete_for_field?
+  * inputmode_for_field?
+  * mark_input_fields_with_autocomplete?
+  * mark_input_fields_with_inputmode?
+
+* An sms_phone_input_type configuration method has been added and
+  now defaults to tel.  Previous, the SMS phone input used a text
+  type.
+
+* rodauth.require_password_authentication has been added to the
+  confirm_password_feature, which will redirect to the login page
+  if not logged in, and will redirect to the confirm password page
+  if the user was logged in without typing in a password.  If the
+  password_grace_period feature is used, this also redirects if
+  the password has not been entered recently.
+
+* rodauth.authenticated_by has been added, which is an array of
+  strings for all methods by which the current session has been
+  authenticated, or nil if the session has not been authenticated.
+
+* rodauth.possible_authentication_methods has been added, which is
+  an array of strings for all methods by which the current session
+  could be authenticated.
+
+* rodauth.autologin_type now returns the type of autologin used if
+  authenticated using autologin.
+
+* All *_view configuration methods now have *_page_title
+  configuration methods for setting custom page titles.
+
+= Other Improvements
+
+* The templates Rodauth uses by default are now compatible with
+  Bootstrap 4, and compatibility with Bootstrap 3 (which Rodauth
+  previously targeted) has been improved.
+
+* When requesting a password reset, if the user provides an invalid
+  login, an input for the login is now displayed so the problem
+  can be corrected.
+
+* When setting up an additional multifactor authentication method,
+  Rodauth no longer overrides which multifactor authentication method
+  was used to authenticate the current session.
+
+* When disabling a multifactor authentication method that was not
+  used to authenticate the current session, the session remains
+  multifactor authenticated.
+
+* When multiple multifactor authentication methods are setup for
+  an account, disabling a multifactor authentication method will not
+  mark the session as not having multifactor authentication enabled.
+
+* When disabling OTP authentication, future calls to
+  rodauth.otp_exists? will return false instead of true.
+
+* Recovery codes are no longer generated automatically when OTP or
+  SMS authentication is setup.  There is no point generating codes
+  that the user has not yet viewed, and generating them automatically
+  will disable automatic redirections in the cases where only one
+  multifactor authentication method is setup.  This can be turned
+  back on using the auto_add_recovery_codes? configuration method.
+
+* The OTP setup page now displays better on phones and other devices
+  with small viewports.
+
+* Links and alternative login forms shown on the login page are
+  now in a specific order and not based on the order in which
+  features were enabled.
+
+* The link to resend the verify account email is not shown on the
+  multi-phase login page after the login has been entered if the
+  account has already been verified.
+
+* The modifications_require_password? configuration method now
+  defaults to false for accounts that do not have a password.
+
+* Multifactor authentication is no longer allowed using the same
+  factor type as used for initial authentication.  Previously,
+  no multifactor authentication type could be used for initial
+  authentication, so this wasn't an issue.
+
+* The verify login change page no longer calls already_logged_in
+  if the session is already logged in.  This method is documented
+  to only be called on pages that expect not to be already logged
+  in, and it's common to access the verify login change page
+  while being logged in, since you need to be logged in to go to
+  the change login page.  The default behavior of already_logged_in
+  is to do nothing, so this only affects you if you have used the
+  already_logged_in configuration method.
+
+* If using the email_auth and verify_account_grace_period features
+  together, do not show email authentication as an option for
+  unverified accounts during the grace period.
+
+* In the lockout feature, generate the unlock account key before
+  calling send_unlock_account_email, similar to how key generation
+  happens in other features that send email.  This makes it easier
+  to override the method.
+
+* Various method visibility issues have been fixed, so that
+  enabling any feature that ships with Rodauth will not affect
+  visibility of methods for features already enabled.
+
+* All Rodauth configuration methods (over 1000) are now documented.
+
+= Backwards Compatibility
+
+* The verify_change_login feature has been removed.  Users should
+  switch to the verify_login_change feature, which verifies the
+  new login works correctly before switching the login.
+
+* For CSRF protection, Roda's route_csrf plugin is now used by
+  default instead of rack_csrf.  This supports request specific
+  CSRF tokens by default.  The :csrf=>:rack_csrf plugin option
+  can be used to continue using rack_csrf.
+
+  Roda's route_csrf allows for per-route checking of the CSRF token,
+  and support for that is enabled for all Rodauth routes.  However,
+  if you were using Rodauth without explicitly loading rack_csrf,
+  these changes could remove CSRF support from your application.
+  You should probably load Roda's route_csrf plugin explicitly and
+  use it in your Roda routing tree if you want CSRF protection for
+  non-Rodauth routes.  You can use the new check_csrf_opts and
+  check_csrf_block to customize options to pass to check_csrf!, or
+  set check_csrf? false to disable calling check_csrf!.
+
+* Email rate limiting is now enabled by default in the lockout,
+  reset_password, and verify_account features.  This requires
+  adding a column to store the last email sent time to the
+  related tables, if the tables were created without one:
+
+    DB.add_column :account_password_reset_keys, :email_last_sent,
+      DateTime, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
+    DB.add_column :account_verification_keys, :email_last_sent,
+      DateTime, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
+    DB.add_column :account_lockouts, :email_last_sent, DateTime
+
+  Alternatively, you can set the appropriate configuration method
+  (e.g. verify_account_email_last_sent_column) to nil to disable
+  rate limiting.
+
+* The http_basic_auth feature has been changed significantly.
+  You should now call rodauth.http_basic_auth in the routing tree
+  to load authentication information from the Authorization
+  request header, similar to how rodauth.load_memory works in the
+  remember feature.
+
+  The require_http_basic_auth configuration method has been renamed
+  to require_http_basic_auth?.  rodauth.require_http_basic_auth?
+  should now be used to check whether HTTP basic auth is required.
+  rodauth.require_http_basic_auth now requires that HTTP basic
+  auth is provided in the request.
+
+  To be more backwards compatible, if not already logged in,
+  rodauth.require_login will load HTTP basic auth information if
+  available, and will require HTTP basic auth if
+  require_http_basic_auth? is configured.
+
+* If using the Bootstrap 3/4 compatibility, the forms used are
+  now standard (vertical) Bootstrap forms.  Previously, they were
+  horizontal forms.
+
+* Most of the strings related to multifactor authentication have
+  been changed to refer to multifactor authentication instead of
+  two factor authentication, or changed to refer to a specific
+  multifactor authentication type (such as TOTP), as appropriate.
+
+* Periods at the end of some default flash messages have been
+  removed for consistency.
+
+* The remember feature no longer depends on the confirm_password
+  feature.  You must now enable confirm_password separately if you
+  want to use it.
+
+* Login confirmation is no longer required by default when
+  verifying accounts or verifying login changes.  In both cases,
+  entering an invalid login causes no problems.
+
+* The otp_drift configuration method now defaults to 30, to allow
+  30 seconds of drift.  The previous setting of nil generally
+  resulted in usability problems, especially without good clock
+  synchronization.
+
+* The json_response_custom_error_status? configuration method now
+  defaults to true, so that custom error statuses are now used by
+  default, instead of a generic 400 response.
+
+* The jwt_check_accept? configuration method now defaults to true,
+  so that the request Accept header is checked.
+
+* The verify_account_set_password? configuration method now defaults
+  to true, so that passwords will be set when verifying accounts
+  instead of when creating accounts.  This prevents issues when
+  an attacker creates an account with a password they know, if the
+  user with access to the email address verifies the account.
+
+* The mark_input_fields_as_required? configuration method now defaults
+  to true.  Most of rodauth's input fields are required, and this
+  provides a nicer experience.  However, it may cause accessibility
+  issues if screen readers do not handle invalid form submissions due
+  to missing required fields in an accessible manner.
+
+* The login_input_type configuration method now defaults to email if
+  login_column is :email (the default setting).  This can cause
+  accessibility issues if screen readers do not handle invalid form
+  submissions due to an invalid login field format in an accessible
+  manner.  It can also break installations that leave login_column
+  as :email but do not use email addresses for logins.
+
+* The json_response_success_key configuration method now defaults to
+  success, so success messages are included by default.  This can be
+  set back to nil to not include them.
+
+* The single_session and session_expiration plugin now use a
+  configurable error status code for JSON requests when the session
+  has expired, using inactive_session_error_status and
+  session_expiration_error_status configuration methods,
+  respectively.
+
+* If you are using the jwt_refresh feature and used the migration
+  previously recommended in the README, you should mark the account_id
+  field as NOT NULL and add an index:
+
+    DB.alter_table(:account_jwt_refresh_keys) do
+      set_column_not_null :account_id
+      add_index :account_id, :name=>:account_jwt_rk_account_id_idx
+    end
+
+* The otp authentication form no longer shows SMS or recovery code
+  information on failure.  The multifactor authentication page will
+  have links to SMS or recovery code authentication if they have been
+  setup, and will redirect or show the appropriate links to those
+  authentication methods if OTP authentication gets locked out.
+
+* Disabling OTP authentication no longer automatically disables SMS
+  authentication and recovery codes, and disabling SMS authentication
+  no longer disables recovery codes.  To disable all multifactor
+  authentication methods at once, the new multifactor authentication
+  disable page should be used.  If you want to revert to the previous
+  behavior of automatic disabling, override after_otp_disable to
+  disable SMS and recovery codes, and override after_sms_disable to
+  disable recovery codes.
+
+* HTML id attributes in the recovery_codes and remember features have
+  been modified to use - instead of _, for consistency with all other
+  Rodauth features.
+
+* Ruby 1.8 support has been dropped.  The minimum supported version is
+  now Ruby 1.9.2.  Support for versions of Ruby that are no longer
+  supported by ruby-core may be dropped in future minor releases if
+  keeping the support becomes a maintenance issue.
+
+* The following configuration methods have been replaced:
+
+  * create_account_link -> create_account_link_text
+  * reset_password_request_link -> reset_password_request_link_text
+  * verify_account_resend_link -> verify_account_resend_link_text
+
+  The new methods take only the text of the link, the path to link
+  to can already be determined by Rodauth.
+
+* The following configuration methods have been removed:
+
+  * account_model
+  * attempt_to_create_unverified_account_notice_message
+  * attempt_to_login_to_unverified_account_notice_message
+  * before_otp_authentication_route
+  * clear_remembered_session_key
+  * no_matching_email_auth_key_message
+  * no_matching_reset_password_key_message
+  * no_matching_unlock_account_key_message
+  * no_matching_verify_account_key_message
+  * no_matching_verify_login_change_key_message
+  * remembered_session_key
+  * two_factor_session_key
+
+  Most of these methods were already deprecated.
+ 
+* Route blocks in external Rodauth features must now have an arity
+  of 1.