# Rodauth: authentication features and setup constraints

> Rodauth is a Ruby authentication framework for Rack applications, with password login, multifactor authentication, passwordless methods, JWT, WebAuthn, and HTML or JSON interfaces. Its strongest fit is a Ruby application that needs configurable authentication controls without adopting a complete application framework.

**jeremyevans/rodauth** — Ruby's Most Advanced Authentication Framework

- Repository: https://github.com/jeremyevans/rodauth
- Website: http://rodauth.jeremyevans.net
- Stars: 1,944 · Forks: 112
- Language: Ruby
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/jeremyevans-rodauth

## Rodauth's Rack authentication scope

Rodauth addresses authentication inside Ruby web applications rather than acting as a general user-management service. It is designed to work in any Rack application, including applications built with Roda and Sequel. The README also states that Rodauth can be used with other web frameworks, database libraries and databases, which makes its stated scope wider than the Roda ecosystem.

The feature set covers the account lifecycle documented by the project. It includes account creation and closure, login changes, password changes, password resets, account verification and expiration. It can also enforce password-related policies such as common-password checks, password reuse restrictions, complexity requirements, expiration and grace periods. Other controls cover sessions, remember devices, active sessions, single-session restrictions, lockout, audit logging and password-hash updates.

That breadth is the project's main appeal, but it also creates a configuration decision for every adopter. Rodauth presents many features rather than one fixed authentication policy. The documentation identifies separate feature files under `doc/`, and several base features are loaded automatically by the features that need them. A team should therefore treat feature selection as part of the architecture, not as installing one authentication package and accepting every enabled behavior.

The intended users are Ruby developers who need authentication controls inside an existing Rack application. Rodauth is less suited to a team seeking an external identity provider with a separately operated control panel. Its documentation describes framework code, database models, routes, rendering and feature plugins, so it expects control of the application and its data layer.

## Plugin composition and request handling

Rodauth is built with Roda and Sequel, but the README does not require those libraries to define every integration boundary. It can be used with other web frameworks, database libraries and databases. Its feature organization is modular: named features cover login, email, two-factor authentication, passwordless authentication, token-based access and account administration.

Features send HTML pages or expose JSON APIs for supported functions. The `JSON` feature is listed separately, while JWT support is divided into `JWT`, `JWT CORS` and `JWT Refresh`. This separation matters because JSON-only use does not necessarily have the same rendering requirements as an HTML application. The README says `tilt` is used by all features unless the application runs in JSON API-only mode or uses the `:render=>false` plugin option.

Configuration uses a Ruby DSL. Rodauth's design goals call for easy configuration through that DSL and for overriding any part of the framework. That is more useful than a fixed login page, but it also means security-sensitive customization is the application's responsibility. The available documentation describes options and methods through its feature files, so a correct setup requires reading the documentation for each enabled feature.

Feature dependencies are selected according to use. `bcrypt` supplies the default password hashing behavior. `argon2` is needed for the `argon2` feature, `mail` is used by listed email-related features, `rotp` and `rqrcode` support OTP, `jwt` supports JWT, and `webauthn` supports WebAuthn. A JSON-only deployment can avoid some rendering dependencies, but optional security and communication features still introduce their own gems.

## Database functions around bcrypt password hashes

Rodauth's most distinctive security mechanism is optional database-level isolation for password hashes. With PostgreSQL, MySQL or Microsoft SQL Server in the default configuration, the application uses database functions instead of granting the application account direct read access to stored password hashes. The stated purpose is to reduce the risk that an attacker who obtains password hashes can use them against other sites.

Passwords are hashed with bcrypt by default. Hashes are stored separately from accounts in a table linked to the accounts table through a foreign key. The documentation describes two database functions: one retrieves the salt for a password, and the other checks whether a supplied password hash matches the stored hash for a user.

Two database accounts are part of this arrangement. The `app` account represents the application and does not have permission to read password hashes. A second account handles password-hash access. This is a meaningful boundary, but it requires database privileges and schema changes rather than only a Ruby setting.

Rodauth does not require database functions and says it works correctly without them. A team using another database, or a managed database account without sufficient control, may be unable to implement the stronger model. In that case, the application must accept a configuration in which it can access password hashes more directly. The feature should be evaluated as part of database administration, not merely as an authentication library option.

## Installing Rodauth and preparing the first use

The README does not provide a basic runtime installation command, a `Gemfile` entry, a database migration, or a complete first-application example. It identifies the project as a gem through `rodauth.gemspec` and documents a development dependency installation command. That command installs dependencies needed to run the tests, not a ready-made Rodauth application.

Developers who want the repository's development dependencies can run the documented command:

