add ReturnTo Plug

[ketupia]

The installer creates an AuthController that will redirect the user based on :return_to in the session but doesn't supply a means to capture and set the :return_to value.

Create a plug something like the following and include it on install or create an igniter task to create it. The example code will look for certain paths like /sign-in with the specified query parameter and store the value in the session.

defmodule YourAppWeb.Plugs.ReturnToPlug do
  @moduledoc """
  Plug to capture the return_to query parameter and store it in the session.
  This allows for proper redirection after successful authentication while
  preventing redirect loops to authentication-related pages.

  ## Options

    * `:paths` - A list of paths where the plug should capture the return_to parameter
      default: ["/sign-in"]
    * `:param_name` - The name of the query parameter to capture
      default: "return_to"
    * `:session_key` - The session key where the return path will be stored
      default: :return_to
    * `:blocked_redirect_paths` - A list of paths that should be blocked as return destinations.  This is a starts_with? comparison.
      default: ["/auth", "/password-reset", "/reset", "/register", "/sign-in", "/sign-out"]

  ## Examples

  Using default options:

      # In your router.ex
      pipeline :browser do
        # ...other plugs
        plug YourAppWeb.Plugs.ReturnToPlug
      end

  With custom paths:

      # Capture return_to on multiple paths
      plug YourAppWeb.Plugs.ReturnToPlug, paths: ["/sign-in", "/login", "/register"]

  Fully customized configuration:

      # Custom parameter name, session key, and blocked paths
      plug YourAppWeb.Plugs.ReturnToPlug,
        paths: ["/sign-in", "/login"],
        param_name: "redirect_to",
        session_key: :redirect_after_login,
        blocked_redirect_paths: ["/auth", "/password-reset", "/reset", "/register", "/sign-in", "/sign-out"]
  """
  import Plug.Conn

  @default_options [
    paths: ["/sign-in"],
    param_name: "return_to",
    session_key: :return_to,
    blocked_redirect_paths: [
      "/auth",
      "/password-reset",
      "/reset",
      "/register",
      "/sign-in",
      "/sign-out"
    ]
  ]

  def init(opts) do
    Keyword.merge(@default_options, opts)
  end

  def call(conn, opts) do
    conn = fetch_query_params(conn)

    # Check if current path is in the configured paths
    if matching_path?(conn, opts[:paths]) && has_return_to_param?(conn, opts[:param_name]) do
      # Extract the return_to parameter
      return_to = get_return_to_param(conn, opts[:param_name])

      # Only store it if it's not pointing to a blocked path
      if blocked_return_path?(return_to, opts[:blocked_redirect_paths]) do
        # If blocked, we could either keep the conn unchanged or clear any existing return_to
        # Here we choose to clear it to be extra safe
        delete_session(conn, opts[:session_key])
      else
        put_session(conn, opts[:session_key], return_to)
      end
    else
      conn
    end
  end

  # Checks if the current path matches any of the configured paths
  defp matching_path?(conn, paths) do
    Enum.member?(paths, conn.request_path)
  end

  # Checks if the request has the configured query parameter
  defp has_return_to_param?(conn, param_name) do
    conn.query_params[param_name] != nil
  end

  # Gets the configured parameter value from the query parameters
  defp get_return_to_param(conn, param_name) do
    conn.query_params[param_name]
  end

  # Checks if the return path starts with any of the blocked prefixes
  defp blocked_return_path?(return_path, blocked_redirect_paths) do
    path_to_check = URI.parse(return_path).path

    Enum.any?(blocked_redirect_paths, fn prefix ->
      String.starts_with?(path_to_check, prefix)
    end)
  end
end

[ketupia]

Elixir Form Post Setting the return_to for ash authentication

[zachdaniel]

I think it's a great idea. Let's hear from @jimsynz if he is into it, and if so PRs welcome! This should be a relatively straight forward change to the ash_authentication_phoenix installer to create this module into user's applications.

[jimsynz]

I like this idea, although I'm wondering if we should simply have the built-in live views look for a return-to query param and stuff if in the session if it's there? That way we can change the generated LiveUserAuth to simply add the query param before bouncing the user out. It also makes it easy to redirect from non-live endpoints too.

[zachdaniel]

The only thing we'd need to add there is some kind of way for the user to configure that logic. It's not a given that developers want users to return to exactly where they came from all the time. So maybe an add on that configures a function that determines the return to that defaults to "exactly wheee you came from" unless it's one of our routes?

