AshAuthentication.Phoenix.Router (ash_authentication_phoenix v2.13.1)

Phoenix route generation for AshAuthentication.

Using this module imports the macros in this module and the plug functions from AshAuthentication.Phoenix.Plug.

Usage

Adding authentication to your live-view router is very simple:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  use AshAuthentication.Phoenix.Router

  pipeline :browser do
    # ...
    plug(:load_from_session)
  end

  pipeline :api do
    # ...
    plug(:load_from_bearer)
  end

  scope "/", MyAppWeb do
    pipe_through :browser
    sign_in_route auth_routes_prefix: "/auth"
    sign_out_route AuthController
    auth_routes AuthController, MyApp.Accounts.User
    reset_route auth_routes_prefix: "/auth"
  end

Adding Custom Fields to Authentication Forms

You can slot in custom form fields into the authentication forms using the override system.

Step 1: Create a Component for Your Extra Fields

defmodule MyAppWeb.AuthComponents do
  use Phoenix.Component
  import PhoenixHTMLHelpers.Form

  attr :form, :any, required: true

  @spec register_extra(map()) :: Phoenix.LiveView.Rendered.t()
  def register_extra(assigns) do
    ~H"""
    <div>Testing</div>
    """
  end
end

Step 2: Configure Overrides to Use Your Component

defmodule MyAppWeb.AuthOverrides do
  use AshAuthentication.Phoenix.Overrides

  override AshAuthentication.Phoenix.Components.Password do
    set :register_extra_component, &MyAppWeb.AuthComponents.register_extra/1
    set :sign_in_extra_component, &MyAppWeb.AuthComponents.sign_in_extra/1
    set :reset_extra_component, &MyAppWeb.AuthComponents.reset_extra/1
  end
end

Step 3: Pass Overrides to Router Macro

scope "/", MyAppWeb do
  pipe_through :browser
  sign_in_route overrides: [MyAppWeb.AuthOverrides]
end

The component will receive the form as the form assign and will be rendered in the appropriate position within the authentication form.

Summary

Types

auth_route_options()

Options that can be passed to auth_routes_for.

path_option()

A sub-path if required. Defaults to /auth.

scope_opts_option()

Any options which should be passed to the generated scope.

to_option()

The controller which will handle success and failure.

Functions

auth_routes(auth_controller, resource_or_resources, opts \\ [])

Generates the routes needed for the various strategies for a given AshAuthentication resource.

auth_routes_for(resource, opts) deprecated

Generates the routes needed for the various strategies for a given AshAuthentication resource.

confirm_route(resource, strategy, opts \\ [])

Generates a generic, white-label confirmation page using LiveView and the components in AshAuthentication.Phoenix.Components.

magic_sign_in_route(resource, strategy, opts \\ [])

Generates a genric, white-label magic link sign in page using LiveView and the components in AshAuthentication.Phoenix.Components.

reset_route(opts \\ [])

Generates a generic, white-label password reset page using LiveView and the components in AshAuthentication.Phoenix.Components. This is the page that allows a user to actually change his password, after requesting a reset token via the sign-in (/reset) route.

sign_in_route(opts \\ [])

Generates a generic, white-label sign-in page using LiveView and the components in AshAuthentication.Phoenix.Components.

sign_out_route(auth_controller, path \\ "/sign-out", opts \\ [])

Generates a sign-out route which points to the sign_out action in your auth controller.

Types

auth_route_options()

@type auth_route_options() :: [path_option() | to_option() | scope_opts_option()]

Options that can be passed to auth_routes_for.

path_option()

@type path_option() :: {:path, String.t()}

A sub-path if required. Defaults to /auth.

scope_opts_option()

@type scope_opts_option() :: {:scope_opts, keyword()}

Any options which should be passed to the generated scope.

to_option()

@type to_option() :: {:to, AshAuthentication.Phoenix.Controller.t()}

The controller which will handle success and failure.

Functions

auth_routes(auth_controller, resource_or_resources, opts \\ [])

(macro)

@spec auth_routes(
  auth_controller :: module(),
  Ash.Resource.t() | [Ash.Resource.t()],
  auth_route_options()
) :: Macro.t()

Generates the routes needed for the various strategies for a given AshAuthentication resource.

This matches all routes at the provided path, which defaults to /auth. This means that if you have any other routes that begin with /auth, you will need to make sure this appears after them.

Upgrading from `auth_routes_for/2`

If you are using route helpers anywhere in your application, typically looks like Routes.auth_path/3 or Helpers.auth_path/3 you will need to update them to use verified routes. To see what routes are available to you, use mix ash_authentication.phoenix.routes.

If you are using any of the components provided by AshAuthenticationPhoenix, you will need to supply them with the auth_routes_prefix assign, set to the path you provide here (set to /auth by default).

