Authentication Zero Documentation

Authentication Zero supports several essential and advanced authentication features, many of which can be enabled via flags during generation (e.g., --api, --two-factor).

Essential Features

• Sign up and Email/Password validations
• Password breach checking (--pwned)
• Authentication via Cookie or Token (--api)
• Two-factor authentication (--two-factor) and Hardware Security Keys (--webauthn)
• Email verification via token links
• Sudo mode (--sudoable)
• Password reset (with verified email restrictions)
• Email bombing protection (--lockable)
• Session and device management
• Activity logging (--trackable)

Advanced Features

• Social login via OmniAuth (--omniauthable)
• Passwordless authentication (--passwordless)
• Invitation system (--invitable)
• "Sign-in as" / Masquerading (--masqueradable)
• Multi-tenant support (--tenantable)

Authentication Zero generates code directly into your application instead of providing a closed library.

Key implications:

• Freedom: You have full control to modify the authentication logic to fit your app.
• Maintenance: Because the code is generated into your app, it will not be automatically updated when you update the gem. You are responsible for porting improvements or security fixes from the gem's CHANGELOG.md into your application code.

Once the gem is installed, run the Rails generator to inject the authentication code directly into your application. This approach provides complete freedom to modify the generated code to suit your specific use case.

$ rails generate authentication

Add authentication-zero to your Rails application via Bundler. Choose the version compatible with your Rails version:

• Rails 7.2+: Use the latest version.
• Rails < 7.2: Use version 3.
• Rails < 7.1: Use version 2.

Authentication Zero provides artifacts to support row-level multi-tenancy using Current.account. To implement this, follow these steps:

1. Prepare Tables: Add an account_id to every table that needs to be scoped. Example: rails g migration add_account_to_projects account:references.
2. Scope Models: Include AccountScoped in your models to set up the relationship and a default scope based on the current account.
3. Middleware Setup (Optional): To set Current.account via the URL (e.g., http://myapp.com/:account_id), configure the AccountMiddleware:
   • Add require_relative "../lib/account_middleware" to config/application.rb.
   • Add config.middleware.use AccountMiddleware to your application class.

When building multi-tenant applications with Authentication Zero, you can include the AccountScoped concern in your ActiveRecord models to automatically scope all database queries to the currently active account.

Including this concern performs two actions:

1. Establishes a belongs_to :account relationship.
2. Applies a default_scope that filters all queries using where account: Current.account.

This ensures that data isolation is handled at the model level by leveraging the Current.account global context.