[adonig]

Hi guys,

I just wanted to share that I’ve implemented basic redirect-after-sign-in functionality in my fork. It's currently a proof of concept, but it works well in tests.

Here's a quick overview of what I did:

1. LiveView redirect param support
   I added a redirect_param_name override (default: "next") for AshAuthentication.Phoenix.SignInLive. In handle_params/3, I extract the redirect param value and store it in the context.

2. Hidden form inputs + query param forwarding
   In AshAuthentication.Phoenix.Components.Password.SignInForm, I added:

   a) Two hidden inputs inside the form:

   <input type="hidden" name="redirect_param_name" value="next" />
   <input type="hidden" name="next" value="/dashboard" />

   b) These values are also forwarded as query params to the token verification endpoint:

   ?token=...&redirect_param_name=next&next=/dashboard
   

3. Post-login redirect in controller
   In the AshAuthentication.Phoenix.Controller, I modified the fallback success/4 handler to support redirecting to the original destination:

def success(conn, _activity, user, _token) do
  conn = conn |> store_in_session(user) |> assign(:current_user, user)

  with name when not is_nil(name) <- conn.params["redirect_param_name"],
       value when not is_nil(value) <- conn.params[name] do
    conn
    |> redirect(to: value)
  else
    _ ->
      conn
      |> put_status(200)
      |> render("success.html")
  end
end

4. I added a LiveUserAuth test helper module for protecting LiveViews and triggering a redirect if the user is not authenticated. It uses on_mount with a handle_params hook to capture the current path and redirect to the sign-in page with a next parameter:

defmodule AshAuthentication.Phoenix.Test.LiveUserAuth do
  use Phoenix.Component

  use Phoenix.VerifiedRoutes,
    endpoint: AshAuthentication.Phoenix.Test.Endpoint,
    router: AshAuthentication.Phoenix.Test.Router

  alias Phoenix.LiveView

  def on_mount(:live_user_required, _params, _session, socket) do
    if socket.assigns[:current_user] do
      {:cont, socket}
    else
      {:cont, LiveView.attach_hook(socket, :redirect_and_halt, :handle_params, &hook/3)}
    end
  end

  defp hook(_params, uri, socket) do
    request_path = URI.parse(uri) |> Map.get(:path)
    socket = LiveView.redirect(socket, to: ~p"/sign-in?next=#{request_path}")
    {:halt, socket}
  end
end

5. Tests to verify behavior
   I wrote a couple of tests to verify the end-to-end redirect logic. Here’s an excerpt from live_auth_flow_test.exs:

  test "unauthenticated user is redirected to sign-in and back to original page after login", %{
    conn: conn
  } do
    # Step 1: Accessing a protected LiveView without authentication -> triggers redirect to /sign-in
    {:error, {:redirect, %{to: sign_in_url}}} = live(conn, "/protected")

    assert sign_in_url =~ "/sign-in"
    assert sign_in_url =~ "next=%2Fprotected"

    # Step 2: Register a user or ensure the user exists
    strategy = AshAuthentication.Info.strategy!(Example.Accounts.User, :password)
    email = "testuser@example.com"
    password = "secure123"
    create_user!(strategy, email, password)

    # Step 3: Simulate visiting the sign-in page with a redirect param (`next=/protected`)
    {:ok, lv, _html} = live(conn, ~p"/sign-in?next=/protected")

    # Submit the login form -> should trigger a redirect to the token-based login URL
    {:error, {:redirect, %{to: token_url}}} =
      lv
      |> form(~s{[action="/auth/user/password/sign_in?"]},
        user: %{strategy.identity_field => email, strategy.password_field => password},
        redirect_param_name: "next",
        next: "/protected"
      )
      |> render_submit()

    # Follow the redirect to the token URL -> should finally redirect to the original /protected path
    conn = get(build_conn(), token_url)
    assert redirected_to(conn, 302) == "/protected"
  end

  test "authenticated user accesses protected liveview directly", %{conn: conn} do
    strategy = AshAuthentication.Info.strategy!(Example.Accounts.User, :password)
    email = "sign.in@email"
    password = "sign.in.secret"
    create_user!(strategy, email, password)
    conn = sign_in_user(conn, strategy, email, password)

    {:ok, _view, html} = live(conn, "/protected")
    assert html =~ "Protected Content"
  end

