rodauth 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4562cb5ac9001ed624c4a17b266e248bda416bfa
-  data.tar.gz: 83b071943791302efef9980bef8d04629ea26d8a
+  metadata.gz: 9f7b621217958c77c148ee85c271e7e39548b02f
+  data.tar.gz: f4fa75ad99266693763134533d5f7f0dc90de8ba
 SHA512:
-  metadata.gz: 46012c509f3e3fe2df2c27c56d7f0ecb6f950c6f7227faa056f8578f940908d20cd2d7757c5a6c63a387f7da066216eba6ab7e1553fd70d1a92882a8d2a2ced4
-  data.tar.gz: 88d313c1a7739bd54ac588e25046e90eed284502ce119c69862e20cc49028bcee2999e8c0ce93874bec4fefcdb2d92bc1de4183359b395cd9e7a8df8af272bde
+  metadata.gz: 9ce46e8a0b1d1b5f5a2994d4ab3d70503fd5da9f968fa0dc1cbd938cd9ce2d327c8dd427fd09a4c8242b2dbdb8be4f428c40277008352021c91b97ad438689fb
+  data.tar.gz: 6535d95d9d3573f5c7190b990d448f983757d674a4df73662de2567ca197fcc63867773a86a4f3617edc26c4a2cd54f3bb741ba3153f503a8f69094c8a89a3d3

data/CHANGELOG

@@ -1,3 +1,149 @@
+=== HEAD
+
+* Remove invalid remember cookies to prevent unnecessary future database checks (jeremyevans)
+
+* Extend remember deadline in cookie in addition to database (jeremyevans)
+
+* Make tokens work with string account ids (jeremyevans)
+
+* Add verify_change_login feature for requiring account reverification on login changes (jeremyevans)
+
+* Set correct cookie expiration in the remember feature (jeremyevans)
+
+* Split confirm_password feature from remember feature (jeremyevans)
+
+* Add verify_account_grace_period feature, for allowing logins into unverified accounts for a certain period after creation (jeremyevans)
+
+* Move login/password requirements settings to login password requirements base feature (jeremyevans)
+
+* Add session_expiration feature, expiring sessions based on inactivity and max lifetime checks (jeremyevans)
+
+* Add password_grace_period feature, for not requiring password entry if password was recently entered (jeremyevans)
+
+* Make create/verify account autologin true by default (jeremyevans)
+
+* Optimize routing using a hash table, disallow per-request routes (jeremyevans)
+
+* Add ability to turn off login/password confirmations (jeremyevans)
+
+* Don't allow changing login to the same as the current login (jeremyevans)
+
+* Only allow requesting account unlocks if the account is current locked out (jeremyevans)
+
+* Use separate routes for unlock account/reset password/verify account requests (jeremyevans)
+
+* Use separate routes for confirming passwords and changing remember settings (jeremyevans)
+
+* Add JWT feature for JSON API support using JWT tokens (jeremyevans)
+
+* Add account_select configuration option for setting which columns to select from accounts_table (jeremyevans)
+
+* Execute get_block and post_block in the Rodauth::Auth instance scope (jeremyevans)
+
+* Store field errors in the rodauth object instead of instance variables in the Roda scope (jeremyevans)
+
+* Add rodauth.redirect to abstract redirection code (jeremyevans)
+
+* Only use flash notices for successful requests, other requests that redirect now use an error flash (jeremyevans)
+
+* The before_* configuration methods now run directly before making the related database changes (jeremyevans)
+
+* Before hooks run before routes now use before_*_route instead of before_* configuration methods (jeremyevans)
+
+* Add token_separator configuration method to replace the default of _ (jeremyevans)
+
+* Rename account_id_value to account_id (jeremyevans)
+
+* Rename account_id to account_id_column and account_session_id to account_session_column (jeremyevans)
+
+* Make skip_status_checks? default to true unless loading verify_account or close_account features (jeremyevans)
+
+* Replace account_model with accounts_table and db, removing use of Sequel models (jeremyevans)
+
+* Extract shared email-related code into email_base feature (jeremyevans)
+
+* Add auth_class_eval to configuration block for adding custom methods (jeremyevans)
+
+* Add configuration_eval to feature definitions for adding custom configuration methods (jeremyevans)
+
+* Allow close_account feature to optionally delete accounts (jeremyevans)
+
+* Make close_account feature work when skipping status checks or when using account_password_hash_column (jeremyevans)
+
+* Add sms_codes feature, for codes received via SMS that can be used if TOTP authentication is not available (jeremyevans)
+
+* Attempt to handle unique constraint violations raised in race conditions where possible (jeremyevans)
+
+* Add _before and _after internal methods, make ununderscored methods only for users (jeremyevans)
+
+* Add single_session feature, for only allowing a single active session per account (jeremyevans)
+
+* Add account_expiration feature, for disallowing access to accounts after an amount of time since last login/activity (jeremyevans)
+
+* Check account status in rodauth.load_memory in remember plugin (jeremyevans)
+
+* Use csrf plugin automatically, depend on Roda >=2.6.0 (jeremyevans)
+
+* Make bcrypt and mail development dependencies instead of runtime dependencies in the gem (jeremyevans)
+
+* Add password_expiration feature, requiring users to change their password after a given amount of time (jeremyevans)
+
+* Add disallow_password_reuse feature, checking that a new password doesn't match previous passwords (jeremyevans)
+
+* Add password_complexity feature, allowing more sophisticated password complexity checks (jeremyevans)
+
+* Add rodauth.remember_param and .remember_confirm_param for overriding parameter names (jeremyevans)
+
+* Check that new password is not the same as existing password in change password and reset password features (jeremyevans)
+
+* Add rodauth.login_meets_requirements? for checking if a login is valid, by default a valid email address (jeremyevans)
+
+* Allow unlock account to optionally require the user's current password (jeremyevans)
+
+* Add support for running on Microsoft SQL Server with database functions for authentication (jeremyevans)
+
+* Make change password, change login, and close account require the user's current password by default (jeremyevans)
+
+* Add rodauth.csrf_tag to make it easy to replace the CSRF tag implementation (jeremyevans)
+
+* Switch unlock_account_autologin? to be true by default (jeremyevans)
+
+* Add rodauth.authenticated? and .require_authentication (jeremyevans)
+
+* Add recovery_codes feature, for single use codes that can be used if TOTP authentication is not available (jeremyevans)
+
+* Add otp feature, for 2 factor authentication via TOTP (jeremyevans)
+
+* Add support for running on MySQL with database functions for authentication (jeremyevans)
+
+* Add *_interval and set_deadline_values? methods for setting deadline intervals on a per-request basis (jeremyevans)
+
+* Add remember_deadline_column method for overriding the column used for storing the deadline (jeremyevans)
+
+* Add rodauth/migrations file for DRYing up the database function creation (jeremyevans)
+
+* Add Rodauth.version for getting the version (jeremyevans)
+
+* External features should now be requirable via rodauth/features/feature_name instead of roda/plugins/rodauth/feature_name (jeremyevans)
+
+* Make Rodauth top level module instead of under Roda::RodaPlugins (jeremyevans)
+
+* Require mail at configure time instead of run time if using a feature that sends email, use require_mail? false to disable (jeremyevans)
+
+* Require bcrypt at configure time instead of run time, use require_bcrypt? false to disable (jeremyevans)
+
+* Always require securerandom (jeremyevans)
+
+* Make remember, password reset, and lockout features work on non-PostgreSQL databases (jeremyevans)
+
+* Support authentication without database functions when password hashes are stored in separate table (jeremyevans)
+
+* Remove overriding of route/get/post blocks (jeremyevans)
+
+* Make lockout feature work on databases not supporting UPDATE RETURNING (jeremyevans)
+
+* Add timing safe comparison of tokens (jeremyevans)
+
 === 0.10.0 (2016-02-17)
 
 * Retrieve salt from database and compute hash client side, instead of computing hash on server (jeremyevans)

