rodauth 1.21.0 → 2.2.0

data/doc/close_account.rdoc

@@ -5,28 +5,21 @@ The close account feature allows users to close their accounts.
 == Auth Value Methods
 
 account_closed_status_value :: The integer representing closed accounts.
-close_account_additional_form_tags :: HTML fragment containing additional
-                                      form tags to use on the close account
-                                      form.
+close_account_additional_form_tags :: HTML fragment containing additional form tags to use on the close account form.
 close_account_button :: The text to use for the close account button.
-close_account_notice_flash :: The flash notice to show after closing the
-                              account.
+close_account_error_flash :: The flash error to show if there is an error closing the account.
+close_account_notice_flash :: The flash notice to show after closing the account.
+close_account_page_title :: The page title to use on the close account form.
 close_account_redirect :: Where to redirect after closing the account.
-close_account_requires_password? :: Whether a password is required when
-                                    closing accounts.
-close_account_route :: The route to the close account action. Defaults to
-                       +close-account+.
-delete_account_on_close? :: Whether to delete the account when closing it,
-                            default value is to use +skip_status_checks?+.
+close_account_requires_password? :: Whether a password is required when closing accounts.
+close_account_route :: The route to the close account action. Defaults to +close-account+.
+delete_account_on_close? :: Whether to delete the account when closing it, default value is to use +skip_status_checks?+.
 
 == Auth Methods
 
 after_close_account :: Run arbitrary code after closing the account.
 before_close_account :: Run arbitrary code before closing an account.
 before_close_account_route :: Run arbitrary code before handling a close account route.
-close_account :: Close the account, by default setting the account status
-                 to closed.
+close_account :: Close the account, by default setting the account status to closed.
 close_account_view :: The HTML to use for the close account form.
-delete_account :: If +delete_account_on_close?+ is true, delete the account
-                  when closing it.
-                  
+delete_account :: If +delete_account_on_close?+ is true, delete the account when closing it.

data/doc/confirm_password.rdoc

@@ -1,24 +1,31 @@
 = Documentation for Confirm Password Feature
 
 The confirm password feature allows you to redirect users to a page to
-confirm their password.  It's used by the remember feature, but can also
-by your application if you want to confirm passwords.
+confirm their password.
+
+When confirming passwords, if authenticated via autologin, a remember token,
+or an email_auth token, switches the authentication type from that login
+method to password.
 
 == Auth Value Methods
 
 confirm_password_additional_form_tags :: HTML fragment containing additional form tags to use on the confirm password form.
 confirm_password_button :: The text to use for the confirm password button.
 confirm_password_error_flash :: The flash error to show if password confirmation is unsuccessful.
+confirm_password_link_text :: The text to use for the link from the two factor auth page.
 confirm_password_notice_flash :: The flash notice to show after password confirmed successful.
+confirm_password_page_title :: The page title to use on the confirm password form.
 confirm_password_redirect :: Where to redirect after successful password confirmation. By default, uses <tt>session[confirm_password_redirect_session_key]</tt> if set, allowing an easy way to redirect back to the page requesting password confirmation.
 confirm_password_redirect_session_key :: The session key used to check for the confirm_password_redirect.
-confirm_password_route :: The route to the confirm password form. Defaults to
-                          +confirm-password+.
+confirm_password_route :: The route to the confirm password form. Defaults to +confirm-password+.
+password_authentication_required_error_flash :: The flash error to show if going to a page requiring password confirmation.
+password_authentication_required_error_status :: The response status to use if going to a page requiring password confirmation, 401 by default.
+password_authentication_required_redirect :: Where to redirect when going to a page requiring password confirmation.
 
 == Auth Methods
 
 after_confirm_password :: Run arbitrary code after successful confirmation of password.
 before_confirm_password :: Run arbitrary code before setting that the password has been confirmed.
-confirm_password :: Run arbitrary code on correct password confirmation.
 before_confirm_password_route :: Run arbitrary code before handling the password confirmation route.
+confirm_password :: Update the session to reflect the password has been confirmed.
 confirm_password_view :: The HTML to use for the confirm password form.

data/doc/create_account.rdoc

@@ -4,34 +4,23 @@ The create account feature allows users to create new accounts.
 
 == Auth Value Methods
 
-create_account_additional_form_tags :: HTML fragment containing additional
-                                       form tags to use on the create account
-                                       form.
+create_account_additional_form_tags :: HTML fragment containing additional form tags to use on the create account form.
 create_account_button :: The text to use for the create account button.
