phoenix-auth-customization

Phoenix Auth Customization

RULES — Follow these with no exceptions

1. Never modify generated auth migrations — create separate migrations for custom fields; generated migrations are tested and correct
2. Update registration_changeset to cast and validate new fields — don't create a separate changeset for initial registration
3. Update test fixtures when adding required fields — missing fixture fields cause cryptic test failures across the entire test suite
4. Confirm users in test fixtures for password-based auth — set confirmed_at: DateTime.utc_now(:second) or tests requiring authenticated users will fail
5. Update both the registration form AND the save/2 handler — the form must send the field, and the handler must pass it to the context
6. Use unique_constraint + database unique index for uniqueness — never validate uniqueness in application code alone

---

Running phx.gen.auth

Start with the generator, then extend. Never hand-roll auth.

# Generate auth with LiveView (recommended)
mix phx.gen.auth Accounts User users

# This creates:
# - Migration: priv/repo/migrations/*_create_users_auth_tables.exs
# - Schema: lib/my_app/accounts/user.ex
# - Scope: lib/my_app/accounts/scope.ex
# - Context: lib/my_app/accounts.ex
# - LiveViews: lib/my_app_web/live/user_live/registration.ex, login.ex,
#              confirmation.ex, settings.ex
# - Controller: lib/my_app_web/controllers/user_session_controller.ex
# - Plugs: lib/my_app_web/user_auth.ex
# - Tests: test/my_app/accounts_test.exs, test/my_app_web/live/user_live/*_test.exs

Phoenix 1.8's phx.gen.auth defaults to magic-link (passwordless) auth — registration has no password field unless you pass options — and generates a MyApp.Accounts.Scope module consumed as @current_scope.

---

Adding Custom Fields

Step 1: Create a Separate Migration

mix ecto.gen.migration add_username_to_users

defmodule MyApp.Repo.Migrations.AddUsernameToUsers do
  use Ecto.Migration

  def change do
    alter table(:users) do
      add :username, :string, null: false
    end

    create unique_index(:users, [:username])
  end
end