<h1>Documentation for Rodauth (v<%= Rodauth.version %>)</h1>

<h2 id="readme"><a href="rdoc/files/README_rdoc.html">README</a> (Introduction to Rodauth, start here if new)</h2>

<h2 id="rdoc"><a href="rdoc/index.html">RDoc</a> (frames)</h2>

<h2 id="plugins">Feature Configuration</h2>

<p>All features in Rodauth must be explicitly enabled.  Configuration that is used by multiple features resides in the Base feature, all other configuration is specific to individual features, and available after the features have been enabled.</p>

<ul>
  <li><a href="rdoc/files/doc/base_rdoc.html">Base</a>: Shared behavior for other features.</li>
  <li><a href="rdoc/files/doc/email_base_rdoc.html">Email Base</a>: Shared behavior for features that require sending email.</li>
  <li><a href="rdoc/files/doc/login_password_requirements_base_rdoc.html">Login Password Requirements Base</a>: Shared behavior for features that set logins or passwords.</li>
  <li><a href="rdoc/files/doc/two_factor_base_rdoc.html">Two Factor Base</a>: Shared behavior for multifactor authentication features.</li>
  <li><a href="rdoc/files/doc/account_expiration_rdoc.html">Account Expiration</a>: Disallows access to accounts if there has been no login or activity after a given amount of time.</li>
  <li><a href="rdoc/files/doc/active_sessions_rdoc.html">Active Sessions</a>: Prevents session reuse after logout, and allows for global logout of all sessions for the account.</li>
  <li><a href="rdoc/files/doc/argon2_rdoc.html">Argon2</a>: Allows use of the argon2 password hash algorithm.</li>
  <li><a href="rdoc/files/doc/audit_logging_rdoc.html">Audit Logging</a>: Provides audit logging to a database table for all rodauth actions.</li>
  <li><a href="rdoc/files/doc/change_login_rdoc.html">Change Login</a>: Allows a user to change their login.</li>
  <li><a href="rdoc/files/doc/change_password_rdoc.html">Change Password</a>: Allows a user to change their password.</li>
  <li><a href="rdoc/files/doc/change_password_notify_rdoc.html">Change Password Notify</a>: Emails the user when they use the Change Password feature to change their password.</li>
  <li><a href="rdoc/files/doc/close_account_rdoc.html">Close Account</a>: Allows a user to close their account.</li>
  <li><a href="rdoc/files/doc/confirm_password_rdoc.html">Confirm Password</a>: Allows a user to confirm their password, or multifactor authenticate via password is authenticated via another method.</li>
  <li><a href="rdoc/files/doc/create_account_rdoc.html">Create Account</a>: Allows a user to create an account.</li>
  <li><a href="rdoc/files/doc/disallow_common_passwords_rdoc.html">Disallow Common Passwords</a>: Disallows the use of common passwords.</li>
  <li><a href="rdoc/files/doc/disallow_password_reuse_rdoc.html">Disallow Password Reuse</a>: Disallows setting password to the same string as previous passwords.</li>
  <li><a href="rdoc/files/doc/email_auth_rdoc.html">Email Authentication</a>: Allows login via a link sent via email.</li>
  <li><a href="rdoc/files/doc/http_basic_auth_rdoc.html">HTTP Basic Auth</a>: Allows HTTP basic authentication.</li>
  <li><a href="rdoc/files/doc/internal_request_rdoc.html">Internal Request</a>: Allows interacting with Rodauth by calling methods.</li>
  <li><a href="rdoc/files/doc/json_rdoc.html">JSON</a>: Adds JSON API support for all other features.</li>
  <li><a href="rdoc/files/doc/jwt_rdoc.html">JWT</a>: Adds JSON Web Token support for all other features.</li>
  <li><a href="rdoc/files/doc/jwt_cors_rdoc.html">JWT CORS</a>: Supports Cross-Origin Resource Sharing in the JSON API.</li>
  <li><a href="rdoc/files/doc/jwt_refresh_rdoc.html">JWT Refresh</a>: Supports separate access and refresh JWT tokens.</li>
  <li><a href="rdoc/files/doc/lockout_rdoc.html">Lockout</a>: Locks an account out after a number of invalid authentication attempts, allowing unlocking via email.</li>
  <li><a href="rdoc/files/doc/login_rdoc.html">Login</a>: Allows for logging into the application via a login/email and password.</li>
  <li><a href="rdoc/files/doc/logout_rdoc.html">Logout</a>: Allows for logging out of the application, by removing the login information from the session.</li>
  <li><a href="rdoc/files/doc/otp_rdoc.html">OTP</a>: Adds support for multifactor authentication via TOTP.</li>
  <li><a href="rdoc/files/doc/otp_lockout_email_rdoc.html">OTP Lockout Email</a>: Emails user when TOTP authentication is locked out or unlocked for their account.</li>
  <li><a href="rdoc/files/doc/otp_modify_email_rdoc.html">OTP Modify Email</a>: Emails user when TOTP authentication is setup or disabled for their account.</li>
  <li><a href="rdoc/files/doc/otp_unlock_rdoc.html">OTP Unlock</a>: Adds support for unlocking TOTP authentication after it is locked out.</li>
  <li><a href="rdoc/files/doc/password_complexity_rdoc.html">Password Complexity</a>: Adds more sophisticated complexity checks for passwords.</li>
  <li><a href="rdoc/files/doc/password_expiration_rdoc.html">Password Expiration</a>: Requires that accounts change their password after a given amount of time.</li>
  <li><a href="rdoc/files/doc/password_grace_period_rdoc.html">Password Grace Period</a>: Allows skipping password entry on forms normally requiring it if a user recently entered their password.</li>
  <li><a href="rdoc/files/doc/password_pepper_rdoc.html">Password Pepper</a>: Allows appending a secret key to passwords before they are hashed.</li>
  <li><a href="rdoc/files/doc/path_class_methods_rdoc.html">Path Class Methods</a>: Allows for getting paths/URLs for features using class methods.</li>
  <li><a href="rdoc/files/doc/recovery_codes_rdoc.html">Recovery Codes</a>: Adds support for mulitfactor authentication via single-use account recovery codes.</li>
  <li><a href="rdoc/files/doc/remember_rdoc.html">Remember</a>: Automatically logs a user in based on a token stored in a cookie.</li>
  <li><a href="rdoc/files/doc/reset_password_rdoc.html">Reset Password</a>: Allows users to reset their password if they don't remember it.</li>
  <li><a href="rdoc/files/doc/reset_password_notify_rdoc.html">Reset Password Notify</a>: Emails the user after they have used the Reset Password feature to successfully reset their password.</li>
  <li><a href="rdoc/files/doc/reset_password_verifies_account_rdoc.html">Reset Password Verifies Account</a>: Allows password resets for unverified accounts, and verifies account on successful password reset.</li>
  <li><a href="rdoc/files/doc/session_expiration_rdoc.html">Session Expiration</a>: Expires sessions automatically based on inactivity or max lifetime checks.</li>
  <li><a href="rdoc/files/doc/single_session_rdoc.html">Single Session</a>: Allows only a single active session per account.</li>
  <li><a href="rdoc/files/doc/sms_codes_rdoc.html">SMS Codes</a>: Adds support for multifactor authentication via codes received via SMS.</li>
  <li><a href="rdoc/files/doc/update_password_hash_rdoc.html">Update Password Hash</a>: Updates the password hash whenever the hash cost changes.</li>
  <li><a href="rdoc/files/doc/verify_account_rdoc.html">Verify Account</a>: Requires verifications of newly created accounts before login.</li>
  <li><a href="rdoc/files/doc/verify_account_grace_period_rdoc.html">Verify Account Grace Period</a>: Allows newly created accounts a grace period before verification is required.</li>
  <li><a href="rdoc/files/doc/verify_login_change_rdoc.html">Verify Login Change</a>: Requires verification of new logins before changing logins.</li>
  <li><a href="rdoc/files/doc/webauthn_rdoc.html">WebAuthn</a>: Adds support for multifactor authentication via WebAuthn.</li>
  <li><a href="rdoc/files/doc/webauthn_autofill_rdoc.html">WebAuthn Autofill</a>: Enables autofill UI for WebAuthn credentials on login.</li>
  <li><a href="rdoc/files/doc/webauthn_login_rdoc.html">WebAuthn Login</a>: Adds support for passwordless login via WebAuthn.</li>
  <li><a href="rdoc/files/doc/webauthn_modify_email_rdoc.html">WebAuthn Modify Email</a>: Emails user when a WebAuthn authenticator is added to or removed from their account.</li>
  <li><a href="rdoc/files/doc/webauthn_verify_account_rdoc.html">WebAuthn Verify Account</a>: Adds support for passwordless WebAuthn setup during account verification.</li>
