View Source AshAuthentication.Phoenix.Router (ash_authentication_phoenix v2.3.0)
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_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 password reset page using LiveView and the
components in AshAuthentication.Phoenix.Components
.
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 reset_route( opts :: [ {:path, String.t()} | {:live_view, module()} | {:as, atom()} | {:overrides, [module()]} | {:on_mount, [module()]} | {atom(), any()} ] ) :: Macro.t()
Generates a generic, white-label password reset page using LiveView and the
components in AshAuthentication.Phoenix.Components
.
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. all other options are passed to the generatedscope
.
This is completely optional, in particular, if the reset_path
option is passed to the
sign_in_route
helper, using the reset_route
helper is redundant.
@spec sign_in_route( opts :: [ {:path, String.t()} | {:live_view, module()} | {:as, atom()} | {:overrides, [module()]} | {:on_mount, [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 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. 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.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.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.