data/README.rdoc

@@ -1,6 +1,11 @@
 = Rodauth
 
-Rodauth is an authentication framework using Roda, Sequel, and PostgreSQL.
+Rodauth is an authentication and account management framework for
+rack applications.  It's built using Roda and Sequel, but it can
+be used with other web frameworks, database libraries, and databases.
+When used with PostgreSQL, MySQL, and Microsoft SQL Server in the
+default configuration, it offers additional security for password
+hashes by protecting access via database functions.
 
 == Design Goals
 
@@ -18,57 +23,100 @@ Rodauth is an authentication framework using Roda, Sequel, and PostgreSQL.
 * Create Account
 * Close Account
 * Verify Account
+* Confirm Password
 * Remember (Autologin via token)
 * Lockout (Bruteforce protection)
+* OTP (2 factor authentication via TOTP)
+* Recovery Codes (2 factor authentication via backup codes)
+* SMS Codes (2 factor authentication via SMS)
+* Verify Change Login (Reverify accounts after login changes)
+* 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)
+* Disallow Password Reuse
+* Password Expiration
+* Account Expiration
+* Session Expiration
+* Single Session (Only one active session per account)
+* JWT (JSON API support for all other features)
 
 == Resources
 
-RDoc :: http://rodauth.jeremyevans.net
+Website :: http://rodauth.jeremyevans.net
 Demo Site :: http://rodauth-demo.jeremyevans.net
 Source :: http://github.com/jeremyevans/rodauth
 Bugs :: http://github.com/jeremyevans/rodauth/issues
+Google Group :: https://groups.google.com/forum/#!forum/rodauth
+IRC :: irc://chat.freenode.net/#rodauth
+
+== Dependencies
+
+There are some dependencies that Rodauth uses by default, but are
+development dependencies instead of runtime dependencies in the
+gem as it is possible to run without them:
+
+tilt, rack_csrf :: Used by all features unless in JSON API only mode.
+bcrypt :: Used by default for password matching, can be skipped
+          if password_match? is overridden for custom authentication.
+mail :: Used by default for mailing in the reset password, verify
+        account, and lockout features.
+rotp, rqrcode :: Used by the otp feature
+jwt :: Used by the jwt feature
 
 == Security
 
-=== Passwords
+=== Password Hash Access Via Database Functions
+
+By default on PostgreSQL, MySQL, and Microsoft SQL Server, Rodauth
+uses database functions to access password hashes, with the user
+running the application unable to get direct access to password
+hashes.  This reduces the risk of an attacker being able to access
+password hashes and use them to attack other sites.
+
+The rest of this section describes this feature in more detail, but
+note that Rodauth does not require this feature be used and works
+correctly without it.  There may be cases where you cannot use
+this feature, such as when using a different database or when you
+do not have full control over the database you are using.
 
 Passwords are hashed using bcrypt, and the password hashes are
 kept in a separate table from the accounts table, with a foreign key
-referencing the accounts table.  Two PostgreSQL functions are added,
+referencing the accounts table.  Two database functions are added,
 one to retrieve the salt for a password, and the other to check
 if a given password hash matches the password hash for the user.
 
-A separate database account owns the table containing the password
-hashes, which the application database account cannot access.
-The application database account has the ability to execute the
-functions to get the salt and check the password hash, but not the
-ability to access the password hashes directly, making it much more
-difficult for an attacker to access the password hashes even if they
-are able to exploit an SQL injection or remote code execution
-vulnerability in the application.  Even if an attacker was able to
-exploit a vulnerability in the application, the only additional
-information they would have is the salt for the password, which
-is much less sensitive than the entire password hash.
-
-While the application database account is not be able to read
-password hashes, it is still be able to insert password hashes,
-update passwords hashes, and delete password hashes, so the
-additional security is not that painful.
+Two database accounts are used. The first is the account that the
+application uses, which is referred to as the +app+ account. The +app+
+account does not have access to read the password hashes. The other
+account handles password hashes and is referred to as the +ph+
+account.  The +ph+ account sets up the database functions that can
+retrieve the salt for a given account's password, and check if a
+password hash matches for for a given account.  The +ph+ account
+sets these functions up so that the +app+ account can execute the
+functions using the +ph+ account's permissions.  This allows the
++app+ account to check passwords without having access to read
+password hashes.
+
+While the +app+ account is not be able to read password hashes, it
+is still be able to insert password hashes, update passwords hashes,
+and delete password hashes, so the additional security is not that
+painful.
+
+By disallowing the +app+ account access to the password hashes,
+it is much more difficult for an attacker to access the password
+hashes, even if they are able to exploit an SQL injection or remote
+code execution vulnerability in the application.
 
 The reason for extra security in regards to password hashes stems from
