AshAuthentication.Phoenix.Router (ash_authentication_phoenix v2.6.2)
View SourcePhoenix 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_for MyApp.Accounts.User, to: AuthController
reset_route auth_routes_prefix: "/auth"
end
Summary
Types
Options that can be passed to auth_routes_for
.
A sub-path if required. Defaults to /auth
.
Any options which should be passed to the generated scope.
The controller which will handle success and failure.
Functions
Generates the routes needed for the various strategies for a given AshAuthentication resource.
Generates the routes needed for the various strategies for a given AshAuthentication resource.
Generates a generic, white-label confirmation page using LiveView and the components in
AshAuthentication.Phoenix.Components
.
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.
Generates a generic, white-label sign-in page using LiveView and the
components in AshAuthentication.Phoenix.Components
.
Generates a sign-out route which points to the sign_out
action in your auth
controller.
Types
@type auth_route_options() :: [path_option() | to_option() | scope_opts_option()]
Options that can be passed to auth_routes_for
.
@type path_option() :: {:path, String.t()}
A sub-path if required. Defaults to /auth
.
@type scope_opts_option() :: {:scope_opts, keyword()}
Any options which should be passed to the generated scope.
@type to_option() :: {:to, AshAuthentication.Phoenix.Controller.t()}
The controller which will handle success and failure.
Functions
@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 theauth_routes_prefix
option insign_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
.
@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 theAshAuthentication.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
@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()]} | {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 "/<strategy>".token_as_route_param?
whether to use the token as a route parameter. i.e<path>/:token
. Defaults totrue
.live_view
the name of the live view to render. Defaults toAshAuthentication.Phoenix.ConfirmLive
.as
which is passed to the generatedlive
route. Defaults to:auth
.overrides
specify any override modules for customisation. SeeAshAuthentication.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 aroundgettext_fn
.
All other options are passed to the generated scope
.
@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()]} | {atom(), any()} ] ) :: Macro.t()
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.
Available options are:
path
the path under which to mount the live-view. Defaults to/password-reset
.live_view
the name of the live view to render. Defaults toAshAuthentication.Phoenix.ResetLive
.as
which is passed to the generatedlive
route. Defaults to:auth
.overrides
specify any override modules for customisation. SeeAshAuthentication.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 aroundgettext_fn
.
All other options are passed to the generated scope
.
@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()}} | {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 disablinghelpers: 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 useAshAuthentication
.live_view
the name of the live view to render. Defaults toAshAuthentication.Phoenix.SignInLive
.auth_routes_prefix
the prefix to use for the auth routes. Defaults to/auth
.as
which is used to prefix the generatedlive_session
andlive
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. SeeAshAuthentication.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 aroundgettext_fn
.
All other options are passed to the generated scope
.
@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.