rodauth 2.1.0 → 2.6.0

data/doc/guides/password_requirements.rdoc

@@ -0,0 +1,30 @@
+= Customize password requirements
+
+By default, Rodauth requires passwords to have at least 6 characters. You can
+modify the minimum length:
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account
+
+    # Require passwords to have at least 8 characters
+    password_minimum_length 8
+  end
+
+You can use the {disallow common passwords feature}[rdoc-ref:doc/disallow_common_passwords.rdoc]
+to prevent the usage of common passwords (the most common 10,000 by default).
+
+You can use additional complexity checks on passwords via the {password
+complexity feature}[rdoc-ref:doc/password_complexity.rdoc], though most of
+those complexity checks are no longer considered modern security best
+practices and are likely to decrease overall security.
+
+If you want complete control over whether passwords meet requirements, you
+can use the <tt>password_meets_requirements?</tt> configuration method.
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account
+
+    password_meets_requirements? do |password|
+      #true if password meets requirements, false otherwise
+    end
+  end

data/doc/guides/paths.rdoc

@@ -0,0 +1,36 @@
+= Change route path
+
+You can change the URL path of any Rodauth route by overriding the
+corresponding <tt>*_route</tt> method:
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account, :reset_password
+
+    # Change login route to "/signin"
+    login_route "signin"
+
+    # Change create account route to "/register"
+    create_account_route "register"
+
+    # Change password reset request route to "/reset-password/request"
+    reset_password_request_route "reset-password/request"
+  end
+
+If you want to add a prefix to all Rodauth routes, you should use the +prefix+
+setting:
+
+  plugin :rodauth do
+    enable :login, :logout
+
+    # Use /auth prefix to each Rodauth route
+    prefix "/auth"
+  end
+
+  route do |r|
+    r.on "auth" do
+      # Serve Rodauth routes under the /auth branch of the routing tree
+      r.rodauth
+    end
+
+    # ...
+  end

data/doc/guides/query_params.rdoc

@@ -0,0 +1,9 @@
+= Pass query parameters to auth URLs
+
+The <tt>*_path</tt> and <tt>*_url</tt> methods allow passing additional query parameters:
+
+  rodauth.create_account_path(type: "seller")
+  #=> "/create-account?type=seller"
+
+  rodauth.login_url(type: "operator")
+  #=> "https//example.com/login?type=operator"

data/doc/guides/redirects.rdoc

@@ -0,0 +1,17 @@
+= Change redirect destination
+
+You can change the redirect destination for any Rodauth action by overriding
+the corresponding <tt>*_redirect</tt> method:
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account, :reset_password
+
+    # Redirect to "/dashboard" after login
+    login_redirect "/dashboard"
+
+    # Redirect to wherever login redirects to after creating account
+    create_account_redirect { login_redirect }
+
+    # Redirect to login page after password reset
+    reset_password_redirect { login_path }
+  end

data/doc/guides/registration_field.rdoc

@@ -0,0 +1,68 @@
+= Add new field during account creation
+
+The create account form only handles login and password parameters by
+default. However, you might want to ask for additional information during
+account creation, such as requiring the user to also enter their full name
+or their company's name.
+
+== A) Accounts table
+
+Let's assume you wanted to wanted to store the additional field(s) directly on
+the +accounts+ table:
+
+  atler_table :accounts do
+    add_column :name, String
+  end
+
+You need to override the <tt>create-account</tt> template, which by default in
+Rodauth you can do by adding a <tt>create-account.erb</tt> template in your
+Roda +views+ directory.  
+
+Once you've added the <tt>create-account.erb</tt> template, and had it include
+a field for the +name+, you can handle the submission of that field in a before
+create account hook:
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account
+
+    before_create_account do
+      # Validate presence of the name field
+      unless name = param_or_nil("name")
+        throw_error_status(422, "name", "must be present")
+      end
+
+      # Assign the new field to the account record
+      account[:name] = name
+    end
+  end
+
+== B) Separate table
+
+Alternatively, you can store the additional field(s) in separate table, for
+example:
+
+  create_table :account_names do
+    foreign_key :account_id, :accounts, primary_key: true, type: :Bignum
+    String :name, null: false
+  end
+
+You can then handle the new submitted field as follows:
+
+  plugin :rodauth do
+    enable :login, :logout, :create_account
+
+    before_create_account do
+      # Validate presence of the name field
+      throw_error_status(422, "name", "must be present") unless param_or_nil("name")
+    end
+
+    after_create_account do
+      # Create the associated record
+      db[:account_names].insert(account_id: account[:id], name: param("name"))
+    end
+
+    after_close_account do
+      # Delete the associated record
+      db[:account_names].where(account_id: account[:id]).delete
+    end
+  end