Before turning this into a proper PR, I’d appreciate it if you could take a quick look and let me know what else you think should be tested to ensure this logic is production-grade. I'm happy to add whatever is missing.

[adonig]

Here’s a quick update on the latest changes:

• Added Django-inspired redirect path sanitization with configurable fallback
• Introduced support for :live_user_optional and :live_no_user
• Added AshAuthentication.Phoenix.Test.UserAuthPlug with require_user/2 and no_user/2
• Updated classification of Strategy.ApiKey to nil (instead of :link) to prevent rendering an unnecessary horizontal rule

So far, everything is working well. I think it would be worthwhile to also add support for redirect parameters on /register and /reset.

One open question: I made the redirect parameter name configurable via an override, but I couldn’t find a way to access overrides inside a controller or plug. If we could, it would allow us to provide default implementations for LiveUserAuth and UserAuthPlug.

Do you think it would make sense to define the redirect parameter name as a config option instead?

[zachdaniel]

I'm not sure exactly what it would look like, but the redirect parameter name should be a web concern, not configured anywhere in the resource. So maybe when calling plugs/liveview helpers you specify it as an option for example.

[adonig]

I think we can add it to the live session in the macros in AshAuthentication.Phoenix.Router like this:

@spec sign_in_route(
        opts :: [
          {:path, String.t()}
          | {:live_view, module}
          | {:as, atom}
          | {:on_mount, [module]}
          | {:overrides, [module]}
          | {:gettext_fn, {module, atom}}
          | {:gettext_backend, {module, String.t()}}
          | {:redirect_param_name, String.t()}  # <-- Add it here
          | {atom, any}
        ]
      ) :: Macro.t()
defmacro sign_in_route(opts \\ []) do
  {path, opts} = Keyword.pop(opts, :path, "/sign-in")
  {live_view, opts} = Keyword.pop(opts, :live_view, AshAuthentication.Phoenix.SignInLive)
  {as, opts} = Keyword.pop(opts, :as, :auth)
  # ...

  # And here:
  {redirect_param_name, opts} =
    Keyword.pop(
      opts,
      :redirect_param_name,
      Application.get_env(:ash_authentication_phoenix, :redirect_param_name, "next")
    )

   # ...

  quote do
    scope "/", unquote(opts) do
      import Phoenix.LiveView.Router, only: [live: 4, live_session: 3]

      # ...

      live_session_opts = [
        session:
          {AshAuthentication.Phoenix.Router, :generate_session,
           [
             %{
               "overrides" => unquote(overrides),
               "auth_routes_prefix" => auth_routes_prefix,
               "otp_app" => unquote(otp_app),
               # ...
               "redirect_param_name" => unquote(redirect_param_name) # <-- and here
             }
           ]},
        on_mount: on_mount
      ]
    end
  end
end

However, we would need to add this to at least sign_in_route/1, reset_route/1, confirm_route/1, and magic_sign_in_route/1 if we want to support redirects in all these cases. Users who want to change the parameter name would have to update it in all of them. If we go this route, I would at least add a :redirect_param_name config option so you can change all of them at once.

Using the live session, we can set the parameter name in handle_params/3 and pass it to the success handler via query params (token sign-in) and hidden form inputs. In LiveUserAuth, it would be available in the handle_params/3 hook as well.

The last place we would need to provide the redirect param name is in a default AuthUserPlug implementation (maybe we just put it in AshAuthentication.Phoenix.Plug):