-create_account_error_flash :: The flash error to show for unsuccessful
-                              account creation.
-create_account_notice_flash :: The flash notice to show after successful
+create_account_error_flash :: The flash error to show for unsuccessful account creation.
+create_account_notice_flash :: The flash notice to show after successful account creation.
+create_account_page_title :: The page title to use on the create account form.
 create_account_redirect :: Where to redirect after creating the account.
-create_account_route :: The route to the create account action. Defaults to
-                        +create-account+.
-create_account_set_password? :: Whether to ask for a password to be set on the create
-                                account form.  Defaults to true.  If set to false, an
-                                alternative method to set the password should be used.
+create_account_route :: The route to the create account action. Defaults to +create-account+.
+create_account_set_password? :: Whether to ask for a password to be set on the create account form.  Defaults to true if not verifying accounts.  If set to false, an alternative method to set the password should be used (assuming you want to allow password authentication).
 
 == Auth Methods
 
 after_create_account :: Run arbitrary code after creating the account.
 before_create_account :: Run arbitrary code before creating the account.
 before_create_account_route :: Run arbitrary code before handling a create account route.
-create_account_autologin? :: Whether to autologin the user upon
-                             successful account creation, true by default unless verifying
-                             accounts.
-create_account_link :: HTML fragment to display with a link to the create
-                       account form.
+create_account_autologin? :: Whether to autologin the user upon successful account creation, true by default unless verifying accounts.
+create_account_link_text :: The text to use for a link to the create account form.
 create_account_view :: The HTML to use for the create account form.
-new_account(login) :: Instantiate a new account hash for the
-                      given login, without saving it.
-save_account :: Insert the account into the database, or return nil/false if that
-                was not successful.
-set_new_account_password :: Set the password for a new account if
-                            +account_password_hash_column+ is set, without saving.
+new_account(login) :: Instantiate a new account hash for the given login, without saving it.
+save_account :: Insert the account into the database, or return nil/false if that was not successful.
+set_new_account_password :: Set the password for a new account if +account_password_hash_column+ is set, without saving.

data/doc/disallow_password_reuse.rdoc

@@ -17,21 +17,14 @@ current password.
 
 == Auth Value Methods
 
-password_same_as_previous_password_message :: The error message fragment to display if the
-                                              given password is the same as a previous
-                                              password.
-previous_password_account_id_column :: The column in the +previous_password_hash_table+ that
-                                       stores the account id.
-previous_password_hash_column :: The column in the +previous_password_hash_table+ that
-                                 stores the password hash.
+password_same_as_previous_password_message :: The error message fragment to display if the given password is the same as a previous password.
+previous_password_account_id_column :: The column in the +previous_password_hash_table+ that stores the account id.
+previous_password_hash_column :: The column in the +previous_password_hash_table+ that stores the password hash.
 previous_password_hash_table :: The table storing previous password hashes.
-previous_password_id_column :: The column in the +previous_password_hash_table+ that
-                               stores the autoincrementing primary key.
+previous_password_id_column :: The column in the +previous_password_hash_table+ that stores the autoincrementing primary key.
 previous_passwords_to_check :: The number of previous password hashes to store and check.
 
 == Auth Methods
 
-add_previous_password_hash(hash) :: Add the given hash to the list of previous hashes for
-                                    the current account.
-password_doesnt_match_previous_password?(password) :: Whether the password given matches any
-                                                      of the previous passwords.
+add_previous_password_hash(hash) :: Add the given hash to the list of previous hashes for the current account.
+password_doesnt_match_previous_password?(password) :: Whether the password given matches any of the previous passwords.

data/doc/email_auth.rdoc

@@ -1,34 +1,35 @@
 = Documentation for Email Auth Feature
 
-The email auth feature implements login using links sent via email.  It is
-very similar to the email auth feature, except you don't need to update
-a password, or even have a password to login.  Depends on the login and
+The email auth feature implements passwordless login using links sent via email.  It is
+similar to the reset password feature, except you don't need to update
+a password, or even have a password to login.  It depends on the login and
 email_base features.
 
 == Auth Value Methods
 
 email_auth_additional_form_tags :: HTML fragment containing additional form tags to use on the email auth login form.
