rodauth 2.0.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 729e0ac62a92c8c92808b20e292ad8b8ad5cc2ba935d62702f8d88496e54e1a1
-  data.tar.gz: f0f0aa6dafc54aefd135b3a94b963a136349a69eef9614f4f61f8c24fe759709
+  metadata.gz: e85b192c01a27f50a917584cb3d0f09e947152c116b022f955d2c7c03ff43f7a
+  data.tar.gz: a4d87aa35b1ae50b5901495b8062ad3a2ad25695b46d4fa91b30d8439a4b7ab1
 SHA512:
-  metadata.gz: 7474a1229f4d069ced3b4575c2aa9d343f4bf1b4f3efd4ed64c33b5985b262863d97366f86d226c261f7cce1ccd20090412639f782b38e5f85f4f56556b45622
-  data.tar.gz: 427688ab9aae856b200dee9b7fcfb71bad8bf52b657e1f4d3c8e8ecb3ccd6c2831f71033054bf0d6ef3335fc7697dbdc9a82d29e71393328534b57406316b184
+  metadata.gz: '000885791eb76a2f283e2f243d281c6c103cdd35ad3b8e15b2510d20e7a05db19bee9a30a5ca9d2fc536a46007fe169674aa799698ad83eac292fd5475d9beb8'
+  data.tar.gz: c73dfb2edd91f6a2d134494504ca0042f7357380ea9dbcb495b7265d25c0fdc62a8cadb07cf5182e330e1bf935c608e9f01f943dfdb21084bf08147848b67026

data/CHANGELOG