defmodule AshAuthentication.Phoenix.UserAuthPlug do
  @moduledoc """
  Plugs for controlling access based on user authentication state.

  - `require_user/2`: Ensures a user is authenticated. If not, redirects to the sign-in page with a redirect parameter.
  - `no_user/2`: Ensures no user is authenticated. If a user is present, redirects to the `next` target (default: `/`).
  """

  import AshAuthentication.Phoenix.Plug, only: [load_from_session: 2]
  alias Plug.Conn
  alias Phoenix.Controller
  alias AshAuthentication.Phoenix.Utils.Redirect

  @doc """
  Ensures a user is authenticated.

  If `:current_user` is present in assigns, allows the request to continue.
  Otherwise redirects to the sign-in page with a redirect query param.

  ## Options

    * `:redirect_param_name` – The name of the query param to use for redirects (default: `"next"`).
    * `:sign_in_path` – The path to redirect to when authentication is required (default: `"/sign-in"`).
  """
  @spec require_user(Conn.t(), keyword) :: Conn.t()
  def require_user(conn, opts) do
    conn = load_from_session(conn, opts)

    if conn.assigns[:current_user] do
      conn
    else
      param_name = Keyword.get(opts, :redirect_param_name, "next")
      sign_in_path = Keyword.get(opts, :sign_in_path, "/sign-in")
      redirect_path = "#{sign_in_path}?#{param_name}=#{conn.request_path}"

      Controller.redirect(conn, to: redirect_path)
      |> Conn.halt()
    end
  end

  @doc """
  Ensures a user is *not* authenticated.

  If `:current_user` is present, the user is redirected to the `next` path (default: `"/"`).
  Otherwise allows the request to continue.

  ## Options

    * `:redirect_param_name` – The name of the query param to use (default: `"next"`).
  """
  @spec no_user(Conn.t(), keyword) :: Conn.t()
  def no_user(conn, opts) do
    conn = load_from_session(conn, opts)

    if conn.assigns[:current_user] do
      param_name = Keyword.get(opts, :redirect_param_name, "next")
      next = conn.params[param_name] || "/"
      sanitized = Redirect.sanitize_path(next)

      Controller.redirect(conn, to: sanitized)
      |> Conn.halt()
    else
      conn
    end
  end
end

Now users could do this in their router:

defmodule ExampleWeb.Router do
  use ExampleWeb, :router

  import AshAuthentication.Phoenix.UserAuthPlug, only: [require_user: 2]

  pipeline :auth_required do
    plug :require_user, redirect_param_name: "return_to"
  end

  scope "/", ExampleWeb do
    pipe_through [:browser, :auth_required]

    live "/protected", SomeController, :index
  end
end

What I don't like about this approach is that it gives users many opportunities to mess it up - like changing the redirect param name in one place but forgetting to change it in another. I think it might be better to only allow users to change it via config.

Additionally, the sign-in path itself is configurable via the :path option in sign_in_route, so UserAuthPlug.require_user/2 would also need to accept a :sign_in_path option to remain aligned. For consistency, it might make sense to allow configuring a default sign-in path via application config too.

[adonig]

Another idea that came to my mind are the opts of the __using__ macro:

defmacro __using__(opts) do
  quote bind_quoted: [opts: opts] do
    @ash_auth_sign_in_path Keyword.get(opts, :sign_in_path, "/sign-in")
    @ash_auth_redirect_param_name Keyword.get(opts, :redirect_param_name, "next")

    import AshAuthentication.Phoenix.Router
    import AshAuthentication.Phoenix.Plug
    import AshAuthentication.Phoenix.LiveSession, only: :macros
  end
end

That would look really nice in the router:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  use AshAuthentication.Phoenix.Router,
    sign_in_path: "/custom-sign-in",
    redirect_param_name: "return_to"

  # ...
end

The downside is that these module attributes are only available within the router module itself (at compile time). So while they work well in macros like sign_in_route/1, they can't be accessed directly from the plug - unless we explicitly pass them as options or store them somewhere (like session or conn.private) during pipeline setup.

[adonig]

There's one way to get it into the plug without relying on Application.get_env or conn.private mutation from the router:

defmacro __using__(opts) do
  quote bind_quoted: [opts: opts] do
    Module.register_attribute(__MODULE__, :ash_auth_config, accumulate: false)
    @ash_auth_config opts

    def __ash_auth_config__, do: @ash_auth_config

    import AshAuthentication.Phoenix.Router
    import AshAuthentication.Phoenix.Plug
    import AshAuthentication.Phoenix.LiveSession, only: :macros
  end
end

This way, when you're in a plug, you can get the router module from conn.private.phoenix_router (which Phoenix sets automatically) and read the config:

router = conn.private.phoenix_router
config = router.__ash_auth_config__()

sign_in_path = Keyword.get(config, :sign_in_path, "/sign-in")
redirect_param_name = Keyword.get(config, :redirect_param_name, "next")

Advanced use-cases like multiple sign-in routes could be supported by having multiple routers:

defmodule MyAppWeb.UserRouter do
  use MyAppWeb, :router
  use AshAuthentication.Phoenix.Router,
    sign_in_path: "/sign-in",
    redirect_param_name: "next"

  # ...
end

defmodule MyAppWeb.AdminRouter do
  use MyAppWeb, :router
  use AshAuthentication.Phoenix.Router,
    sign_in_path: "/admin/sign-in",
    redirect_param_name: "return_to"

  # ...