-the fact that people tend to reuse passwords, so a compromise of one
-database containing password hashes can result in account access on
-other sites, making password hash storage of critical importance even
-if the other data stored is not that important.
+the fact that people tend to choose poor passwords and reuse passwords,
+so a compromise of one database containing password hashes can result
+in account access on other sites, making password hash storage of
+critical importance even if the other data stored is not that important.
 
-If you are storing other important information in your database, you
+If you are storing other sensitive information in your database, you
 should consider using a similar approach in other areas (or all areas)
 of your application.
 
-Rodauth can still be used if you are using a more conventional approach
-of storing the password hash in a column in the same table, with
-a single configuration setting.
-
 === Tokens
 
 Account verification, password resets, remember, and lockout tokens
@@ -79,18 +127,17 @@ for a single account, instead of being able to bruteforce tokens for
 all accounts at once (which would be possible if the token was just a
 random string).
 
-There is a maximum of 1 token per account for each of these features
-at a time. This prevents attackers from creating an arbitrary number
-of requests in order to make bruteforcing easier.
+Additionally, all comparisons of tokens use a timing-safe comparison
+function to reduce the risk of timing attacks.
 
-== Database Setup
+== PostgreSQL Database Setup
 
-In order to get full advantages of Rodauth's security design, multiple
-database accounts are involved:
+In order to get full advantages of Rodauth's security design on PostgreSQL,
+multiple database accounts are involved:
 
-1) database superuser account (usually postgres)
-2) application database account
-3) secondary database account
+1. database superuser account (usually postgres)
+2. +app+ account (same name as application)
+3. +ph+ account (application name with +_password+ appended)
 
 The database superuser account is used to load extensions related to the
 database.  The application should never be run using the database
@@ -109,42 +156,81 @@ citext extension if you want to support case insensitive logins.
 
 Example:
 
-  echo "CREATE EXTENSION citext" | psql -U postgres $database_name
+  psql -U postgres -c "CREATE EXTENSION citext" ${DATABASE_NAME}
 
 Note that on Heroku, this extension can be loaded using a standard database
-account.
+account.  If you don't want to support case sensitive logins, you don't
+need to use the PostgreSQL citext extension. Just remember to modify the
+migration below to use +String+ instead of +citext+ for the email.
 
 === Create database accounts
 
 If you are currently running your application using the database superuser
-account, the first thing you need to do is to create a database account for
-the application.  It's often best to name this account the same as the
+account, the first thing you need to do is to create the +app+ database
+account.  It's often best to name this account the same as the
 database name.
 
-You should also create a second database account which will own the password
-hash table.
+You should also create the +ph+ database account which will handle access
+to the password hashes.
 
-Example:
+Example for PostgreSQL:
 
-  createuser -U postgres $database_name
-  createuser -U postgres $database_name_password_hashes
+  createuser -U postgres ${DATABASE_NAME}
+  createuser -U postgres ${DATABASE_NAME}_password
 
 Note that if the database superuser account owns all of the items in the
 database, you'll need to change the ownership to the database account you
 just created.  See https://gist.github.com/jeremyevans/8483320
 for a way to do that.
 
-=== Create tables
+== MySQL Database Setup
+
+MySQL does not have the concept of object owners, and MySQL's GRANT/REVOKE
+support is much more limited than PostgreSQL's. When using MySQL, it is
+recommended to GRANT the +ph+ account ALL privileges on the database,
+including the ability to GRANT permissions to the +app+ account:
+
+  CREATE USER '${DATABASE_NAME}'@'localhost' IDENTIFIED BY '${PASSWORD}';
+  CREATE USER '${DATABASE_NAME}_password'@'localhost' IDENTIFIED BY '${OTHER_PASSWORD}';
+  GRANT ALL ON ${DATABASE_NAME}.* TO '${DATABASE_NAME}_password'@'localhost' WITH GRANT OPTION;
+
+You should run all migrations as the +ph+ account, and GRANT specific access
+to the +app+ account as needed.
+
+Adding the database functions on MySQL may require setting the 
+<tt>log_bin_trust_function_creators=1</tt> setting in the MySQL configuration.
+
+== Microsoft SQL Server Database Setup
+
+Microsoft SQL Server has a concept of database owners, but similar to MySQL
+usage it's recommended to use the +ph+ account as the superuser for the
+database, and have it GRANT permissions to the +app+ account:
+
+  CREATE LOGIN rodauth_test WITH PASSWORD = 'rodauth_test';
+  CREATE LOGIN rodauth_test_password WITH PASSWORD = 'rodauth_test';
+  CREATE DATABASE rodauth_test;
+  USE rodauth_test;
+  CREATE USER rodauth_test FOR LOGIN rodauth_test;
+  GRANT CONNECT, EXECUTE TO rodauth_test;
+  EXECUTE sp_changedbowner 'rodauth_test_password';
+
+You should run all migrations as the +ph+ account, and GRANT specific access
+to the +app+ account as needed.
+
+== Creating tables
 
 Because two different database accounts are used, two different migrations
 are required, one for each database account.  Here are example migrations.
 You can modify them to add support for additional columns, or remove tables
 or columns related to features that you don't need.
 
-First migration, run using the application database account:
+First migration.  On PostgreSQL, this should be run with the +app+ account,
+on MySQL and Microsoft SQL Server this should be run with the +ph+ account.
 
   Sequel.migration do
     up do
+      extension :date_arithmetic
+
       # Used by the account verification and close account features
       create_table(:account_statuses) do
         Integer :id, :primary_key=>true
@@ -152,35 +238,47 @@ First migration, run using the application database account:
       end
       from(:account_statuses).import([:id, :name], [[1, 'Unverified'], [2, 'Verified'], [3, 'Closed']])
 
-      # Used by the create account, account verification,
-      # and close account features.
+      db = self
       create_table(:accounts) do
         primary_key :id, :type=>Bignum
         foreign_key :status_id, :account_statuses, :null=>false, :default=>1