data/doc/guides/require_mfa.rdoc

@@ -0,0 +1,30 @@
+= Require multifactor authentication after login
+
+You may want to require multifactor authentication on login for people
+that have multifactor authentication set up. The +require_authentication+
+Rodauth method works for pages that require an authenticated user, but not for
+pages where authentication is optional.
+
+You can set this up as follows:
+
+  plugin :rodauth do
+    enable :login, :logout, :otp
+
+    # If you don't want to show an error message when redirecting
+    # to the multifactor authentication page.
+    two_factor_need_authentication_error_flash nil
+
+    # Display the same flash message after multifactor
+    # authentication than is displayed after login
+    two_factor_auth_notice_flash { login_notice_flash }
+  end
+
+  route do |r|
+    r.rodauth
+
+    if rodauth.logged_in? && rodauth.two_factor_authentication_setup?
+      rodauth.require_two_factor_authenticated
+    end
+
+    # ...
+  end

data/doc/guides/reset_password_autologin.rdoc

@@ -0,0 +1,21 @@
+= Autologin after password reset
+
+When the user resets their password, by default they are not automatically
+logged in. You can change this behaviour and login the user automatically
+after password reset.
+
+  plugin :rodauth do
+    enable :login, :logout, :reset_password
+
+    reset_password_autologin? true
+  end
+
+Similarly, when the verify login change feature is used, the user is not
+automatically logged in after verifying the login change.  You can configure
+Rodauth to automatically log the user in in this case:
+
+  plugin :rodauth do
+    enable :login, :logout, :verify_login_change
+
+    verify_login_change_autologin? true
+  end

data/doc/guides/status_column.rdoc

@@ -0,0 +1,28 @@
+= Store account status in a text column
+
+By default, Rodauth recommends using a separate table for account statuses, and
+linking them via foreign keys. This is useful as it achieves an enum-like
+behaviour, where the database ensures a constrained set of status values.
+
+However, if you use a testing environment that starts with a blank database,
+and don't want to fix your testing environment to support real foreign keys,
+you can configure Rodauth to store the account status in a text column.
+Doing so results in problems if a text value you do not expect gets stored
+in the column.  We can mitigate the problems by using a CHECK constraint
+on the column.
+
+  create_table :accounts do
+    # ...
+    String :status, null: false, default: "verified",
+      check: {status: %w'unverified verified closed'}
+  end
+
+Then we can configure Rodauth to support this.
+
+  plugin :rodauth do
+    # ...
+    account_status_column :status
+    account_unverified_status_value "unverified"
+    account_open_status_value "verified"
+    account_closed_status_value "closed"
+  end

data/doc/guides/totp_or_recovery.rdoc

@@ -0,0 +1,16 @@
+= Allow recovery code on TOTP code field
+
+If using the otp feature, for convenience you might want to allow
+the user to enter the recovery code into the TOTP code field, instead
+of requiring they use the separate recovery codes form. You can
+implement this using the following configuration:
+
+  plugin :rodauth do
+    enable :login, :logout, :otp, :recovery_codes
+
+    before_otp_auth_route do
+      if recovery_code_match?(param(otp_auth_param))
+        two_factor_authenticate("recovery_code")
+      end
+    end
+  end

data/doc/jwt_refresh.rdoc

@@ -13,23 +13,40 @@ older access tokens.  Older access tokens remain valid until they expire.  You
 can use the active_sessions feature if you want previous access tokens to be invalid
 as soon as the refresh token is used.
 