</ul>

<h2 id="guides">Guides</h2>

<ul>
  <li><a href="rdoc/files/doc/guides/admin_activation_rdoc.html">Require account verification by admin</a></li>
  <li><a href="rdoc/files/doc/guides/already_authenticated_rdoc.html">Skip login page if already authenticated</a></li>
  <li><a href="rdoc/files/doc/guides/alternative_login_rdoc.html">Use a non-email login</a></li>
  <li><a href="rdoc/files/doc/guides/case_insensitive_login_rdoc.html">Case insensitive login</a></li>
  <li><a href="rdoc/files/doc/guides/change_table_and_column_names_rdoc.html">Change table and column names</a></li>
  <li><a href="rdoc/files/doc/guides/create_account_programmatically_rdoc.html">Create an account record programmatically</a></li>
  <li><a href="rdoc/files/doc/guides/delay_password_rdoc.html">Set password when verifying account</a></li>
  <li><a href="rdoc/files/doc/guides/email_only_rdoc.html">Allow only email authentication</a></li>
  <li><a href="rdoc/files/doc/guides/email_requirements_rdoc.html">Customize email requirements</a></li>
  <li><a href="rdoc/files/doc/guides/i18n_rdoc.html">Translate with I18n gem</a></li>
  <li><a href="rdoc/files/doc/guides/links_rdoc.html">Display authentication links</a></li>
  <li><a href="rdoc/files/doc/guides/login_return_rdoc.html">Redirect to original page after login</a></li>
  <li><a href="rdoc/files/doc/guides/password_column_rdoc.html">Store password hash in accounts table</a></li>
  <li><a href="rdoc/files/doc/guides/password_confirmation_rdoc.html">Require password confirmation for certain actions</a></li>
  <li><a href="rdoc/files/doc/guides/password_requirements_rdoc.html">Customize password requirements</a></li>
  <li><a href="rdoc/files/doc/guides/paths_rdoc.html">Change route path</a></li>
  <li><a href="rdoc/files/doc/guides/query_params_rdoc.html">Pass query parameters to auth URLs</a></li>
  <li><a href="rdoc/files/doc/guides/redirects_rdoc.html">Change redirect destination</a></li>
  <li><a href="rdoc/files/doc/guides/registration_field_rdoc.html">Add field during account creation</a></li>
  <li><a href="rdoc/files/doc/guides/render_confirmation_rdoc.html">Render confirmation view</a></li>
  <li><a href="rdoc/files/doc/guides/require_mfa_rdoc.html">Require multifactor authentication after login</a></li>
  <li><a href="rdoc/files/doc/guides/reset_password_autologin_rdoc.html">Autologin after password reset</a></li>
  <li><a href="rdoc/files/doc/guides/share_configuration_rdoc.html">Share configuration via inheritance</a></li>
  <li><a href="rdoc/files/doc/guides/status_column_rdoc.html">Store account status in a text column</a></li>
  <li><a href="rdoc/files/doc/guides/totp_or_recovery_rdoc.html">Allow recovery code on TOTP code field</a></li>
  <li><a href="rdoc/files/doc/guides/internals_rdoc.html">Internals Guide, describing how Rodauth works internally</a></li>