-        citext :email, :null=>false
+        if db.database_type == :postgres
+          citext :email, :null=>false
+          constraint :valid_email, :email=>/^[^,;@ \r\n]+@[^,@; \r\n]+\.[^,@; \r\n]+$/
+          index :email, :unique=>true, :where=>{:status_id=>[1, 2]}
+        else
+          String :email, :null=>false
+          index :email, :unique=>true
+        end
+      end
 
-        constraint :valid_email, :email=>/^[^,;@ \r\n]+@[^,@; \r\n]+\.[^,@; \r\n]+$/
-        index :email, :unique=>true, :where=>{:status_id=>[1, 2]}
+      deadline_opts = proc do |days|
+        if database_type == :mysql
+          {:null=>false}
+        else
+          {:null=>false, :default=>Sequel.date_add(Sequel::CURRENT_TIMESTAMP, :days=>days)}
+        end
       end
 
       # Used by the password reset feature
       create_table(:account_password_reset_keys) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
         String :key, :null=>false
-        DateTime :deadline, :null=>false, :default=>Sequel.lit("CURRENT_TIMESTAMP + '1 day'")
+        DateTime :deadline, deadline_opts[1]
       end
 
       # Used by the account verification feature
       create_table(:account_verification_keys) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
         String :key, :null=>false
+        DateTime :requested_at, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
       end
 
       # Used by the remember me feature
       create_table(:account_remember_keys) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
         String :key, :null=>false
-        DateTime :deadline, :null=>false, :default=>Sequel.lit("CURRENT_TIMESTAMP + '2 weeks'")
+        DateTime :deadline, deadline_opts[14]
       end
 
       # Used by the lockout feature
@@ -191,81 +289,183 @@ First migration, run using the application database account:
       create_table(:account_lockouts) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
         String :key, :null=>false
-        DateTime :deadline, :null=>false, :default=>Sequel.lit("CURRENT_TIMESTAMP + '1 day'")
+        DateTime :deadline, deadline_opts[1]
+      end
+
+      # Used by the password expiration feature
+      create_table(:account_password_change_times) do
+        foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
+        DateTime :changed_at, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
+      end
+
+      # Used by the account expiration feature
+      create_table(:account_activity_times) do
+        foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
+        DateTime :last_activity_at, :null=>false
+        DateTime :last_login_at, :null=>false
+        DateTime :expired_at
+      end
+
+      # Used by the single session feature
+      create_table(:account_session_keys) do
+        foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
+        String :key, :null=>false
+      end
+
+      # Used by the otp feature
+      create_table(:account_otp_keys) do
+        foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
+        String :key, :null=>false
+        Integer :num_failures, :null=>false, :default=>0
+        Time :last_use, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
       end
 
-      # Grant password user access to reference accounts
-      pw_user = get{Sequel.lit('current_user')} + '_password'
-      run "GRANT REFERENCES ON accounts TO #{pw_user}"
+      # Used by the recovery codes feature
+      create_table(:account_recovery_codes) do
+        foreign_key :id, :accounts, :type=>Bignum
+        String :code
+        primary_key [:id, :code]
+      end
+
+      # Used by the sms codes feature
+      create_table(:account_sms_codes) do
+        foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
+        String :phone_number, :null=>false
+        Integer :num_failures
+        String :code
+        DateTime :code_issued_at, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
+      end
+
+      case database_type
+      when :postgres
+        user = get{Sequel.lit('current_user')} + '_password'
+        run "GRANT REFERENCES ON accounts TO #{user}"
+      when :mysql, :mssql
+        user = if database_type == :mysql
+          get{Sequel.lit('current_user')}.sub(/_password@/, '@')
+        else
+          get{DB_NAME{}}
+        end
+        run "GRANT ALL ON account_statuses TO #{user}"
+        run "GRANT ALL ON accounts TO #{user}"
+        run "GRANT ALL ON account_password_reset_keys TO #{user}"
+        run "GRANT ALL ON account_verification_keys TO #{user}"
+        run "GRANT ALL ON account_remember_keys TO #{user}"
+        run "GRANT ALL ON account_login_failures TO #{user}"
+        run "GRANT ALL ON account_lockouts TO #{user}"
+        run "GRANT ALL ON account_password_change_times TO #{user}"
+        run "GRANT ALL ON account_activity_times TO #{user}"
+        run "GRANT ALL ON account_session_keys TO #{user}"
+        run "GRANT ALL ON account_otp_keys TO #{user}"
+        run "GRANT ALL ON account_recovery_codes TO #{user}"
+        run "GRANT ALL ON account_sms_codes TO #{user}"
+      end
     end
 
     down do
-      drop_table(:account_lockouts, :account_login_failures, :account_remember_keys,
-        :account_verification_keys, :account_password_reset_keys, :accounts, :account_statuses)
+      drop_table(:account_sms_codes,
+                 :account_recovery_codes,
+                 :account_otp_keys,
+                 :account_session_keys,
+                 :account_activity_times,
+                 :account_password_change_times,
+                 :account_lockouts,
+                 :account_login_failures,
+                 :account_remember_keys,
+                 :account_verification_keys,
+                 :account_password_reset_keys,
+                 :accounts,
+                 :account_statuses)
     end
   end
 
-Second migration, run using the secondary database account:
+Second migration, run using the +ph+ account:
+
+  require 'rodauth/migrations'
 
   Sequel.migration do
     up do
-      # Used by the login and change password features
       create_table(:account_password_hashes) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>Bignum
         String :password_hash, :null=>false
       end
