rodauth 2.36.0 → 2.37.0

data/doc/guides/password_confirmation.rdoc

@@ -1,37 +0,0 @@
-= 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

data/doc/guides/password_requirements.rdoc

@@ -1,43 +0,0 @@
-= Customize password requirements
-
-By default, Rodauth requires passwords to have at least 6 characters. You can
-modify the minimum and maximum length:
-
-  plugin :rodauth do
-    enable :login, :logout, :create_account
-
-    # Require passwords to have at least 8 characters
-    password_minimum_length 8
-
-    # Don't allow passwords to be too long, to prevent long password DoS attacks
-    password_maximum_length 64
-  end
-
-You can use the {disallow common passwords feature}[rdoc-ref:doc/disallow_common_passwords.rdoc]
-to prevent the usage of common passwords (the most common 10,000 by default).
-
-You can use additional complexity checks on passwords via the {password
-complexity feature}[rdoc-ref:doc/password_complexity.rdoc], though most of
-those complexity checks are no longer considered modern security best
-practices and are likely to decrease overall security.
-
-If you want complete control over whether passwords meet requirements, you
-can use the <tt>password_meets_requirements?</tt> configuration method.
-
-  plugin :rodauth do
-    enable :login, :logout, :create_account
-
-    password_meets_requirements? do |password|
-      super(password) && password_complex_enough?(password)
-    end
-
-    auth_class_eval do
-      # If password doesn't pass custom validation, add field error with error
-      # reason, and return false.
-      def password_complex_enough?(password)
-        return true if password.match?(/\d/) && password.match?(/[^a-zA-Z\d]/)
-        set_password_requirement_error_message(:password_simple, "requires one number and one special character")
-        false
-      end
-    end
-  end

data/doc/guides/paths.rdoc

@@ -1,51 +0,0 @@
-= Change route path
-
-You can change the URL path of any Rodauth route by overriding the
-corresponding <tt>*_route</tt> method:
-
-  plugin :rodauth do
-    enable :login, :logout, :create_account, :reset_password
-
-    # Change login route to "/signin"
-    login_route "signin"
-    
-    # Change redirect when login is required to "/signin"
-    require_login_redirect { login_path }
-
-    # Change create account route to "/register"
-    create_account_route "register"
-
-    # Change password reset request route to "/reset-password/request"
-    reset_password_request_route "reset-password/request"
-  end
-
-If you want to add a prefix to all Rodauth routes, you should use the +prefix+
-setting:
-
-  plugin :rodauth do
-    enable :login, :logout
-
-    # Use /auth prefix to each Rodauth route
-    prefix "/auth"
-  end
-
-  route do |r|
-    r.on "auth" do
-      # Serve Rodauth routes under the /auth branch of the routing tree
-      r.rodauth
-    end
-
-    # ...
-  end
-
-There are cases where you may want to disable certain routes. For example, you
-may want to enable the create_account feature to allow creating admins, but
-only make it possible programmatically via internal requests. In this case,
-you should set the corresponding <tt>*_route</tt> method to +nil+:
-
-  plugin :rodauth, name: :admin do
-    enable :create_account
-
-    # disable the /create-account route
-    create_account_route nil
-  end

data/doc/guides/query_params.rdoc

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

data/doc/guides/redirects.rdoc

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

data/doc/guides/registration_field.rdoc

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

data/doc/guides/render_confirmation.rdoc

@@ -1,17 +0,0 @@
-= Render confirmation view
-
-Most Rodauth actions redirect and display a flash notice after they're successfully performed. However, in some cases you may wish to render a view confirming that the action was successful, for nicer user experience.
-
-For example, when the user creates an account, you might render a page with a call to action to verify their account. Assuming you've created an +account_created+ view template alongside your other Rodauth templates, you can configure the following:
-
-  after_create_account do
-    # render "account_created" view template with page title of "Account created!"
-    return_response view("account_created", "Account created!")
-  end
-
-Similarly, when the user has requested a password reset, you can render a page telling them to check their email:
-
-  after_reset_password_request do
-    # render "password_reset_sent" view template with page title of "Password sent!"
-    return_response view("password_reset_sent", "Password sent!")
-  end

data/doc/guides/require_mfa.rdoc

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

data/doc/guides/reset_password_autologin.rdoc

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

data/doc/guides/share_configuration.rdoc

@@ -1,34 +0,0 @@
-= Share configuration via inheritance
-
-If you have multiple configurations that needs to share some amount of
-authentication behaviour, you can do so through inheritance. For example:
-
-  require "rodauth"
-
-  class RodauthBase < Rodauth::Auth
-    configure do
-      # common authentication configuration
-    end
-  end
-
-  class RodauthMain < RodauthBase # inherit common configuration
-    configure do
-      # main-specific authentication configuration
-    end
-  end
-
-  class RodauthAdmin < RodauthBase # inherit common configuration
-    configure do
-      # admin-specific authentication configuration
-    end
-  end
-
-  class RodauthApp < Roda
-    plugin :rodauth, auth_class: RodauthMain
-    plugin :rodauth, auth_class: RodauthAdmin, name: :admin
-    # ...
-  end
-
-However, when doing this, you need to be careful that you do not use a
-configuration method in a superclass, and then load a feature in a subclass
-that overrides the configuration you set in the superclass.

data/doc/guides/status_column.rdoc

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

data/doc/guides/totp_or_recovery.rdoc

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

data/doc/http_basic_auth.rdoc

@@ -1,18 +0,0 @@
-= Documentation for HTTP Basic Auth Feature
-
-The HTTP basic auth feature allows logins using HTTP basic authentication,
-described in RFC 1945.
-
-In your routing block, you can require HTTP basic authentication via:
-
-  rodauth.require_http_basic_auth
-
-If you want to allow HTTP basic authentication but not require it, you can
-call:
-
-  rodauth.http_basic_auth
-
-== Auth Value Methods
-
-http_basic_auth_realm :: The realm to return in the WWW-Authenticate header.
-require_http_basic_auth? :: If true, when +rodauth.require_login+ or +rodauth.require_authentication+ is used, return a 401 status page if basic auth has not been provided, instead of redirecting to the login page. If false, +rodauth.require_login+ or +rodauth.require_authentication+ will check for HTTP basic authentication if not already logged in.  False by default.