+email_auth_deadline_column :: The column name in the +email_auth_table+ storing the deadline after which the token will be ignored.
+email_auth_deadline_interval :: The amount of time for which to allow users to use email auth keys, 1 day by default. Only used if set_deadline_values? is true.
+email_auth_email_last_sent_column :: The email auth last sent column in the +email_auth_table+, storing the last time the email was sent. Set to nil to always send an email when requested.
 email_auth_email_recently_sent_error_flash :: The flash error to show if not sending an email auth email because another was sent recently.
 email_auth_email_recently_sent_redirect :: Where to redirect after not sending an email auth email because another was sent recently.
-email_auth_deadline_column :: The column name in the email auth keys table storing the deadline after which the token will be ignored.
-email_auth_deadline_interval :: The amount of time for which to allow users to reset their passwords, 1 day by default. Only used if set_deadline_values? is true.
 email_auth_email_sent_notice_flash :: The flash notice to show after an email auth email has been sent.
 email_auth_email_sent_redirect :: Where to redirect after sending an email auth email.
 email_auth_email_subject :: The subject to use for email auth emails.
 email_auth_error_flash :: The flash error to show if unable to login using email authentication.
-email_auth_id_column :: The id column in the email auth keys table, should be a foreign key referencing the accounts table.
-email_auth_key_column :: The email auth key/token column in the email auth keys table.
+email_auth_id_column :: The id column in the +email_auth_table+, should be a foreign key referencing the accounts table.
+email_auth_key_column :: The email auth key/token column in the +email_auth_table+.
 email_auth_key_param :: The parameter name to use for the email auth key.
-email_auth_last_column :: The email auth last sent column in the email auth keys table, storing the last time the email was sent. Set to nil to always send an email when requested.
+email_auth_page_title :: The page title to use on the email auth form.
 email_auth_request_additional_form_tags :: HTML fragment containing additional form tags to use on the email auth request form.
 email_auth_request_button :: The text to use for the email auth request button.
 email_auth_request_error_flash :: The flash error to show if not able to send an email auth email.
 email_auth_request_route :: The route to the email auth request action.  Defaults to +email-auth-request+.
 email_auth_route :: The route to the email auth action. Defaults to +email-auth+.
 email_auth_session_key :: The key in the session to hold the email auth key temporarily.
-email_auth_skip_resend_within :: The number of seconds before sending another email auth email.
-email_auth_table :: The name of the email auth keys table.
-force_email_auth? :: Whether email auth should be forced for the account.  By default, email auth is forced if the account does not have a password.
+email_auth_skip_resend_email_within :: The number of seconds required before sending another email auth email, 5 minutes by default.
+email_auth_table :: The name of the table storing email auth keys.
+force_email_auth? :: Whether email auth should be forced for the account.  False by default, which results in email auth only be used automatically if the account does not have a password.
 no_matching_email_auth_key_error_flash :: The flash error message to show if attempting to access the email auth form with an invalid key.
 
 == Auth Methods
@@ -42,12 +43,12 @@ create_email_auth_email :: A Mail::Message for the email auth email.
 create_email_auth_key :: Add the email auth key data to the database.
 email_auth_email_body :: The body to use for the email auth email.
 email_auth_email_link :: The link to the email auth form in the email auth email.
-email_auth_key_insert_hash :: The hash to insert into the email auth keys table.
+email_auth_key_insert_hash :: The hash to insert into the +email_auth_table+.
 email_auth_key_value :: The email auth key for the current account.
-email_auth_request_form :: The HTML to use for a form to request an email auth email, shown on the login page after the user submits their login, if +force_email_auth?+ is false.
+email_auth_request_form :: The HTML to use for a form to request an email auth email, shown on the login page after the user submits their login, if +force_email_auth?+ is false and email authentication is not the only possible for of authentication for the user.
 email_auth_view :: The HTML to use for the email auth form.
-get_email_auth_key(id) :: Get the email auth key for the given account id from the database.
 get_email_auth_email_last_sent :: Get the last time an email auth email is sent, or nil if there is no last sent time.
+get_email_auth_key(id) :: Get the email auth key for the given account id from the database.
 remove_email_auth_key :: Remove the email auth key for the current account, run after successful email auth.
 send_email_auth_email :: Send the email auth email.
 set_email_auth_email_last_sent :: Set the last time an email auth email is sent.  This is only called if there is a previous email auth token still active.

data/doc/email_base.rdoc

@@ -5,23 +5,14 @@ that requires sending emails.
 
 == Auth Value Methods
 