+      Rodauth.create_database_authentication_functions(self)
+      case database_type
+      when :postgres
+        user = get{Sequel.lit('current_user')}.sub(/_password\z/, '')
+        run "REVOKE ALL ON account_password_hashes FROM public"
+        run "REVOKE ALL ON FUNCTION rodauth_get_salt(int8) FROM public"
+        run "REVOKE ALL ON FUNCTION rodauth_valid_password_hash(int8, text) FROM public"
+        run "GRANT INSERT, UPDATE, DELETE ON account_password_hashes TO #{user}"
+        run "GRANT SELECT(id) ON account_password_hashes TO #{user}"
+        run "GRANT EXECUTE ON FUNCTION rodauth_get_salt(int8) TO #{user}"
+        run "GRANT EXECUTE ON FUNCTION rodauth_valid_password_hash(int8, text) TO #{user}"
+      when :mysql
+        user = get{Sequel.lit('current_user')}.sub(/_password@/, '@')
+        db_name = get{database{}}
+        run "GRANT EXECUTE ON #{db_name}.* TO #{user}"
+        run "GRANT INSERT, UPDATE, DELETE ON account_password_hashes TO #{user}"
+        run "GRANT SELECT (id) ON account_password_hashes TO #{user}"
+      when :mssql
+        user = get{DB_NAME{}}
+        run "GRANT EXECUTE ON rodauth_get_salt TO #{user}"
+        run "GRANT EXECUTE ON rodauth_valid_password_hash TO #{user}"
+        run "GRANT INSERT, UPDATE, DELETE ON account_password_hashes TO #{user}"
+        run "GRANT SELECT ON account_password_hashes(id) TO #{user}"
+      end
 
-      # Function that returns salt for current password.
-      run <<END
-  CREATE OR REPLACE FUNCTION rodauth_get_salt(account_id int8) RETURNS text AS $$
-  DECLARE salt text;
-  BEGIN
-  SELECT substr(password_hash, 0, 30) INTO salt 
-  FROM account_password_hashes
-  WHERE account_id = id;
-  RETURN salt;
-  END;
-  $$ LANGUAGE plpgsql
-  SECURITY DEFINER
-  SET search_path = public, pg_temp;
-  END
-
-      # Function that checks if password hash is valid for given user.
-      run <<END
-  CREATE OR REPLACE FUNCTION rodauth_valid_password_hash(account_id int8, hash text) RETURNS boolean AS $$
-  DECLARE valid boolean;
-  BEGIN
-  SELECT password_hash = hash INTO valid 
-  FROM account_password_hashes
-  WHERE account_id = id;
-  RETURN valid;
-  END;
-  $$ LANGUAGE plpgsql
-  SECURITY DEFINER
-  SET search_path = public, pg_temp;
-  END
-
-      # Restrict access to the password hash table
-      app_user = get{Sequel.lit('current_user')}.sub(/_password\z/, '')
-      run "REVOKE ALL ON account_password_hashes FROM public"
-      run "REVOKE ALL ON FUNCTION rodauth_get_salt(int8) FROM public"
-      run "REVOKE ALL ON FUNCTION rodauth_valid_password_hash(int8, text) FROM public"
-      run "GRANT INSERT, UPDATE, DELETE ON account_password_hashes TO #{app_user}"
-      run "GRANT SELECT(id) ON account_password_hashes TO #{app_user}"
-      run "GRANT EXECUTE ON FUNCTION rodauth_get_salt(int8) TO #{app_user}"
-      run "GRANT EXECUTE ON FUNCTION rodauth_valid_password_hash(int8, text) TO #{app_user}"
+      # Used by the disallow_password_reuse feature
+      create_table(:account_previous_password_hashes) do
+        primary_key :id, :type=>Bignum
+        foreign_key :account_id, :accounts, :type=>Bignum
+        String :password_hash, :null=>false
+      end
+      Rodauth.create_database_previous_password_check_functions(self)
+
+      case database_type
+      when :postgres
+        user = get{Sequel.lit('current_user')}.sub(/_password\z/, '')
+        run "REVOKE ALL ON account_previous_password_hashes FROM public"
+        run "REVOKE ALL ON FUNCTION rodauth_get_previous_salt(int8) FROM public"
+        run "REVOKE ALL ON FUNCTION rodauth_previous_password_hash_match(int8, text) FROM public"
+        run "GRANT INSERT, UPDATE, DELETE ON account_previous_password_hashes TO #{user}"
+        run "GRANT SELECT(id, account_id) ON account_previous_password_hashes TO #{user}"
+        run "GRANT USAGE ON account_previous_password_hashes_id_seq TO #{user}"
+        run "GRANT EXECUTE ON FUNCTION rodauth_get_previous_salt(int8) TO #{user}"
+        run "GRANT EXECUTE ON FUNCTION rodauth_previous_password_hash_match(int8, text) TO #{user}"
+      when :mysql
+        user = get{Sequel.lit('current_user')}.sub(/_password@/, '@')
+        db_name = get{database{}}
+        run "GRANT EXECUTE ON #{db_name}.* TO #{user}"
+        run "GRANT INSERT, UPDATE, DELETE ON account_previous_password_hashes TO #{user}"
+        run "GRANT SELECT (id, account_id) ON account_previous_password_hashes TO #{user}"
+      when :mssql
+        user = get{DB_NAME{}}
+        run "GRANT EXECUTE ON rodauth_get_previous_salt TO #{user}"
+        run "GRANT EXECUTE ON rodauth_previous_password_hash_match TO #{user}"
+        run "GRANT INSERT, UPDATE, DELETE ON account_previous_password_hashes TO #{user}"
+        run "GRANT SELECT ON account_previous_password_hashes(id, account_id) TO #{user}"
+      end
     end
 
     down do
-      run "DROP FUNCTION rodauth_get_salt(int8)"
-      run "DROP FUNCTION rodauth_valid_password_hash(int8, text)"
-      drop_table(:account_password_hashes)
+      Rodauth.drop_database_previous_password_check_functions(self)
+      Rodauth.drop_database_authentication_functions(self)
+      drop_table(:account_previous_password_hashes, :account_password_hashes)
     end
   end
 
-If you are using a non-PostgreSQL database or cannot use multiple user
-accounts, just combine the two migrations into a single migration and
-exclude the GRANT/REVOKE statements.
+To support multiple separate migration users, you can run the migration
+for the password user using Sequel's migration API: 
+
+  Sequel.extension :migration
+  Sequel.postgres('DATABASE_NAME', :user=>'PASSWORD_USER_NAME') do |db|
+    Sequel::Migrator.run(db, 'path/to/password_user/migrations', :table=>'schema_info_password')
+  end
+
+If the database is not PostgreSQL, MySQL, or Microsoft SQL Server, or you
+cannot use multiple user accounts, just combine the two migrations into a
+single migration.
 
 One thing to notice in the above migrations is that Rodauth uses additional
 tables for additional features, instead of additional columns in a single