+You can have multiple active refresh tokens active at a time, since each browser session
+will generally use a separate refresh token.  If you would like to revoke a refresh token
+when logging out, provide the refresh token when submitting the JSON request to logout.
+If you would like to remove all refresh tokens for the account when logging out, provide
+a value of <tt>all</tt> as the token value.
+
+When using the refresh token, you must provide a valid access token, as that contains
+information about the current session, which is used to create the new access token.
+If you change the +allow_refresh_with_expired_jwt_access_token?+ setting to +true+,
+an expired but otherwise valid access token will be accepted, and Rodauth will check
+that the access token was issued in the same session as the refresh token.
+
 This feature depends on the jwt feature.
 
 == Auth Value Methods
 
+allow_refresh_with_expired_jwt_access_token? :: Whether refreshing should be allowed with an expired access token. Default is +false+.  You must set an +hmac_secret+ if setting this value to +true+.
 jwt_access_token_key :: Name of the key in the response json holding the access token.  Default is +access_token+.
 jwt_access_token_not_before_period :: How many seconds before the current time will the jwt be considered valid (to account for inaccurate clocks). Default is 5.
 jwt_access_token_period :: Validity of an access token in seconds, default is 1800 (30 minutes).
 jwt_refresh_route :: The route to the login action. Defaults to <tt>jwt-refresh</tt>.
 jwt_refresh_invalid_token_message :: Error message when the provided refresh token is non existent, invalid or expired.
 jwt_refresh_token_account_id_column :: The column name in the +jwt_refresh_token_table+ storing the account id, should be a foreign key referencing the accounts table.
+jwt_refresh_token_data_session_key :: The key in the session hash storing random data, for access checking during refresh if +allow_refresh_with_expired_jwt_access_token?+ is set.
 jwt_refresh_token_deadline_column :: The column name in the +jwt_refresh_token_table+ storing the deadline after which the refresh token will no longer be valid.
 jwt_refresh_token_deadline_interval :: Validity of a refresh token. Default is 14 days.
+jwt_refresh_token_hmac_session_key :: The key in the session hash storing the hmac, for access checking during refresh if +allow_refresh_with_expired_jwt_access_token?+ is set.
 jwt_refresh_token_id_column :: The column name in the refresh token keys table storing the id of each token (the primary key of the table).
 jwt_refresh_token_key :: Name of the key in the response json holding the refresh token.  Default is +refresh_token+.
 jwt_refresh_token_key_column :: The column name in the +jwt_refresh_token_table+ holding the refresh token key value.
 jwt_refresh_token_key_param :: Name of parameter in which the refresh token is provided when requesting a new token.  Default is +refresh_token+.
 jwt_refresh_token_table :: Name of the table holding refresh token keys.
+jwt_refresh_without_access_token_message :: Error message when trying to refresh with providing an access token.
+jwt_refresh_without_access_token_status :: The HTTP status code to use when trying to refresh without providing an access token.
 
 == Auth Methods
 

data/doc/login.rdoc

@@ -3,6 +3,13 @@
 The login feature implements a login page.  It's the most commonly
 used feature.
 
+In addition to the auth methods below, it provides a +login+ method that wraps
++login_session+, running login hooks and redirecting to the configured
+location.
+
+  rodauth.account           #=> { id: 123, ... }
+  rodauth.login('password') # login the current account
+
 == Auth Value Methods
 
 login_additional_form_tags :: HTML fragment containing additional form tags to use on the login form.
@@ -27,4 +34,5 @@ use_multi_phase_login? :: Whether to ask for login first, and only ask for passw
 
 before_login_route :: Run arbitrary code before handling a login route.
 login_view :: The HTML to use for the login form.
+login_return_to_requested_location_path :: If +login_return_to_requested_location?+ is true, the path to use as the requested location.  By default, uses the full path of the request for GET requests, and is nil for non-GET requests (in which case the default +login_redirect+ will be used).
 multi_phase_login_view :: The HTML to use for the login form after login has been entered when using multi phase login.

data/doc/login_password_requirements_base.rdoc

@@ -9,8 +9,10 @@ already_an_account_with_this_login_message :: The error message to display when
 login_confirm_label :: The label to use for login confirmations.
 login_confirm_param :: The parameter name to use for login confirmations.
 login_does_not_meet_requirements_message :: The error message to display when the login does not meet the requirements you have set.
