rodauth 1.23.0 → 2.4.0

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

data/doc/guides/password_requirements.rdoc

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

data/doc/guides/paths.rdoc

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

data/doc/guides/query_params.rdoc

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

data/doc/guides/redirects.rdoc

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

data/doc/guides/registration_field.rdoc

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

data/doc/guides/require_mfa.rdoc

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

data/doc/guides/reset_password_autologin.rdoc

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

data/doc/guides/status_column.rdoc

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

data/doc/guides/totp_or_recovery.rdoc

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

data/doc/http_basic_auth.rdoc

@@ -3,7 +3,16 @@
 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_authentication+ is used, return a 401 status if basic auth has not been provided, instead of redirecting to the login page. False by default.
+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.

data/doc/jwt.rdoc

@@ -2,7 +2,7 @@
 
 The jwt feature adds support for JSON API access for all other features
 that ship with Rodauth, using JWT (JSON Web Tokens) to hold the
-authentication data.
+session information.
 
 When this feature is used, all other features become accessible via a
 JSON API.  The JSON API uses the POST method for all requests, using
@@ -10,10 +10,10 @@ the same parameter names as the features uses.  JSON API requests to
 Rodauth endpoints that use a method other than POST will result in a
 405 Method Not Allowed response.
 
-Responses are returned as JSON hashes.  In case of an error, the "error"
-entry is set to an error message, and the "field-error" entry is set to
+Responses are returned as JSON hashes.  In case of an error, the +error+
+entry is set to an error message, and the <tt>field-error</tt> entry is set to
 an array containing the field name and the error message for that field.
-Successful requests by default store a "success" entry with a success
+Successful requests by default store a +success+ entry with a success
 message, though that can be disabled.
 
 In order to use this feature, you have to set the +jwt_secret+ configuration
@@ -26,42 +26,42 @@ future requests, if the response Authorization header is set. If the
 response Authorization header is not set, then continue to use the
 previous Authorization header.
 
-When using this feature, consider using the :json=>:only option when
+When using this feature, consider using the <tt>json: :only</tt> option when
 loading the rodauth plugin, if you want Rodauth to only handle
-JSON requests.  If you don't use the :json=>:only option, the jwt feature
+JSON requests.  If you don't use the <tt>json: :only</tt> option, the jwt feature
 will probably result in an error if a request to a Rodauth endpoint comes
 in with a Content-Type that isn't application/json, unless you also set
 <tt>only_json? false</tt> in your rodauth configuration.
 
 If you would like to check if a valid JWT was submitted with the current
-request in your Roda app, you can call the rodauth.valid_jwt? method.  If
-rodauth.valid_jwt?  returns true, the contents of the jwt can be retrieved
-from rodauth.session.
+request in your Roda app, you can call the +rodauth.valid_jwt?+ method.  If
++rodauth.valid_jwt?+ returns true, the contents of the jwt can be retrieved
+from +rodauth.session+.
 
 == Auth Value Methods
 
 invalid_jwt_format_error_message :: The error message to use when a JWT with an invalid format is submitted in the Authorization header.
-json_accept_regexp :: The regexp to use to check the Accept header for JSON if jwt_check_accept? is true.
+json_accept_regexp :: The regexp to use to check the Accept header for JSON if +jwt_check_accept?+ is true.
 json_non_post_error_message :: The error message to use when a JSON non-POST request is sent.
-json_not_accepted_error_message :: The error message to display if jwt_check_accept? is true and the Accept header is present but does not match json_request_content_type_regexp.
+json_not_accepted_error_message :: The error message to display if +jwt_check_accept?+ is true and the Accept header is present but does not match +json_request_content_type_regexp+.
 json_request_content_type_regexp :: The regexp to use to recognize a request as a json request.
-json_response_content_type :: The content type to set for json responses, application/json by default.
-json_response_custom_error_status? :: Whether to use custom error statuses, instead of always using +json_response_error_status+, false by default for backwards compatibility.
-json_response_error_key :: The JSON result key containing an error message, "error" by default.
-json_response_error_status :: The HTTP status code to use for JSON error responses, 400 by default.
-json_response_field_error_key :: The JSON result key containing an field error message, "field-error" by default.
-json_response_success_key :: The JSON result key containing a success message for successful request, if set.  nil by default to not set success messages.
-jwt_algorithm :: The JWT algorithm to use, "HS256" by default.
+json_response_content_type :: The content type to set for json responses, <tt>application/json</tt> by default.
+json_response_custom_error_status? :: Whether to use custom error statuses, instead of always using +json_response_error_status+, true by default, can be set to false for backwards compatibility with Rodauth 1.
+json_response_error_key :: The JSON result key containing an error message, +error+ by default.
+json_response_error_status :: The HTTP status code to use for JSON error responses if not using custom error statuses, 400 by default.
+json_response_field_error_key :: The JSON result key containing an field error message, <tt>field-error</tt> by default.
+json_response_success_key :: The JSON result key containing a success message for successful request, if set.  +success+ by default.
+jwt_algorithm :: The JWT algorithm to use, +HS256+ by default.
 jwt_authorization_ignore :: A regexp matched against the Authorization header, which skips JWT processing if it matches.  By default, HTTP Basic and Digest authentication are ignored.
 jwt_authorization_remove :: A regexp to remove from the Authorization header before processing the JWT.  By default, a Bearer prefix is removed.
-jwt_check_accept? :: Whether to check the Accept header to see if the client supports JSON responses, false by default for backwards compatibility.
-jwt_decode_opts :: An optional hash to pass to JWT.decode. Can be used to set JWT verifiers.
+jwt_check_accept? :: Whether to check the Accept header to see if the client supports JSON responses, true by default, can be set to false for backwards compatibility with Rodauth 1.
+jwt_decode_opts :: An optional hash to pass to +JWT.decode+. Can be used to set JWT verifiers.
 jwt_secret :: The JWT secret to use.  Access to this should be protected the same as a session secret.
 jwt_session_key :: A key to nest the session hash under in the JWT payload.  nil by default, for no nesting.
 jwt_symbolize_deeply? :: Whether to symbolize the session hash deeply.  false by default.
 non_json_request_error_message :: The error message to use when a non-JSON request is sent and +only_json?+ is set.
-only_json? :: Whether to have Rodauth only allow JSON requests.  True by default if :json=>:only option was given when loading the plugin.  If set, rodauth endpoints will issue an error for non-JSON requests.
-use_jwt? :: Whether to use the JWT in the Authorization header for authentication information.  If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if only_json? is true, or if the request uses a json content type.
+only_json? :: Whether to have Rodauth only allow JSON requests.  True by default if <tt>json: :only</tt> option was given when loading the plugin.  If set, rodauth endpoints will issue an error for non-JSON requests.
+use_jwt? :: Whether to use the JWT in the Authorization header for authentication information.  If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if +only_json?+ is true, or if the request uses a json content type.
 
 == Auth Methods