phoenix-liveview-auth

Phoenix LiveView Authentication

RULES — Follow these with no exceptions

1. Always use on_mount callbacks for LiveView auth — never check auth in mount/3 directly; on_mount runs before mount and centralizes auth logic
2. Use mount_current_scope/2 to extract scope from session — never access session tokens manually or parse session data in LiveViews
3. Handle both :cont and :halt returns from on_mount — :halt must redirect with a flash message, never silently drop the connection
4. Resolve Controller/LiveView name clashes the way the 1.8 generator does — UserAuth contains both conn plugs and on_mount hooks. Import Phoenix.Controller normally (the plugs need redirect/2), and fully qualify the LiveView calls inside on_mount hooks: Phoenix.LiveView.redirect(socket, to: ...) and Phoenix.LiveView.put_flash(socket, :error, ...). Excluding the Controller imports breaks the plug half of the module.
5. Guard the nil scope, not the assign lookup — mount_current_scope always assigns :current_scope, so @current_scope is safe; the hazard is calling .user on a nil scope. Write @current_scope && @current_scope.user. Bracket access assigns[:current_scope] is only needed when the assign may be entirely absent (e.g. layouts shared with non-auth live_sessions).
6. Test auth redirects by asserting {:error, {:redirect, %{to: path}}} — don't test auth by checking rendered content; verify the redirect tuple from live/2
7. Define on_mount hooks once, reference via live_session in router — never duplicate auth logic across LiveView modules

on_mount Authentication Pattern

The standard pattern for LiveView authentication. Define once, use everywhere via live_session.

defmodule MyAppWeb.UserAuth do
  use MyAppWeb, :verified_routes
  import Plug.Conn
  import Phoenix.Controller

  # Called by live_session :require_authenticated_user
  def on_mount(:require_authenticated_user, _params, session, socket) do
    socket = mount_current_scope(socket, session)

    if socket.assigns.current_scope && socket.assigns.current_scope.user do
      {:cont, socket}
    else
      socket =
        socket
        |> Phoenix.LiveView.put_flash(:error, "You must log in to access this page.")
        |> Phoenix.LiveView.redirect(to: ~p"/users/log-in")

      {:halt, socket}
    end
  end

  # Called by live_session :redirect_if_authenticated
  def on_mount(:redirect_if_authenticated, _params, session, socket) do
    socket = mount_current_scope(socket, session)

    if socket.assigns.current_scope && socket.assigns.current_scope.user do
      {:halt, Phoenix.LiveView.redirect(socket, to: ~p"/")}
    else
      {:cont, socket}
    end
  end

  # Conn plug — needs the plain Phoenix.Controller redirect/2
  def require_authenticated_user(conn, _opts) do
    if conn.assigns[:current_scope] && conn.assigns.current_scope.user do
      conn
    else
      conn
      |> put_flash(:error, "You must log in to access this page.")
      |> redirect(to: ~p"/users/log-in")
      |> halt()
    end
  end

  # Called by live_session :mount_current_scope (public pages)
  def on_mount(:mount_current_scope, _params, session, socket) do
    {:cont, mount_current_scope(socket, session)}
  end

  defp mount_current_scope(socket, session) do
    Phoenix.Component.assign_new(socket, :current_scope, fn ->
      if user = find_user_from_session(session) do
        %Scope{user: user}
      end
    end)
  end

  defp find_user_from_session(%{"user_token" => token}) do
    Accounts.get_user_by_session_token(token)
  end

  defp find_user_from_session(_session), do: nil
end