-allow_raw_email_token? :: When +email_token_hmac_secret+ is used, this allows the use of the raw
-                          token.  This should only be set to true temporarily during a transition
-                          period from using raw tokens to using HMACed tokens.  After the transition
-                          period, this should not be set, as setting this to true removes the
-                          security that HMACed tokens add.
-default_post_email_redirect :: Where to redirect after sending an email. This is the default
-                               redirect location for all redirects after an email is sent when the
-                               account is not logged in.  Also includes cases where an email is not
-                               sent due to rate limiting.
+allow_raw_email_token? :: When +hmac_secret+ is used, this allows the use of the raw token.  This should only be set to true temporarily during a transition period from using raw tokens to using HMACed tokens.  After the transition period, this should not be set, as setting this to true removes the security that HMACed tokens add.
+default_post_email_redirect :: Where to redirect after sending an email. This is the default redirect location for all redirects after an email is sent when the account is not logged in.  Also includes cases where an email is not sent due to rate limiting.
 email_from :: The from address to use for emails sent by Rodauth.
 email_subject_prefix :: The prefix to use for email subjects 
-require_mail? :: Set to false to not require mail, useful if using a different
-                 library for sending email.
+require_mail? :: Set to false to not require mail, useful if using a different library for sending email.
 
 == Auth Methods
 
-email_to :: The email address to send emails to, by default the login of the
-            current account.
-create_email(subject, body) :: Return a Mail::Message instance with the given subject
-                               and body.
+create_email(subject, body) :: Return a Mail::Message instance with the given subject and body.
+email_to :: The email address to send emails to, by default the login of the current account.
+send_email(email) :: Deliver a given Mail::Message instance.

data/doc/guides/admin_activation.rdoc

@@ -0,0 +1,46 @@
+= Require account verification by admin
+
+There are scenarios in which, instead of allowing the user to verify they have
+access to the email for the account, you may want to have an admin or moderator
+approve new accounts manually. One way this can be achieved by sending the
+account verification email to the admin:
+
+  plugin :rodauth do
+    enable :login, :logout, :verify_account, :reset_password
+
+    # Send account verification email to the admin
+    email_to do
+      if account[account_status_column] == account_unverified_status_value
+        "admin@myapp.com"
+      else
+        super()
+      end
+    end
+
+    # Do not ask for password when creating or verifying account
+    verify_account_set_password? false
+    create_account_set_password? false
+
+    # Adjust the account verification email subject and body
+    verify_account_email_subject "New User Awaiting Admin Approval"
+    verify_account_email_body do
+      "The user #{account[login_column]} has created an account. Click here to approve it: #{verify_account_email_link}."
+    end
+
+    # Display this message to the user after they've created their account
+    verify_account_email_sent_notice_flash "Your account has been created and is awaiting approval"
+
+    # Prevent the admin from being logged in after confirming the account
+    verify_account_autologin? false
+    verify_account_notice_flash "The account has been approved"
+
+    # Send a reset password email after verifying the account.
+    # This allows the user to choose the password for the account,
+    # and also makes sure the user can only log in if they have
+    # access to the email address for the account.
+    after_verify_account do
+      generate_reset_password_key_value
+      create_reset_password_key
+      send_reset_password_email
+    end
+  end

data/doc/guides/already_authenticated.rdoc

@@ -0,0 +1,10 @@
+= Skip login page if already authenticated
+
+In some cases it may be useful to skip login/registration pages when the user
+is already logged in. This can be achieved as follows.  Note that this only
+matters if the user manually navigates to the login or create account pages.
+
+  plugin :rodauth do
+    # Redirect logged in users to the wherever login redirects to
+    already_logged_in { redirect login_redirect }
+  end

data/doc/guides/alternative_login.rdoc