@@ -282,7 +482,7 @@ are loaded:
   end
 
 The block passed to the plugin call uses the Rodauth configuration DSL.
-The one configuration method that should always be used is enable,
+The one configuration method that should always be used is +enable+,
 which chooses which features you would like to load:
 
   plugin :rodauth do
@@ -290,17 +490,18 @@ which chooses which features you would like to load:
   end
 
 Once features are loaded, you can use any of the configuration methods
-supported by the features.  There are three types of configuration
+supported by the features.  There are two types of configuration
 methods.  The first type are called auth methods, and they take a
-block, and overrides the default method that Rodauth uses.  Inside the
-block, you can call super if you want to get the default behavior.  For
-example, if you want to add additional logging when a user logs in:
+block which overrides the default method that Rodauth uses.  Inside the
+block, you can call super if you want to get the default behavior, though
+you must provide explicit arguments to super.  There is no need to
+call super in before or after hooks, though. For example, if you want to
+add additional logging when a user logs in:
 
   plugin :rodauth do
     enable :login, :logout
     after_login do
-      logger.info "#{account.email} logged in!"
-      super
+      LOGGER.info "#{account.email} logged in!"
     end
   end
 
@@ -320,8 +521,7 @@ So if you want to log the IP address for the user during login:
   plugin :rodauth do
     enable :login, :logout
     after_login do
-      logger.info "#{account.email} logged in from #{request.ip}"
-      super
+      LOGGER.info "#{account.email} logged in from #{request.ip}"
     end
   end
 
@@ -329,33 +529,22 @@ The second type of configuration methods are called auth value
 methods.  They are similar to auth methods, but instead of just
 accepting a block, they can optionally accept a single argument
 without a block, which will be treated as a block that just returns
-that value.  For example, the account_model method sets the model
-class to use for the account, so to override it, you can call the
-method with another class:
+that value.  For example, the accounts_table method sets the database
+table storing accounts, so to override it, you can call the method
+with a symbol for the table:
 
   plugin :rodauth do
     enable :login, :logout
-    account_model User
-  end
-
-The third type of configuration methods are called auth block methods,
-and there are three of them per feature, one for handling the route
-itself, one for handling just the GET route, and one for handling just
-the POST route.  For the login feature, login_route_block would set
-the routing block to use if the login route matches, login_get_block
-would set the routing block to use if the login route matches and it
-is a GET request, and login_post_block would set the routing block to
-use if the login route matches and it is a POST request.  As auth block
-methods specify the route blocks, they are executed in the context
-of the Roda instance, and are passed two arguments, the first being the
-RodaRequest instance, and the second being the Rodauth::Auth instance.
-For example, if you wanted to override how a POST request to the login
-route is handled:
+    accounts_table :users
+  end
+
+Note that all auth value methods can still take a block, allowing
+overriding for all behavior, using any information from the request:
 
   plugin :rodauth do
-    enable :login
-    login_post_route do |r, auth|
-      # ...
+    enable :login, :logout
+    accounts_table do
+      request.ip.start_with?("192.168.1") ? :admins : :users
     end
   end
 
@@ -369,6 +558,9 @@ separate page per feature.  If these links are not active, please
 view the appropriate file in the doc directory.
 
 * {Base}[rdoc-ref:doc/base.rdoc] (this feature is autoloaded)
+* {Login Password Requirements Base}[rdoc-ref:doc/login_password_requirements_base.rdoc] (this feature is autoloaded by features that set logins/passwords)
+* {Email Base}[rdoc-ref:doc/email_base.rdoc] (this feature is autoloaded by features that send email)
+* {Two Factor Base}[rdoc-ref:doc/two_factor_base.rdoc] (this feature is autoloaded by 2 factor authentication features)
 * {Login}[rdoc-ref:doc/login.rdoc]
 * {Logout}[rdoc-ref:doc/logout.rdoc]
 * {Change Password}[rdoc-ref:doc/change_password.rdoc]
@@ -377,13 +569,81 @@ view the appropriate file in the doc directory.
 * {Create Account}[rdoc-ref:doc/create_account.rdoc]
 * {Close Account}[rdoc-ref:doc/close_account.rdoc]
 * {Verify Account}[rdoc-ref:doc/verify_account.rdoc]
+* {Confirm Password}[rdoc-ref:doc/confirm_password.rdoc]
 * {Remember}[rdoc-ref:doc/remember.rdoc]
 * {Lockout}[rdoc-ref:doc/lockout.rdoc]
+* {OTP}[rdoc-ref:doc/otp.rdoc]
+* {Recovery Codes}[rdoc-ref:doc/recovery_codes.rdoc]
+* {SMS Codes}[rdoc-ref:doc/sms_codes.rdoc]
+* {Verify Change Login}[rdoc-ref:doc/verify_change_login.rdoc]
+* {Verify Account Grace Period}[rdoc-ref:doc/verify_account_grace_period.rdoc]
+* {Password Grace Period}[rdoc-ref:doc/password_grace_period.rdoc]
+* {Password Complexity}[rdoc-ref:doc/password_complexity.rdoc]
+* {Disallow Password Reuse}[rdoc-ref:doc/disallow_password_reuse.rdoc]
+* {Password Expiration}[rdoc-ref:doc/password_expiration.rdoc]
+* {Account Expiration}[rdoc-ref:doc/account_expiration.rdoc]
+* {Session Expiration}[rdoc-ref:doc/session_expiration.rdoc]
+* {Single Session}[rdoc-ref:doc/single_session.rdoc]
+* {JWT}[rdoc-ref:doc/jwt.rdoc]
+
+=== Calling Rodauth in the Routing Tree
+
+In general, you will usually want to call rodauth early in your
+route block:
+
+  route do |r|
+    r.rodauth
+
+    # ...
+  end
+
+Note that will allow Rodauth to run, but it won't force people
+to login or add any security to your site.  If you want to force
+all users to login, you need to redirect to them login page if
+they are not already logged in:
+
+  route do |r|
+    r.rodauth
+    rodauth.require_authentication
+
+    # ...
+  end
+
+If only certain parts of your site require logins, then you can
+only redirect if they are not logged in certain branches of the
+routing tree:
+
+  route do |r|
+    r.rodauth
+
+    r.on "admin" do
+      rodauth.require_authentication
+
+      # ...
+    end
+
+    # ...
+  end
+
+In some cases you may want to have rodauth run inside a branch of
+the routing tree, instead of in the root.  You can do this by
+setting a +:prefix+ when configuring Rodauth, and calling +r.rodauth+
+inside a matching routing tree branch:
 