</ul>

<h2 id="external-features">External Features</h2>

<p>To use these external features, install their dependencies and follow their installation instructions.</p>

<ul>
  <li><a href="https://github.com/adam12/rodauth-become_account">rodauth-become_account</a>: Easily switch between Rodauth accounts.</li>
  <li><a href="https://github.com/janko/rodauth-guest">rodauth-guest</a>: Provides guest user functionality.</li>
  <li><a href="https://github.com/janko/rodauth-i18n">rodauth-i18n</a>: Provides I18n integration and translations.</li>
  <li><a href="https://github.com/janko/rodauth-model">rodauth-model</a>: Provides password attribute and associations for account model.</li>
  <li><a href="https://gitlab.com/os85/rodauth-oauth">rodauth-oauth</a>: Implements the OAuth 2.0 protocol on top of Rodauth.</li>
  <li><a href="https://github.com/janko/rodauth-omniauth">rodauth-omniauth</a>: Provides login & registration with multiple external providers using OmniAuth.</li>
  <li><a href="https://github.com/janko/rodauth-pwned">rodauth-pwned</a>: Checks passwords against the Pwned Passwords API.</li>
  <li><a href="https://github.com/janko/rodauth-rails">rodauth-rails</a>: Provides Rails integration for Rodauth.</li>
  <li><a href="https://gitlab.com/honeyryderchuck/rodauth-select-account">rodauth-select-account</a>: Support logging into multiple accounts in the same session.</li>