You also will need to set auth_routes_prefix on the reset_route, i.e reset_route(auth_routes_prefix: "/auth")

Options

path - the path to mount auth routes at. Defaults to /auth. If changed, you will also want to change the auth_routes_prefix option in sign_in_route to match. routes.
not_found_plug - a plug to call if no route is found. By default, it renders a simple JSON response with a 404 status code.
as - the alias to use for the generated scope. Defaults to :auth.

auth_routes_for(resource, opts)

(macro)

This macro is deprecated. Replaced by `auth_routes/2..3`. Run `mix igniter.apply_upgrades ash_authentication_phoenix:2.10.5:2.10.6` to fix automatically. .

@spec auth_routes_for(Ash.Resource.t(), auth_route_options()) :: Macro.t()

Generates the routes needed for the various strategies for a given AshAuthentication resource.

This is required if you wish to use authentication.

Options

to - a module which implements the AshAuthentication.Phoenix.Controller behaviour. This is required.
path - a string (starting with "/") wherein to mount the generated routes.
scope_opts - any options to pass to the generated scope.

Example

scope "/", DevWeb do
  auth_routes_for(MyApp.Accounts.User,
    to: AuthController,
    path: "/authentication",
    scope_opts: [host: "auth.example.com"]
  )
end

confirm_route(resource, strategy, opts \\ [])

(macro)

@spec confirm_route(
  resource :: Ash.Resource.t(),
  strategy :: atom(),
  opts :: [
    {:path, String.t()}
    | {:live_view, module()}
    | {:as, atom()}
    | {:overrides, [module()]}
    | {:gettext_fn, {module(), atom()}}
    | {:gettext_backend, {module(), String.t()}}
    | {:on_mount, [module()]}
    | {:on_mount_prepend, [module()]}
    | {atom(), any()}
  ]
) :: Macro.t()

Generates a generic, white-label confirmation page using LiveView and the components in AshAuthentication.Phoenix.Components.

This is used when require_interaction? is set to true on a confirmation strategy.

Available options are:

path the path under which to mount the live-view. Defaults to
auth_routes_prefix if set, this will be used instead of route helpers when determining routes. Allows disabling helpers: true. If a tuple {:unscoped, path} is provided, the path prefix will not inherit the current route scope. "/<strategy>".
token_as_route_param? whether to use the token as a route parameter. i.e <path>/:token. Defaults to true.
live_view the name of the live view to render. Defaults to AshAuthentication.Phoenix.ConfirmLive.
as which is passed to the generated live route. Defaults to :auth.
overrides specify any override modules for customisation. See AshAuthentication.Phoenix.Overrides for more information.
gettext_fn as a {module :: module, function :: atom} tuple pointing to a (msgid :: String.t(), bindings :: keyword) :: String.t() typed function that will be called to translate each output text of the live view.
gettext_backend as a {module :: module, domain :: String.t()} tuple pointing to a Gettext backend module and specifying the Gettext domain. This is basically a convenience wrapper around gettext_fn.

All other options are passed to the generated scope.

magic_sign_in_route(resource, strategy, opts \\ [])

(macro)

@spec magic_sign_in_route(
  resource :: Ash.Resource.t(),
  strategy :: atom(),
  opts :: [
    {:path, String.t()}
    | {:live_view, module()}
    | {:as, atom()}
    | {:overrides, [module()]}
    | {:gettext_fn, {module(), atom()}}
    | {:gettext_backend, {module(), String.t()}}
    | {:on_mount, [module()]}
    | {:on_mount_prepend, [module()]}
    | {atom(), any()}
  ]
) :: Macro.t()

Generates a genric, white-label magic link sign in page using LiveView and the components in AshAuthentication.Phoenix.Components.

This is used when require_interaction? is set to true on a magic link strategy.

Available options are:

path the path under which to mount the live-view. Defaults to
auth_routes_prefix if set, this will be used instead of route helpers when determining routes. Allows disabling helpers: true. If a tuple {:unscoped, path} is provided, the path prefix will not inherit the current route scope. "/<strategy>".
token_as_route_param? whether to use the token as a route parameter. i.e <path>/:token. Defaults to true.
live_view the name of the live view to render. Defaults to AshAuthentication.Phoenix.MagicSignInLive.
as which is passed to the generated live route. Defaults to :auth.
overrides specify any override modules for customisation. See AshAuthentication.Phoenix.Overrides for more information.
gettext_fn as a {module :: module, function :: atom} tuple pointing to a (msgid :: String.t(), bindings :: keyword) :: String.t() typed function that will be called to translate each output text of the live view.
gettext_backend as a {module :: module, domain :: String.t()} tuple pointing to a Gettext backend module and specifying the Gettext domain. This is basically a convenience wrapper around gettext_fn.

All other options are passed to the generated scope.