-Since the auth block methods work the same way for each of these
-features, they are not documented on the feature pages. Additionally,
-all features have a before auth method (e.g. before_login) that is
-called before either the GET or POST route blocks are handled.
+  plugin :rodauth do
+    enable :login, :logout
+    prefix "auth"
+  end
+
+  route do |r|
+    r.on "auth" do
+      r.rodauth
+    end
+
+    rodauth.require_authentication
+
+    # ...
+  end
 
 === With Multiple Configurations
 
@@ -407,26 +667,79 @@ the name as an argument to use that configuration:
     r.rodauth
   end
 
-=== With Other Databases
+=== With Password Hashes Inside the Accounts Table
 
-You can use Rodauth with other databases besides PostgreSQL. Assuming
-you are storing the password hashes in the same table as the account
-information, you can just do:
+You can use Rodauth if you are storing password hashes in the same
+table as the accounts.  You just need to specify which column
+stores the password hash:
 
   plugin :rodauth do
     account_password_hash_column :password_hash
   end
 
-When this option is set, Rodauth will not use a database function
-to authenticate, it will do the check in ruby.  This feature can
-also be used if you are using PostgreSQL, but for legacy reasons
-are storing the password hashes in the same table as the account
-information.
+When this option is set, Rodauth will do the password hash check
+in ruby.
+  
+=== When Using PostgreSQL/MySQL/Microsoft SQL Server without Database Functions
+
+If you want to use Rodauth on PostgreSQL, MySQL, or Microsoft SQL Server
+without using database functions for authentication, but still storing password
+hashes in a separate table, you can do so:
+
+  plugin :rodauth do
+    use_database_authentication_functions? false
+  end
 
-The Rodauth lockout feature also uses UPDATE RETURNING to update
-a row and return the new value, so if you are not using PostgreSQL
-and wish to use the lockout feature, you'll need to override the
-invalid_login_attempted method.
+Conversely, if you implement the rodauth_get_salt and
+rodauth_valid_password_hash functions on a database that isn't
+PostgreSQL, MySQL, or Microsoft SQL Server, you can set this value to true.
+
+=== With Custom Authentication (such as LDAP)
+
+You can use Rodauth with other authentication types, by overriding
+a single configuration setting.  For example, if you have accounts
+stored in the database, but authentication happens via LDAP, you
+can use the +simple_ldap_authenticator+ library:
+
+  require 'simple_ldap_authenticator'
+  plugin :rodauth do
+    enable :login, :logout
+    require_bcrypt? false
+    password_match? do |password|
+      SimpleLdapAuthenticator.valid?(account.username, password)
+    end
+  end
+
+If you aren't storing accounts in the database, but want to allow
+any valid LDAP user to login, you can do something like this:
+
+  require 'simple_ldap_authenticator'
+  plugin :rodauth do
+    enable :login, :logout
+
+    # Don't require the bcrypt library, since using LDAP for auth
+    require_bcrypt? false
+
+    # Treat the login itself as the account
+    account_from_login{|l| l.to_s}
+
+    # Use the login provided as the session value
+    account_session_value{account}
+
+    # Store session value in :login key, since the :account_id
+    # default wouldn't make sense
+    session_key :login
+
+    password_match? do |password|
+      SimpleLdapAuthenticator.valid?(account, password)
+    end
+  end
+
+Note that when using custom authentication, using some of Rodauth's
+features such as change login and change password either would not
+make sense or would require some additional custom configuration.
+The login and logout features should work correctly with the examples
+above, though.
 
 === With Other Web Frameworks
 
@@ -438,47 +751,192 @@ Rodauth:
 
   class RodauthApp < Roda
     plugin :middleware
-    plugin :rodauth
+    plugin :rodauth do
+      enable :login
+    end
+
     route do |r|
       r.rodauth
+      env['rodauth'] = rodauth
+      rodauth.require_authentication
     end
   end
 
   use RodauthApp
 