```bash
gem install --development rodauth
```

This installs the dependencies listed for development so the test suite can be run. It does not, by itself, configure Roda, Sequel, a database schema or a Rack application.

For a first real use, the repository's feature documentation is the starting point because the README points to individual files in `doc/`. There is no documented single command here that creates accounts, starts a server or displays a login page. An application author must select the required features, add the corresponding gem dependencies, define the authentication schema, configure the database and mount Rodauth within the Rack stack.

The optional dependencies should be added only when their features are enabled. For example, bcrypt is the default hashing dependency, while OTP, JWT and WebAuthn bring separate dependencies. This is an important setup check: installing the development dependencies does not establish that a production application has every gem required by its selected feature set.

## MFA and passwordless feature trade-offs

Rodauth supports several forms of authentication beyond a conventional login and password. The README names multiple multifactor authentication methods and multiple passwordless authentication methods. The feature index includes OTP, recovery codes, WebAuthn, WebAuthn Login, email authentication, SMS codes and JWT. It also includes account verification and email-related workflows.

These features are not interchangeable. OTP requires `rotp` and `rqrcode`, email authentication depends on the mail-related feature set, JWT requires the `jwt` gem, and WebAuthn requires the `webauthn` gem. SMS codes add a communication dependency whose delivery behavior is outside the framework's documented feature list. Recovery codes are listed as a separate feature and should be treated as part of the account-recovery design rather than an incidental setting.

WebAuthn has several variants, including login, email modification and account verification. That granularity allows an application to expose only a particular operation, but it increases the number of configuration and test cases. JSON support is also available for supported features, which can help API applications avoid HTML rendering, though the README does not claim that every authentication interaction has identical behavior across HTML and JSON interfaces.

The right choice depends on the application contract and its users. A passwordless method still requires careful account linking and recovery behavior. MFA adds credential provisioning and fallback paths. JWT changes the token lifecycle and introduces the separate `JWT Refresh` and `JWT CORS` concerns. Rodauth offers the mechanisms, but the application must decide which ones fit its risk model and user experience.

## Limitations, maintenance and MIT licensing

The clearest limitation is the amount of application-side work surrounding the framework. Rodauth is flexible by design, but the README does not present a complete production setup. Database schema, feature configuration, dependency selection, route integration and policy decisions remain outside a single documented startup path. The database-function protection is also unavailable when the selected database or account permissions do not support it.

The framework is not a hosted identity service. Its HTML pages, JSON API, email delivery, SMS delivery, recovery policy and database controls are parts of an application architecture. A team that needs an independently operated identity platform may find that this model does not match its operating requirements.

Rodauth's MIT licence permits use, modification and distribution under the licence terms, but adopters must retain the required licence notices and review the actual `MIT-LICENSE` file for their distribution context. This is a licensing note rather than legal advice.

The repository is not archived. Its last push was on 2026-10-13, which indicates recent development activity under the stated maintenance rules, although it has no GitHub releases. The repository contains `CHANGELOG`, `CONTRIBUTING` and `SECURITY.md`, but the README does not document a supported release policy, upgrade procedure or compatibility matrix. Teams should inspect those files and the gem dependencies before selecting an upgrade cadence.

## Conclusion

Application teams should consider Rodauth when they want composable authentication features in a Rack application and can manage its Ruby, Rack, database and optional feature dependencies. Projects that need a documented one-command setup or a self-contained hosted identity service should look elsewhere. Before adoption, verify the exact feature configuration, database privilege model, dependency set, session behavior, upgrade path and MIT licence obligations. Rodauth had its last push on 2026-10-13, so its current codebase is recent even though the repository has no GitHub releases.

## FAQ

### What is Rodauth used for?

Rodauth provides authentication features for Ruby Rack applications. Its documented capabilities include login, account management, password policies, MFA, passwordless authentication, JWT and WebAuthn.

### Does Rodauth require Roda and Sequel?

No. Rodauth is built using Roda and Sequel, but the README says it can be used with other web frameworks, database libraries and databases.

### Which database features protect Rodauth password hashes?

In the default configuration, PostgreSQL, MySQL and Microsoft SQL Server can use database functions so the application account cannot directly read password hashes. Rodauth says this feature is optional and can be unavailable with other databases or restricted database permissions.

## Sources

- [Issues](https://github.com/jeremyevans/rodauth/issues)
- [jeremyevans/rodauth on GitHub](https://github.com/jeremyevans/rodauth)
- [License: MIT](https://github.com/jeremyevans/rodauth/blob/master/LICENSE)
- [Project website](http://rodauth.jeremyevans.net)
- [README](https://github.com/jeremyevans/rodauth/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jeremyevans-rodauth