reset_route(opts \\ [])

(macro)

@spec reset_route(
  opts :: [
    {:path, String.t()}
    | {:live_view, module()}
    | {:as, atom()}
    | {:overrides, [module()]}
    | {:gettext_fn, {module(), atom()}}
    | {:gettext_backend, {module(), String.t()}}
    | {:on_mount, [module()]}
    | {:on_mount_prepend, [module()]}
    | {atom(), any()}
  ]
) :: Macro.t()

Available options are:

path the path under which to mount the live-view. Defaults to /password-reset.
auth_routes_prefix if set, this will be used instead of route helpers when determining routes. Allows disabling helpers: true. If a tuple {:unscoped, path} is provided, the path prefix will not inherit the current route scope.
live_view the name of the live view to render. Defaults to AshAuthentication.Phoenix.ResetLive.
as which is passed to the generated live route. Defaults to :auth.
overrides specify any override modules for customisation. See AshAuthentication.Phoenix.Overrides for more information.
gettext_fn as a {module :: module, function :: atom} tuple pointing to a (msgid :: String.t(), bindings :: keyword) :: String.t() typed function that will be called to translate each output text of the live view.
gettext_backend as a {module :: module, domain :: String.t()} tuple pointing to a Gettext backend module and specifying the Gettext domain. This is basically a convenience wrapper around gettext_fn.
resources - Which resources should have their sign in UIs rendered. Defaults to all resources that use AshAuthentication.

All other options are passed to the generated scope.

sign_in_route(opts \\ [])

(macro)

@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()}}
    | {:on_mount_prepend, [module()]}
    | {atom(), any()}
  ]
) :: Macro.t()

Generates a generic, white-label sign-in page using LiveView and the components in AshAuthentication.Phoenix.Components.

This is completely optional.

Available options are:

path the path under which to mount the sign-in live-view. Defaults to /sign-in within the current router scope.
auth_routes_prefix if set, this will be used instead of route helpers when determining routes. Allows disabling helpers: true. If a tuple {:unscoped, path} is provided, the path prefix will not inherit the current route scope.
register_path - the path under which to mount the password strategy's registration live-view. If not set, and registration is supported, registration will use a dynamic toggle and will not be routeable to. If a tuple {:unscoped, path} is provided, the registration path will not inherit the current route scope.
reset_path - the path under which to mount the password strategy's password reset live-view, for a user to request a reset token by email. If not set, and password reset is supported, password reset will use a dynamic toggle and will not be routeable to. If a tuple {:unscoped, path} is provided, the reset path will not inherit the current route scope.
resources - Which resources should have their sign in UIs rendered. Defaults to all resources that use AshAuthentication.
live_view the name of the live view to render. Defaults to AshAuthentication.Phoenix.SignInLive.
as which is used to prefix the generated live_session and live route name. Defaults to :auth.
otp_app the otp app or apps to find authentication resources in. Pulls from the socket by default.
overrides specify any override modules for customisation. See AshAuthentication.Phoenix.Overrides for more information.
gettext_fn as a {module :: module, function :: atom} tuple pointing to a (msgid :: String.t(), bindings :: keyword) :: String.t() typed function that will be called to translate each output text of the live view.
gettext_backend as a {module :: module, domain :: String.t()} tuple pointing to a Gettext backend module and specifying the Gettext domain. This is basically a convenience wrapper around gettext_fn.
on_mount_prepend - Same as on_mount, but for hooks that need to be run before AshAuthenticationPhoenix's hooks.

All other options are passed to the generated scope.

sign_out_route(auth_controller, path \\ "/sign-out", opts \\ [])

(macro)

@spec sign_out_route(AshAuthentication.Phoenix.Controller.t(), path :: String.t(), [
  {:as, atom()} | {atom(), any()}
]) :: Macro.t()

Generates a sign-out route which points to the sign_out action in your auth controller.

This is optional, but you probably want it.

AshAuthentication.Phoenix.Router (ash_authentication_phoenix v2.13.1)

Usage

Adding Custom Fields to Authentication Forms

Step 1: Create a Component for Your Extra Fields

Step 2: Configure Overrides to Use Your Component

Step 3: Pass Overrides to Router Macro

Summary

Types

Functions

Types

auth_route_options()

path_option()

scope_opts_option()

to_option()

Functions

auth_routes(auth_controller, resource_or_resources, opts \\ [])

Upgrading from auth_routes_for/2

Options

auth_routes_for(resource, opts)

Options

Example

confirm_route(resource, strategy, opts \\ [])

magic_sign_in_route(resource, strategy, opts \\ [])

reset_route(opts \\ [])

sign_in_route(opts \\ [])

sign_out_route(auth_controller, path \\ "/sign-out", opts \\ [])

Upgrading from `auth_routes_for/2`