@@ -0,0 +1,46 @@
+= Use a non-email login
+
+Rodauth's by default uses email addresses for identifying users, since that is
+the most common form of identifier currently. In some cases, you might want
+to allow logging in via alternative identifiers, such as a username.  In this
+case, it is best to choose a different column name for the login, such as
++:username+.  Among other things, this also makes it so that the login field
+does not expect an email address to be provided.
+
+  plugin :rodauth do
+    enable :login, :logout
+    login_column :username
+  end
+
+Note that Rodauth features that require sending email need an email address, and
+that defaults to the value of the login column.  If you have both a username and
+an email for an account, you can have the login column be the user, and use the
+value of the email colummn for the email address.
+
+  plugin :rodauth do
+    enable :login, :logout, :reset_password
+
+    login_column :username
+    email_to do
+      account[:email]
+    end
+  end
+
+An alternative approach would be to accept a login and automatically change it
+to an email address. If you have a +username+ field on the +accounts+ table,
+then you can configure Rodauth to allow entering a username instead of email
+during login.  See the {Adding new registration field}[rdoc-ref:doc/guides/registration_field.rdoc]
+guide for instructions on requiring add an additional field during registration.
+
+  plugin :rodauth do
+    enable :login, :logout
+
+    account_from_login do |login|
+      # handle the case when login parameter is a username
+      unless login.include?("@")
+        login = db[:accounts].where(username: login).get(:email)
+      end
+
+      super(login)
+    end
+  end

data/doc/guides/create_account_programmatically.rdoc

@@ -0,0 +1,38 @@
+= Create an account record programmatically
+
+In some scenarios you might want to create an account records programmatically,
+for example in your tests.
+
+If you're storing passwords in a separate table, you can create an account
+records as follows:
+
+  account_id = DB[:accounts].insert(
+    email:     "name@example.com",
+    status_id: 2, # verified
+  )
+
+  DB[:account_password_hashes].insert(
+    id:            account_id,
+    password_hash: BCrypt::Password.create("secret").to_s,
+  )
+
+If the password is stored in a column in the accounts table:
+
+  account_id = DB[:accounts].insert(
+    email:         "name@example.com",
+    password_hash: BCrypt::Password.create("secret").to_s,
+    status_id:     2, # verified
+  )
+
+If you are creating accounts in your tests, you probably want to use
+the +:cost+ option, otherwise you will have very slow tests:
+
+  account_id = DB[:accounts].insert(
+    email:     "name@example.com",
+    status_id: 2, # verified
+  )
+
+  DB[:account_password_hashes].insert(
+    id:            account_id,
+    password_hash: BCrypt::Password.create("secret", cost: BCrypt::Engine::MIN_COST).to_s,
+  )

data/doc/guides/delay_password.rdoc

@@ -0,0 +1,25 @@
+= Set password when verifying account
+
+If you want to request less information from the user on registration, you can
+ask the user to set their password only when they verify their account:
+
+  plugin :rodauth do
+    enable :login, :logout, :verify_account
+    verify_account_set_password? true
+  end
+
+Note that this is already the default behaviour when verify account feature is
+loaded, but it's not when verify account grace period is used, because it would
+prevent the account from logging in during the grace period. You can work around
+this by automatically remebering their login during account creation using the
+remember feature.  Be aware that remembering accounts has effects beyond the
+verification period, and this would only allow automatic logins from the browser
+that created the account.
+
+  plugin :rodauth do
+    enable :login, :logout, :verify_account_grace_period, :remember
+    verify_account_set_password? true
+    after_create_account do
+      remember_login
+    end
+  end

data/doc/guides/email_only.rdoc

@@ -0,0 +1,16 @@
+= Allow only email authentication
+
+When using the email authentication feature, you can avoid other authentication
+mechanisms entirely as follows:
+
+  plugin :rodauth do
+    enable :login, :email_auth, :create_account, :verify_account
+
+    create_account_set_password? false
+    verify_account_set_password? false
+    force_email_auth? true
+  end
+
+With this configuration, users won't be required to enter a password on
+registration, and on login the email authentication link will automatically be
+sent after the email address is entered.

data/doc/guides/i18n.rdoc

@@ -0,0 +1,26 @@
+= Translate with i18n gem
+
+Rodauth allows transforming user-facing text configuration such as flash
+messages, validation errors, labels etc. via the +translate+ configuration
+method. This method receives a name of a configuration along with its default
+value, and is expected to return the result text.
+
+You can use this to perform translations using the
+{i18n gem}[https://github.com/ruby-i18n/i18n]:
+
+  plugin :rodauth do
+    enable :login, :logout, :reset_password
+
+    translate do |key, default|
+      I18n.translate("rodauth.#{key}") || default
+    end
+  end
+
+Your translation file may then look something like this:
+
+  en:
+    rodauth:
+      login_notice_flash: "You have been signed in"
+      require_login_error_flash: "Login is required for accessing this page"
+      no_matching_login_message: "user with this email address doesn't exist"
+      reset_password_email_subject: "Password Reset Instructions"