end

It’s a bit meta, but fully contained and avoids global config or magic conn state. What do you think?

[scottwoodall]

Hi guys,

I just wanted to share that I’ve implemented basic redirect-after-sign-in functionality in my fork. It's currently a proof of concept, but it works well in tests.

.... snip ...
Before turning this into a proper PR, I’d appreciate it if you could take a quick look and let me know what else you think should be tested to ensure this logic is production-grade. I'm happy to add whatever is missing.

There are some edge cases around the sanitization. Add some additional unit tests to make sure normalization is taking place

  @default_safe_schemes [nil, "http", "https"]

HTTP would not be allowed here in this check uri.scheme not in safe_schemes -> fallback

There's also "dot dot" redirects, think /auth/../admin and URL encoding /%61dmin as ways to get around unsafe_paths

I'm sure there are more, but these were ones I immediately thought of. Nice work on the feature!

[adonig]

I’ve been experimenting in my fork to add support for a global router configuration in AshAuthentication.Phoenix.Router, aimed at simplifying and unifying the configuration of authentication routes.

Global Configuration:
Added @default_router_opts and @ash_auth_config module attributes to support a single, consistent configuration across all authentication routes:

use AshAuthentication.Phoenix.Router,
  sign_in_path: "/sign-in",
  sign_out_path: "/sign-out",
  default_auth_scope: "/auth"

This configures default paths, layouts, LiveViews, and other settings in one place, while still allowing overrides in individual route macros when needed. It's possible to access this configuration with AshAuthentication.Phoenix.Router.get_config/1 from within plugs.

Refactored Route Macros:
Split route generation into dedicated modules under lib/ash_authentication_phoenix/router/routes/, each with:

• build_route/2: Builds the actual routes.
• process_options/2: Extracts and normalizes options, merging them with the global router config.
• Typed option definitions for better developer experience.

Improved Maintainability:
This modular approach reduces duplication and makes it easier to:

• Add new features like redirect after sign-in/reset/register.
• Extend and maintain the router codebase without touching every route macro.

Documentation:
Expanded module and function docs, explaining default behaviors and configuration options for each route.

Example Usage

defmodule MyAppWeb.Router do
  use Phoenix.Router
  use AshAuthentication.Phoenix.Router,
    sign_in_path: "/login",
    sign_out_path: "/logout",
    gettext_backend: {MyAppWeb.Gettext, "default"}

  # routes...
  sign_in_route()
  sign_out_route()
end

Why this matters

• Centralized Configuration: No more repeating paths and modules across every route.
• Overrides Still Possible: Individual route macros accept explicit overrides if needed.
• Better Extensibility: Makes it easier to add features like redirects and internationalization.

I’d love to hear your thoughts on this approach! Happy to refine or adjust based on feedback! Let me know what you think.

[adonig]

Should I maybe just turn this into a PR? 😅

[zachdaniel]

👋 I think use AshAuthentication.Phoenix.Router adds some niceties, but also some complexities for certain setups like those that may need to configure these things separately and I think for now we should stick w/ the repetitiveness IMO.

But I'd like to have the ReturnTo stuff settled and provided by core personally 😄 So providing a builtin plug and adding it as part of installation sounds good to me.

[adonig]

Thanks, @zachdaniel!

One thing I’d like to double-check before moving forward: Do you think it’s really a good idea to implement the redirect functionality without any global configuration?

The reason I ask is that if we want to support redirect-after-login, register, reset, magic sign-in, etc., we’ll need to pass the redirect param name (e.g. "next" or "return_to") into quite a few places:

• The LiveView route macros
• The sign-in/reset forms (as hidden inputs)
• The controller/token handler
• The LiveUserAuth module
• The UserAuthPlug.require_user/2 and no_user/2
• And possibly in on_mount hooks

Without a shared config source, every one of these would need to duplicate the value manually. That’s fine for simple apps, but it can become fragile in more complex setups or when people want to customize the param name across the board.

Would it make sense to at least support an optional global fallback (e.g. via use AshAuthentication.Phoenix.Router, redirect_param_name: "return_to"), which could be overridden per route if needed? That way we can keep it DRY but still allow flexibility.

Happy to implement it either way - just wanted to make sure we’re not ruling out config too early if it helps reduce boilerplate and mistakes.