</ul>

<h2 id="external-documentation">External Documentation</h2>

<ul>
  <li><a href="https://github.com/janko/rodauth-openapi">rodauth-openapi</a>: Generate OpenAPI documentation for your Rodauth endpoints</li>
  <li><a href="https://documenter.getpostman.com/view/26686011/2s9YC7SWn9">Documentation of Rodauth routes for JSON requests</a></li>
</ul>

<h2><a href="rdoc/files/CHANGELOG.html">Change Log</a></h2>

<h2 id="release-notes">Release Notes</h2>
<ul>
  <% %w'2 1'.each do |i| %>
      <% 
         lines = []
         Dir["../doc/release_notes/#{i}.*.txt"].map{|f| File.basename(f)}.each do |f|
           (lines[f.split('.')[1].to_i/10] ||= []) << f
         end
         lines.reverse.each do |fs|
      %>
        <li>
          <%= fs.sort_by{|f| f.split('.').map{|x| x.to_i}}.reverse.map do |f|
            "<a href='rdoc/files/doc/release_notes/#{f.gsub('.', '_')}.html'>#{f.sub(/\.txt$/, '').sub(/(..)\.0$/, '\\1')}</a>"
             end.join(' | ') %>
        </li>
      <% end %>
  <% end %>
</ul>

<h2 id="license"><a href="rdoc/files/MIT-LICENSE.html">License</a></h2>

<h2 id="presentations">Presentations</h2>

<ul>
<li><a href="http://code.jeremyevans.net/presentations/pivorak-2020-05/index.html">&quot;Rodauth: Ruby's Most Advanced Authentication Framework&quot; Presentation at Pivorak Conf 5.0</a> (<a href="https://www.youtube.com/watch?v=5rjjCZmbB6c&t=10s">Video</a>)</li>
<li><a href="https://speakerdeck.com/valikos/rodauth-clean-authentication">&quot;Rodauth: Clean Authentication&quot; at Ruby Meditation #13</a></li>
<li><a href="http://code.jeremyevans.net/presentations/rubyconflt2016/index.html">&quot;Rodauth: Website Security Through Database Security&quot; Presentation at RubyConf LT 2016</a> (1024x768, 50 minutes)</li>
<li><a href="http://code.jeremyevans.net/presentations/rubyconfby2016/index.html">&quot;Rodauth: Website Security Through Database Security&quot; Presentation at RubyConf BY 2016</a> (1280x720, 40 minutes) (<a href="https://www.youtube.com/watch?v=z3HZZHXXo3I">Video</a>)</li>
</ul>

<h2 id="db-diagram">Database Diagram</h2>

<p>Here is a diagram of the tables that Rodauth uses and the relationships between the tables as of Rodauth 2.0.0.</p>

<a style="display: block;" href="images/rodauth-db-diagram.png"><img src="images/rodauth-db-diagram-thumb.png" /></a>

<h2 id="apps">Applications Using Rodauth</h2>

<p>Here are some open source applications that use Rodauth:</p>

<ul>
  <li><a href="https://github.com/jeremyevans/spam">SPAM</a> (Simple Personal Accounting Manager)</li>
  <li><a href="https://github.com/jeremyevans/giftsmas">Giftsmas</a> (Gift Tracking)</li>
  <li><a href="https://github.com/jeremyevans/kaeruera">KaeruEra</a> (Exception Tracking)</li>
  <li><a href="https://github.com/enterprise-oss/osso">Osso</a> (SAML to OAuth bridge)</li>
  <li><a href="https://github.com/ubicloud/ubicloud">Ubicloud</a> (Open, Free, and Portable Cloud)</li>
</ul>