@@ -1,3 +1,61 @@
+=== 2.5.0 (2020-10-22)
+
+* Add change_login_needs_verification_notice_flash for easier translation of change_login_notice_flash when using verify_login_change (bjeanes, janko, jeremyevans) (#126)
+
+* Add login_return_to_requested_location_path for controlling path to use as the requested location (HoneyryderChuck, jeremyevans) (#122, #123)
+
+=== 2.4.0 (2020-09-21)
+
+* Add session_key_prefix for more easily using separate session keys when using multiple configurations (janko) (#121)
+
+* Add password_pepper feature for appending a secret key to passwords before they are hashed, supporting secret rotation (janko) (#119)
+
+=== 2.3.0 (2020-08-21)
+
+* Return an error status instead of an invalid access token when trying to refresh JWT without an access token in the jwt_refresh feature (jeremyevans)
+
+* Allow {create,drop}_database_authentication_functions to work with UUID keys (monorkin, janko) (#117)
+
+* Add rodauth.login('login_type') for logging in after setting a valid account (janko) (#114)
+
+* Make new refresh token available to the after_refresh_token hook by setting it in the response first (jeremyevans)
+
+* Make the jwt_refresh plugin call before_jwt_refresh_route hook (previously the configuration method was ignored) (AlexeyMatskevich) (#110)
+
+* Add login_email_regexp, login_not_valid_email_message, and log_valid_email? configuration methods (janko) (#107)
+
+=== 2.2.0 (2020-07-20)
+
+* Allow removing all jwt_refresh tokens when logging out by providing a value of "all" as the token to remove (jeremyevans)
+
+* Allow removing specific jwt_refresh token when logging out by providing the token to remove (jeremyevans)
+
+* Avoid NoMethodError when checking if session is authenticated when using two factor auth, verify_account_grace_period, and email_auth (jeremyevans) (#105)
+
+* Reduce queries in #authenticated? and #require_authentication when using two factor authentication (janko) (#106)
+
+* Treat verify_account_email_resend returning false as an error in the verify_account feature (jeremyevans)
+
+* Fix use of password_dictionary configuration method in password_complexity feature (jeremyevans)
+
+* Remove unnecessary conditionals (jeremyevans)
+
+* Add otp_last_use to the otp feature, returning the time of last successful OTP use (jeremyevans) (#103)
+
+=== 2.1.0 (2020-06-09)
+
+* Do not check CSRF tokens by default for requests using JWT (janko, jeremyevans) (#99)
+
+* Use new-password autocomplete value for password field when creating accounts (jeremyevans) (#98)
+
+* Consistently use json_response_body for all JSON responses in jwt feature (arthurmmoreira) (#97)
+
+* Add check_csrf configuration method to customize CSRF checking (janko) (#96)
+
+* Have logged_in? when using http_basic_auth feature check for basic authentication (jeremyevans) (#94)
+
+* Don't consider account open if in unverified grace period without password (janko) (#92)
+
 === 2.0.0 (2020-05-06)
 
 * Do not show email auth as an option for unverified accounts if using the verify_account_grace_period feature (jeremyevans) (#88)

data/README.rdoc

@@ -44,6 +44,7 @@ HTML and JSON API for all supported features.
 * Verify Account Grace Period (Don't require verification before login)
 * Password Grace Period (Don't require password entry if recently entered)
 * Password Complexity (More sophisticated checks)
+* Password Pepper
 * Disallow Password Reuse
 * Disallow Common Passwords
 * Password Expiration
@@ -881,6 +882,7 @@ view the appropriate file in the doc directory.
 * {Password Complexity}[rdoc-ref:doc/password_complexity.rdoc]
 * {Password Expiration}[rdoc-ref:doc/password_expiration.rdoc]
 * {Password Grace Period}[rdoc-ref:doc/password_grace_period.rdoc]
+* {Password Pepper}[rdoc-ref:doc/password_pepper.rdoc]
 * {Recovery Codes}[rdoc-ref:doc/recovery_codes.rdoc]
 * {Remember}[rdoc-ref:doc/remember.rdoc]
 * {Reset Password}[rdoc-ref:doc/reset_password.rdoc]
@@ -1062,6 +1064,18 @@ the name as an argument to use that configuration:
     r.rodauth
   end
 
+By default, alternate configurations will use the same session keys as the
+primary configuration, which may be undesirable. To ensure session state is
+separated between configurations, you can set a session key prefix for
+alternate configurations.  If you are using the remember feature in both
+configurations, you may also want to set a different remember key in the
+alternate configuration:
+
+  plugin :rodauth, :name=>:secondary do
+    session_key_prefix "secondary_"
+    remember_cookie_key "_secondary_remember"
+  end
+
 === With Password Hashes Inside the Accounts Table
 
 You can use Rodauth if you are storing password hashes in the same

data/doc/base.rdoc

@@ -17,6 +17,7 @@ mark_input_fields_as_required? :: Whether input fields should be marked as requi
 prefix :: The routing prefix used for Rodauth routes.  If you are calling in a routing subtree, this should be set to the root path of the subtree.  This should include a leading slash if set, but not a trailing slash.
 require_bcrypt? :: Set to false to not require bcrypt, useful if using custom authentication.
 session_key :: The key in the session hash storing the primary key of the logged in account.
+session_key_prefix :: The string that will be prepended to the default value for all session keys.
 skip_status_checks? :: Whether status checks should be skipped for accounts.  Defaults to true unless enabling the verify_account or close_account features.
 title_instance_variable :: The instance variable to set in the Roda scope with the page title.  The layout should use this instance variable if available to set the title of the page.  You can use +set_title+ if setting the page title is not done through an instance variable.
 
@@ -91,6 +92,7 @@ authenticated? :: Whether the user has been authenticated. If multifactor authen
 before_login :: Run arbitrary code after password has been checked, but before updating the session.
 before_login_attempt :: Run arbitrary code after an account has been located, but before the password has been checked.
 before_rodauth :: Run arbitrary code before handling any rodauth route, but after CSRF checks if Rodauth is doing CSRF checks.
+check_csrf :: Checks CSRF token using Roda's +check_csrf!+ method.
 clear_session :: Clears the current session.
 csrf_tag(path=request.path) :: The HTML fragment containing the CSRF tag to use, if any.
 function_name(name) :: The name of the database function to call.  It's passed either :rodauth_get_salt or :rodauth_valid_password_hash.

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"

data/doc/guides/links.rdoc

@@ -0,0 +1,12 @@
+= Display authentication links
+
+You can retrieve a relative URL to any Rodauth action by calling the
+corresponding <tt>*_path</tt> method on the Rodauth instance:
+
+  <a href="<%= rodauth.login_path %>">Sign in</a>
+  <a href="<%= rodauth.create_account_path %>">Sign up</a>
+
+For absolute URLs instead of paths, you can use the <tt>*_url</tt> methods:
+
+  <a href="<%= rodauth.login_url %>">Sign in</a>
+  <a href="<%= rodauth.create_account_url %>">Sign up</a>

data/doc/guides/login_return.rdoc

@@ -0,0 +1,37 @@
+= Redirect to original page after login
+
+When the user attempts to open a page that requires authentication, Rodauth
+redirects them to the login page. It can be useful to redirect them back to
+the page they originally requested after successful login.  Similarly, you
+can do this for pages requiring multifactor authentication.
+
+  plugin :rodauth do
+    enable :login, :logout, :otp
+
+    # Have successful login redirect back to originally requested page
+    login_return_to_requested_location? true
+
+    # Have successful multifactor authentication redirect back to
+    # originally requested page
+    two_factor_auth_return_to_requested_location? true
+  end
+
+You can manually set which page to redirect after login or multifactor
+authentication, though it is questionable whether the user will desire
+this behavior compared to the default.
+
+  route do |r|
+    r.rodauth
+
+    # Return the last visited path after login
+    if rodauth.logged_in?
+      # Return to the last visited page after multifactor authentication
+      unless rodauth.two_factor_authenticated?
+        session[rodauth.two_factor_auth_redirect_session_key] = request.fullpath
+      end
+    else
+      session[rodauth.login_redirect_session_key] = request.fullpath
+    end
+
+    # rest of routes
+  end

data/doc/guides/password_column.rdoc

@@ -0,0 +1,25 @@
+= Store password hash in accounts table
+
+By default, Rodauth stores the password hash in a separate
++account_password_hashes+ table.  This makes it a lot less likely that the
+password hashes will be leaked, especially if you use Rodauth's default
+approach of using database functions for checking the hashes.
+
+However, if you have reasons for storing the password hashes in +accounts+
+table that outweigh the security benefits of Rodauth's default approach,
+Rodauth supports that.
+
+To do this, add the password hash column to the +accounts+ table:
+
+  alter_table :accounts do
+    add_column :password_hash, String
+  end
+
+And then tell Rodauth to use it:
+
+  plugin :rodauth do
+    enable :login, :logout
+
+    # Use the password_hash column in the accounts table
+    account_password_hash_column :password_hash
+  end

data/doc/guides/password_confirmation.rdoc

@@ -0,0 +1,37 @@
+= Require password confirmation for certain actions
+
+You might want to require the user to enter their password before accessing
+sensitive sections of the app. This functionality is provided by the confirm
+password feature, which accompanied with the password grace period feature will
+remember the entered password for a period of time:
+
+  plugin :rodauth do
+    enable :confirm_password, :password_grace_period
+
+    # Remember the password for 1 hour
+    password_grace_period 60*60
+  end
+
+  route do |r|
+    r.rodauth
+
+    r.is 'some-action' do
+      # Require password authentication if the password has not been
+      # input recently.
+      rodauth.require_password_authentication
+
+      # ...
+    end
+  end
+
+You can also do this for Rodauth actions that normally require a password.
+Which essentially moves the password confirmation into a separate step, as
+Rodauth's behavior with the password grace period feature is to ask for the
+password on the same form.
+
+  plugin :rodauth do
+    enable :confirm_password, :password_grace_period, :change_login, :change_password
+
+    before_change_login_route    { require_password_authentication }
+    before_change_password_route { require_password_authentication }
+  end