+login_email_regexp :: The regular expression used to validate whether login is a valid email address.
 login_maximum_length :: The maximum length for logins, 255 by default.
 login_minimum_length :: The minimum length for logins, 3 by default.
+login_not_valid_email_message :: The error message to display when login is not a valid email address.
 login_too_long_message :: The error message fragment to show if the login is too long.
 login_too_short_message :: The error message fragment to show if the login is too short.
 logins_do_not_match_message :: The error message to display when login and login confirmation do not match.
@@ -29,6 +31,7 @@ same_as_existing_password_message :: The error message to display when a new pas
 == Auth Methods
 
 login_meets_requirements?(login) :: Whether the given login meets the requirements.  By default, just checks that the login is a valid email address.
+login_valid_email?(login) :: Whether the login is a valid email address.
 password_hash(password) :: A hash of the given password.
 password_meets_requirements?(password) :: Whether the given password meets the requirements. Can be used to implement complexity requirements for passwords.
 set_password(password) :: Set the password for the current account to the given password.

data/doc/otp.rdoc

@@ -73,6 +73,7 @@ otp_auth_view :: The HTML to use for the OTP authentication form.
 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.

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/release_notes/2.2.0.txt

@@ -0,0 +1,39 @@
+= New Features
+
+* When using the jwt_refresh feature, you can remove the current
+  refresh token when logging out by submitting the refresh token
+  in the logout request, the same as when submitting the refresh
+  token to obtain a new refresh token.  You can also use a value
+  of "all" instead of the refresh token to remove all refresh
+  tokens when logging out.
+
+* A rodauth.otp_last_use method has been added to the otp feature,
+  allowing you to determine when the otp was last used.
+
+= Other Improvements
+
+* When using multifactor authentication, rodauth.authenticated? and
+  rodauth.require_authentication now cache values in the session and
+  do not perform queries every time they are called.
+
+* Many guides for common scenarios have been added to the
+  documentation.  These augment Rodauth's existing comprehensive
+  feature documentation, which is aimed to be more of a reference
+  and less of a guide.
+
+* When the verify_account_grace_period and email_auth features are
+  used with a multifactor authentication feature, and the
+  verify_account_set_password? configuration method is set to true,
+  Rodauth no longer raises a NoMethodError when checking if the
+  session was authenticated.
+
+* In the verify_account feature, if verify_account_email_resend
+  returns false indicating no email was sent, an error message
+  is now used, instead of a success message.
+
+* In the password_complexity feature, the password_dictionary
+  configuration method was previously ignored if the default
+  password dictionary file existed.
+
+* Rodauth and all features that ship with it now have 100% branch
+  coverage.

data/doc/release_notes/2.3.0.txt

@@ -0,0 +1,37 @@
+= New Features
+
+* Configuration methods have been added for easier validation of
+  logins when logins must be valid email addresses (the default):
+
+  * login_valid_email?(login) can be used for full control of
+    determining whether the login is valid.
+
+  * login_email_regexp can be used to set the regexp used in the
+    default login_valid_email? check.
+
+  * login_not_valid_email_message can be used to set the field
+    error message if the login is not a valid email.  Previously, this
+    value was hardcoded and not translatable.
+
+* The {create,drop}_database_authentication_functions now work
+  correctly with uuid keys on PostgreSQL.  All other parts of
+  Rodauth already worked correctly with uuid keys.
+
+= Other Improvements
+
+* The before_jwt_refresh_route hook is now called before the route
+  is taken. Previously, the configuration method had no effect.
+
+* rodauth.login can now be used by external code to login the current
+  account (the account that rodauth.account returns).  This should be
+  passed the authentication type string used to login, such as
+  password.
+
+* The jwt_refresh route now returns an error for requests where a
+  valid access token for a logged in session is not provided.  You
+  can use the jwt_refresh_without_access_token_message and
+  jwt_refresh_without_access_token_status configuration methods
+  to configure the error response.
+
+* The new refresh token is now available to the after_refresh_token
+  hook by looking in json_response[jwt_refresh_token_key].