+Note that Rodauth expects the Roda app it is used in to provide a
+layout.  So if you are using Rodauth as middleware for another app,
+if you don't have a +views/layout.erb+ file that Rodauth can use,
+you should probably also add load Roda's +render+ plugin
+with the appropriate settings that allow Rodauth to use the same
+layout as the application.
+
+By setting <tt>env['rodauth'] = rodauth</tt> in the route block
+inside the middleware, you can easily provide a way for your
+application to call Rodauth methods.
+
+For an example of integrating Rodauth into a real application that
+doesn't use Roda, see
+{this example integrating Rodauth into Ginatra, a Sinatra-based git repository viewer}[https://github.com/jeremyevans/ginatra/commit/28108ebec96e8d42596ee55b01c3f7b50c155dd1].
+
+=== Using 2 Factor Authentication
+
+Rodauth ships with 2 factor authentication support via TOTP (Time-Based
+One-Time Passwords, RFC 6238).  There are a wide variety of ways in
+which to integrate 2 factor authentication into your site with Rodauth,
+based on the needs of the application.
+
+The 2 factor authentication support is part of the OTP feature, which
+needs to be enabled in addition to the login feature.  In addition,
+when implementing 2 factor authentication, you should generally
+provide a backup 2nd factor if the primary second factor is not
+available.  Rodauth supports SMS codes and recovery codes as other
+2nd factors.
+
+If you want to support but not require 2 factor authentication:
+
+  plugin :rodauth do
+    enable :login, :logout, :otp, :recovery_codes, :sms_codes
+  end
+  route do |r|
+    r.rodauth
+    rodauth.require_authentication
+
+    # ...
+  end
+
+If you want to force all users to use OTP authentication, requiring users
+that don't currently have an account to set one up:
+
+  route do |r|
+    r.rodauth
+    rodauth.require_authentication
+    rodauth.require_two_factor_authentication_setup
+
+    # ...
+  end
+
+Similarly to requiring authentication in general, it's possible to require
+login authentication for most of the site, but require 2 factor
+authentication only for particular branches:
+
+  route do |r|
+    r.rodauth
+    rodauth.require_login
+
+    r.on "admin" do
+      rodauth.require_two_factor_authenticated
+    end
+
+    # ...
+  end
+
+== JSON API Support
+
+To add support for handling JSON responses, you can pass the +:json+
+option to the plugin, and enable the JWT feature in addition to
+other features you plan to use:
+
+  plugin :rodauth, :json=>true do
+    enable :login, :logout, :jwt
+  end
+
+If you do not want to load the HTML plugins that Rodauth usually loads
+(render, csrf, flash, h), because you are building a JSON-only API,
+pass <tt>:json => :only</tt>
+
+  plugin :rodauth, :json=>:only do
+    enable :login, :logout, :jwt
+  end
+
+Note that by default, the features that send email depend on the
+render plugin, so if using the <tt>:json=>:only</tt> option, you
+either need to load the render plugin manually or you need to
+use the necessary *_email_body configuration options to specify
+the body of the emails.
+
+The JWT feature enables JSON API support for all of the other features
+that Rodauth ships with.
+
+=== Adding Custom Methods to the +rodauth+ Object
+
+Inside the configuration block, you can use +auth_class_eval+ to add
+custom methods that will be callable on the +rodauth+ object.
+
+  plugin :rodauth do
+    enable :login
+
+    auth_class_eval do
+      def require_admin
+        request.redirect("/") unless account[:admin]
+      end
+    end
+  end
+
+  route do |r|
+    r.rodauth
+
+    r.on "admin"
+      rodauth.require_admin
+    end
+  end
+
 === Using External Features
 
 The enable configuration method is able to load features external to
 Rodauth.  You need to place the external feature file where it can be
-required via roda/plugins/rodauth/feature_name. That file should
+required via rodauth/features/feature_name. That file should
 use the following basic structure
 
-  class Roda
-    module RodaPlugins
-      module Rodauth
-        # :feature_name will be the argument given to enable to
-        # load the feature
-        FeatureName = Feature.define(:feature_name) do
-          auth_value_methods # one argument per auth value method
-          auth_methods # one argument per auth method
-
-          get_block do |r, auth|
-            # r is the RodaRequest instance
-            # auth is the Rodauth::Auth instance
-            # This block is evaluated in the scope of the Roda instance
-            # ...
-          end
-
-          post_block do |r, auth|
-            # ...
-          end
-
-          # define the default behavior for the auth methods
-          # and auth value methods
-          # ...
+  module Rodauth
+    # :feature_name will be the argument given to enable to
+    # load the feature
+    FeatureName = Feature.define(:feature_name) do
+      # Shortcut for defining auth value methods with static values
+      auth_value_method :method_name, 1 # method_value
+
+      auth_value_methods # one argument per auth value method
+
+      auth_methods # one argument per auth method
+ 
+      route do |r|
+        # This block is taken for requests to the feature's route.
+        # This block is evaluated in the scope of the Rodauth::Auth instance.
+        # r is the Roda::RodaRequest instance for the request
+        
+        r.get do
+        end
+
+        r.post do
         end
       end
+
+      configuration_eval do
+        # define additional configuration specific methods here, if any
+      end
+
+      # define the default behavior for the auth_methods
+      # and auth_value_methods
+      # ...
+    end
+  end
+
+See the source code for the features that ship with Rodauth for an
+example of how to construct features.
+
+=== Overriding Route-Level Behavior
+
+All of Rodauth's configuration methods change the behavior of the
+Rodauth::Auth instance.  However, in some cases you may want to
+overriding handling at the routing layer.  You can do this easily
+by adding an appropriate route before calling +r.rodauth+:
+
+  route do |r|
+    r.post 'login' do
+      # Custom POST /login handling here
     end
+
+    r.rodauth
   end
 
 == Upgrading from 0.9.x
@@ -489,47 +947,13 @@ it and add the two database functions listed in the migration
 section above.  You can add the following code to a migration to
 accomplish that:
 
+  require 'rodauth/migrations'
   run "DROP FUNCTION account_valid_password(int8, text);"
-  
-  run <<END
-  CREATE OR REPLACE FUNCTION rodauth_get_salt(account_id int8) RETURNS text AS $$
-  DECLARE salt text;
-  BEGIN
-  SELECT substr(password_hash, 0, 30) INTO salt 
-  FROM account_password_hashes
-  WHERE account_id = id;
-  RETURN salt;
-  END;
-  $$ LANGUAGE plpgsql
-  SECURITY DEFINER
-  SET search_path = public, pg_temp;
-  END
-
-  run <<END
-  CREATE OR REPLACE FUNCTION rodauth_valid_password_hash(account_id int8, hash text) RETURNS boolean AS $$
-  DECLARE valid boolean;
-  BEGIN
-  SELECT password_hash = hash INTO valid 
-  FROM account_password_hashes
-  WHERE account_id = id;
-  RETURN valid;
-  END;
-  $$ LANGUAGE plpgsql
-  SECURITY DEFINER
-  SET search_path = public, pg_temp;
-  END
-
-  # Restrict access to the password hash table
-  app_user = get{Sequel.lit('current_user')}.sub(/_password\z/, '')
+  Rodauth.create_database_authentication_functions(self)
   run "REVOKE ALL ON FUNCTION rodauth_get_salt(int8) FROM public"
   run "REVOKE ALL ON FUNCTION rodauth_valid_password_hash(int8, text) FROM public"
-  run "GRANT EXECUTE ON FUNCTION rodauth_get_salt(int8) TO #{app_user}"
-  run "GRANT EXECUTE ON FUNCTION rodauth_valid_password_hash(int8, text) TO #{app_user}"
-
-== Possible Future Directions
-
-* OmniAuth support.  This is not something I plan to work on myself,
-  but I will consider patches that add it.
+  run "GRANT EXECUTE ON FUNCTION rodauth_get_salt(int8) TO ${DATABASE_NAME}"
+  run "GRANT EXECUTE ON FUNCTION rodauth_valid_password_hash(int8, text) TO ${DATABASE_NAME}"
 
 == Similar Projects