PhxAuthPlus

🔐 Complete & Extensible Phoenix Authentication - Full email + password authentication with future-proof extensibility using Igniter.

✨ Why PhxAuthPlus?

Phoenix v1.8 simplified authentication to magic links only. PhxAuthPlus restores the complete email + password experience while preparing your app for future authentication methods!

Built with Igniter for smarter code generation and better project integration.

🚀 Quick Start

Installation

Add to your mix.exs:

def deps do
  [
    {:phx_auth_plus, "~> 0.0.1", only: [:dev], runtime: false}
  ]
end

Generate Authentication

# Install and generate in one command!
mix igniter.install phx_auth_plus

# Or generate manually
mix phx_auth_plus.gen.auth Accounts User users

🎯 Complete Feature Set

🔐 Core Authentication

🛡️ Security Features

🎨 User Experience

🔧 Developer Experience

🚀 Extensibility (Future-Proof)

📦 Installation Methods

Method 1: Igniter (Recommended)

mix igniter.install phx_auth_plus

Method 2: Manual

# Add to deps
{:phx_auth_plus, "~> 0.0.1", only: [:dev], runtime: false}

# Generate
mix deps.get
mix phx_auth_plus.gen.auth Accounts User users

🛠️ Usage Options

Basic Generation

mix phx_auth_plus.gen.auth Accounts User users

With Options

# LiveView (default)
mix phx_auth_plus.gen.auth Accounts User users --live

# Controllers only  
mix phx_auth_plus.gen.auth Accounts User users --no-live

# Argon2 hashing (most secure)
mix phx_auth_plus.gen.auth Accounts User users --hashing-lib argon2

# Binary IDs (UUIDs)
mix phx_auth_plus.gen.auth Accounts User users --binary-id

# Custom table name
mix phx_auth_plus.gen.auth Accounts User users --table app_users

# Context app (umbrella projects)
mix phx_auth_plus.gen.auth Accounts User users --context-app my_app

🔄 After Generation

# Install dependencies
mix deps.get

# Run migrations  
mix ecto.migrate

# Start server
mix phx.server

Visit http://localhost:4000 to see the complete authentication system!

📁 Generated Files

lib/
├── my_app/accounts/
│   ├── user.ex                    # User schema with password fields
│   ├── user_token.ex              # Token management for sessions
│   └── user_notifier.ex           # Email notifications (Swoosh)
└── my_app_web/
    ├── auth/
    │   └── user_auth.ex           # Authentication plugs & functions
    └── user_auth/
        ├── registration_live.ex   # Signup LiveView
        ├── login_live.ex          # Login LiveView  
        ├── settings_live.ex       # Settings LiveView
        ├── reset_password_live.ex # Password reset LiveView
        └── confirmation_live.ex   # Email confirmation LiveView

priv/repo/migrations/
└── xxx_create_users_auth_tables.exs  # Users & tokens tables

test/
└── my_app_web/
    └── auth/
        └── user_auth_test.exs    # Complete authentication tests

🔗 Available Routes

Authentication Routes

Settings Routes

🎨 Authentication Flow

1. Registration

User enters email + password → 
Validation → 
Hash password → 
Save user → 
Send confirmation email → 
Redirect to login

2. Login

User enters email + password → 
Find user by email → 
Verify password → 
Create session token → 
Set secure cookie → 
Redirect to dashboard

3. Password Reset

User requests reset → 
Generate secure token → 
Send reset email → 
User clicks link → 
Verify token → 
Allow password change → 
Invalidate all sessions

📊 Security Architecture

Password Security

Session Security

Email Security

🆚 vs Standard Phoenix Auth

Feature Phoenix v1.8+ PhxAuthPlus
Email + Password ❌ Removed ✅ Full Support
Account Confirmation ✅ Basic ✅ Enhanced
Password Reset ✅ Basic ✅ Complete Flow
Remember Me ❌ Removed ✅ Secure Cookies
Session Tracking ✅ Basic ✅ Enhanced
LiveView Support ✅ Basic ✅ Complete
Smart Generation ❌ Basic ✅ AST-based
Future Extensibility ❌ Limited ✅ Ready
Documentation ✅ Basic ✅ Comprehensive

🔧 Configuration

Password Hashing

# config/config.exs
config :phx_auth_plus, PhxAuthPlus.Vault,
  # bcrypt (default Unix)
  log_rounds: 12,
  
  # pbkdf2 (default Windows)  
  salt_len: 16,
  digest: :sha256,
  
  # argon2 (most secure)
  t_cost: 2,
  m_cost: 65536,
  parallelism: 4

Session Configuration

# config/config.exs  
config :phx_auth_plus, PhxAuthPlusWeb.Auth,
  session_timeout: :timer.hours(24),
  absolute_session_timeout: :timer.hours(72),
  remember_me_timeout: :timer.days(30),
  max_sessions_per_user: 5

Email Configuration

# config/dev.exs
config :my_app, MyApp.Mailer,
  adapter: Swoosh.Adapters.Local

# Visit /dev/mailbox to see emails during development

🧪 Testing

The generated test suite includes:

Run tests with:

mix test test/my_app_web/auth/user_auth_test.exs

🎨 Customization

Add Custom Fields to User

# lib/my_app/accounts/user.ex
schema "users" do
  field :email, :string
  field :password, :string, virtual: true, redact: true
  field :hashed_password, :string, redact: true
  field :confirmed_at, :utc_datetime_usec
  
  # Custom fields
  field :first_name, :string
  field :last_name, :string
  field :avatar_url, :string
  field :role, :string, default: "user"
  
  timestamps()
end

Add Role-Based Authorization

# lib/my_app/accounts/authorization.ex
defmodule MyApp.Accounts.Authorization do
  def admin?(%User{role: "admin"}), do: true
  def admin?(_), do: false
  
  def can_access?(user, resource) do
    # Your authorization logic here
  end
end

Customize LiveViews

# lib/my_app_web/user_auth/registration_live.ex
defmodule MyAppWeb.UserAuth.RegistrationLive do
  use MyAppWeb, :live_view

  def render(assigns) do
    ~H"""
    <div class="mx-auto max-w-md">
      <.header class="text-center">
        Create your account
        <:subtitle>
          Join our community today
        </:subtitle>
      </.header>
      
<!-- Your custom registration form -->

    </div>
    """
  end
end

📚 Documentation

🚀 Roadmap

v1.1.0 (Planned)

v1.2.0 (Future)

v2.0.0 (Long-term)

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md.

Development Setup

# Clone the repository
git clone https://github.com/your-username/phx_auth_plus.git
cd phx_auth_plus

# Install dependencies
mix deps.get

# Run tests
mix test

# Generate documentation
mix docs

📄 License

MIT License - see LICENSE.md for details.

🔗 Links

🎯 Why "Plus"?

PhxAuthPlus is designed to be the complete authentication solution that grows with your application:

  1. Plus Features - All the features Phoenix removed + more
  2. Plus Security - Enhanced security with modern best practices
  3. Plus Extensibility - Ready for future authentication methods
  4. Plus Developer Experience - Igniter-powered smart generation
  5. Plus Documentation - Comprehensive guides and examples

Start with email + password today, add OAuth tomorrow, implement 2FA next week - PhxAuthPlus scales with your needs!

Built with ❤️ using Igniter - The future of Elixir code generation!

🚀 Ready to build the complete authentication system your users deserve?