Using this module, Permit authorization can be integrated with Phoenix LiveView at three key points:

1. During mount (via the on_mount: Permit.Phoenix.LiveView.AuthorizeHook hook)
2. During live navigation (via the handle_params/3 callback)
3. During events (via the handle_event/3 callback)

This way, Permit.Phoenix's load-and-authorize mechanism occurs regardless of whether the user has navigated to the page directly (from outside a LiveView session), or has navigated to a URL that stays within the same LiveView session (or the same LiveView instance), and also when an event is triggered (e.g. a delete button is clicked).

Schematic overview

The diagram below illustrates the flow of authorization in Permit.Phoenix LiveView in the context of what happens when a user navigates to a LiveView route.

flowchart TD
  Start([USER NAVIGATES])
  Start --> Outside["From Outside
  (browser link, bookmark)"]
  Start --> SameSession["Same LiveView Session
  (diff instance)"]
  Start --> SameInstance["Same LiveView Instance
  (patch nav)"]

  Outside --> Mount["MOUNT PHASE
  New LiveView mounts, AuthorizeHook module
  attaches hooks to params and event handlers
  and loads & authorizes based on @live_action,
  then assigns to @loaded_resource(s)"]
  SameSession --> Mount

  SameInstance --> HandleParams["HANDLE_PARAMS/3
  Load & authorize based on @live_action
  Assign @loaded_resource(s)"]
  Mount --> HandleParams

  HandleParams --> Running["LiveView instance running"]
  Running -.-> HandleEvent["HANDLE_EVENT/3
  Authorize events via @permit_action
  or event_mapping/0"]

  Running -.-> HandleParams
  HandleEvent -.-> Running

Setup

In the router, in a live_session that authenticates the user, add Permit.Phoenix.LiveView.AuthorizeHook after the :ensure_authenticated hook at :on_mount:

live_session :require_authenticated_user,
  on_mount: [
    {MyAppWeb.UserAuth, :ensure_authenticated},
    Permit.Phoenix.LiveView.AuthorizeHook         # add Permit.Phoenix's hook at mount
  ] do
  live "/live_articles", ArticleLive.Index, :index
  live "/live_articles/new", ArticleLive.Index, :new
  live "/live_articles/:id/edit", ArticleLive.Index, :edit

  live "/live_articles/:id", ArticleLive.Show, :show
  live "/live_articles/:id/show/edit", ArticleLive.Show, :edit
end

Names of :live_action's defined in the router are important - they are directly mapped to Permit action names. If an action name is defined in your app's actions module (see Permit.Phoenix.Actions), or in the router, it will be generated as a convenience function in your permissions module.

# Your router

defmodule MyAppWeb.Router do
  use Phoenix.Router
  import Phoenix.LiveView.Router

  live_session :require_authenticated_user, on_mount: [
    {MyAppWeb.UserAuth, :ensure_authenticated},
    Permit.Phoenix.LiveView.AuthorizeHook
  ] do
    # Define routes with :live_action named :view and :all
    live("/articles/:id/view", MyAppWeb.ArticleLive, :view)
    live("/articles/:id/all", MyAppWeb.ArticleLive, :all)
  end
end

# Your actions module
defmodule MyApp.Actions do
  use Permit.Phoenix.Actions, router: MyAppWeb.Router

  # Permit.Phoenix.Actions includes :index, :show, :update, :edit, :create, :new, :delete
  # Specifying the router will include action names from the router

  # Clarify that the :view action relates to a single resource, not a listing.
  # :all will be a plural action, loading all articles for the current user.
  @impl true
  def singular_actions do
    [:view]
  end
end

# Your permissions module
defmodule MyApp.Permissions do
  use Permit.Ecto.Permissions, actions_module: MyApp.Actions

  # The :view and :all actions generate `view/2` and `all/2` functions, so we can use them here
  def can(:show = _action) do
    permit()
    |> view(MyApp.Article)
    |> all(MyApp.Article)
  end
end

Then, configure LiveViews to use the authorization mechanism. It can be put in individual modules, or in the MyAppWeb module's live_view function:

defmodule MyAppWeb do
  def live_view do
    quote do
      use Permit.Phoenix.LiveView,
        authorization_module: MyApp.Authorization,
        # other options...
    end
  end
end

Options can be set as use keywords, or as callback implementations (which take precedence). This way, you can override them in individual LiveViews. Typically, at the very least, you'll want to set the resource_module to the related schema.

defmodule MyAppWeb.ArticleLive.Index do
  use MyAppWeb, :live_view

  @impl true
  def resource_module, do: MyApp.Article
end

Navigation & mounting authorization

Navigating to a LiveView route results in triggering the handle_params/3 callback. This may occur in three scenarios:

• navigating from outside a LiveView session (e.g. from a link in an email or a browser bookmark),
• navigating within the same LiveView session, but a different LiveView instance,
• navigating within the same LiveView instance.

Authorization flow

The Permit.Phoenix.LiveView.AuthorizeHook module taps into the handle_params/3 callback processing. When it is triggered on navigation to a LiveView route, the route's :live_action is used to determine the action to authorize. Records are filtered and loaded is loaded using Permit.Ecto based on the resource_module and id_param_name/id_struct_field_name options, the base_query, and resolved authorization conditions (or with a loader function when Permit.Ecto is not used).

flowchart TD
  Start["HANDLE_PARAMS/3 TRIGGERED"]

  Hook["Hook attached by Permit.Phoenix
  ─────────────────────────────────────
  1. Get @live_action from socket
  2. Check if in except/0 (skip?)
  3. Determine singular vs plural"]

  ActionAuth["ACTION AUTHORIZATION
  ─────────────────────────────────────
  Fails if there is no permission to @live_action
  altogether: user |> can(:read, Article, ...)"]

  Singular["SINGULAR ACTION
  (:show, :edit, etc)
  ──────────────────────
  Load single record via id_param_name
  (id by default)"]

  Plural["PLURAL ACTION
  (:index, etc.)
  ──────────────────────
  Load all records filtered
  by user's permissions"]

  Start --> Hook
  Hook --> ActionAuth
  ActionAuth --> Singular
  ActionAuth --> Plural
  Singular --> Note1
  Plural --> Note1
  Note1[Record loading done using Permit.Ecto automatically generates query based on<br/>permissions and params. Alternatively, loader/1 callback loads records if Permit.Ecto not used.]

Now that the record (or list of records) is loaded, authorization is finally verified against resolved permissions. If it succeeds, a single record is assigned to :loaded_resource, or a list is assigned or streamed to :loaded_resources, and execution continues in the handle_params/3 callback implementation. Otherwise, depending on what kind of error happened, handle_unauthorized/2 or handle_not_found/1 is called. These callbacks may either halt (default), or continue so that we can still go back to handle_params/3, which is possible but discouraged.

flowchart TD
  AuthCheck["AUTHORIZATION CHECK"]

  Authorized["AUTHORIZED
  ──────────────────────
  {:cont, socket}
  with resource(s) assigned or streamed"]

  Unauthorized["UNAUTHORIZED
  ──────────────────────
  handle_unauthorized/2

  Default: flash + stay on page
  if possible, or redirect to
  fallback path"]

  NotFound["NOT FOUND
  ──────────────────────
  handle_not_found/1

  Default: raise error"]

  UserImplementation["YOUR handle_params/3 IMPLEMENTATION
  (receives socket with resources)"]

  AuthCheck --> Authorized
  AuthCheck --> Unauthorized
  AuthCheck --> NotFound
  Authorized --> UserImplementation
  Unauthorized --> UserImplementation
  NotFound --> UserImplementation

  linkStyle 4,5 stroke-dasharray: 5 5

Example of usage with a singular action:

@impl true
def handle_params(_params, _uri, socket) do
  # Article is loaded and authorized by Permit
  article = socket.assigns.loaded_resource

  {:noreply, socket |> assign(:title, article.title)}
end

If an action is defined as plural in the actions module, resources are either assigned to :loaded_resources (by default), or streamed as :loaded_resources if use_stream?/1 is true.

# Default: assign to `:loaded_resources`
@impl true
def handle_params(_params, _uri, socket) do
  # Article list is loaded to @loaded_resources
  {:noreply, socket}
end

# Optional: set `use_stream?/1` to `true` to use streams instead of assigns
@impl true
def use_stream?(_socket), do: true

@impl true
def handle_params(_params, _uri, socket) do
  # Article list available in @streams.loaded_resources
  {:noreply, socket}
end

Event authorization

Actions such as updating or deleting a resource are typically implemented in LiveView using handle_event/3. Permit taps into handle_event/3 processing and, depending on the event's nature:

• For events carrying an "id" param (e.g. record deletion from an index page), loads the record with Permit.Ecto (or a loader function) based on the ID param and a query based on the currently resolved permissions and puts it in assigns.
• For events that do not carry an "id" param (e.g. updating a record with form data), reloads the record currently assigned to @loaded_resource, using either Permit.Ecto (and the record's ID) or the existing loader function. This is done by default to ensure permissions are evaluated against the latest data. You can disable this behaviour by overriding reload_on_event?/2 (or by passing the :reload_on_event? option) if you prefer to reuse the already assigned record.

flowchart TD
  Start["USER TRIGGERS EVENT (e.g. click)"]

  Hook["Hook attached by Permit.Phoenix
  ─────────────────────────────────────
  1. Map event → action via:
     • @permit_action attributes
     • event_mapping/0 callback
     • default_event_mapping/0"]

  WithId["EVENT HAS 'id' PARAM
  (e.g. delete from index page)
  ──────────────────────
  Load record by ID from params"]

  NoId["NO 'id' PARAM
  (e.g. form submit)
  ──────────────────────
  RELOAD existing @loaded_resource
  (if reload_on_event? is true)"]

  AuthCheck["AUTHORIZATION CHECK"]

  Authorized["AUTHORIZED
  ──────────────────────
  Assign to: @loaded_resource"]

  Unauthorized["UNAUTHORIZED
  ──────────────────────
  handle_unauthorized/2

  Default: flash + stay on page
  or fallback_path"]

  NotFound["NOT FOUND
  ──────────────────────
  handle_not_found/1

  Default: raise error"]

  UserImplementation["YOUR handle_event/3 IMPLEMENTATION
  (@loaded_resource available)"]

  Start --> Hook
  Hook --> WithId
  Hook --> NoId
  WithId --> Note1
  NoId --> Note1
  Note1[Record loading done using Permit.Ecto automatically generates query based on<br/>permissions and params. Alternatively, loader/1 callback loads records if Permit.Ecto not used.]
  Note1 --> AuthCheck
  AuthCheck --> Authorized
  AuthCheck --> Unauthorized
  AuthCheck --> NotFound
  Authorized --> UserImplementation
  Unauthorized --> UserImplementation
  NotFound --> UserImplementation

  linkStyle 10,11 stroke-dasharray: 5 5

Usage

Event to action mapping is given using the @permit_action module attribute put right before an event handler.

@impl true
@permit_action :update
def handle_event("save", %{"article" => article_params}, socket) do
  article = socket.assigns.loaded_resource

  case MyApp.update_article(article_params) do
    # ...
  end
end

In this example, the "save" event handler is authorized against the :update action on MyApp.Article.

Default event mapping (Permit.Phoenix.LiveView.default_event_mapping/0) maps most common event names (strings) to action names (atoms) **except for the "save" event. Phoenix generates "save" event handler for both :create and :update actions, hence it must be explicitly provided in code.

When the handle_event/3 function is not implemented using pattern matching on the first argument, the event_mapping callback must be used instead.

@impl true
# "delete" event maps to :delete Permit action
def event_mapping, do: %{"delete" => :delete, "remove" => :delete}

@impl true
def handle_event(event_name, _params, _socket) when event_name in ["delete", "remove"] do
  # Resource is loaded and authorized by Permit
  article = socket.assigns.loaded_resource

  # Delete the record
  {:ok, _} = MyApp.Blog.delete_article(article)

  # If in an action like :index, stream the deletion to the client.
  # Permit either streams the viewed items or assigns them (see `use_stream?/1` callback)
  {:noreply, stream_delete(socket, :loaded_resources, article)}
end

If authorization fails, handle_unauthorized/2 is called. Handling authorization failure is as simple as:

@impl true
def handle_unauthorized(:delete, socket) do
  # You actually don't need to implement it, but it's useful for defining custom behaviour.
  {:halt, socket |> put_flash(:error, "You are not authorized to delete this article")}
end

The full list of options can be found in this module's callback specifications.

Handling failures

Permit allows customizing the way authorization failures and record-not-found errors are handled, providing sane defaults for both scenarios.

Authorization failure

The handle_unauthorized/2 callback is provided to enable authorization failure handling customization. It is used both in navigation and event authorization. It should return either {:halt, socket} or {:cont, socket} depending on desired behaviour.

When navigating to a different LiveView instance, or from outside a LiveView session, the new LiveView has to be mounted. In this case, a :halt and a redirect is required. If it's a navigation within the same LiveView instance, or when it occurs in event authorization, you can use either :halt or :cont and remain on the page, displaying an error or performing any appropriate action.

For convenience, this module provides the mounting?/1 function, which returns true if the LiveView is in the mounting phase, and false otherwise. It can be used in the handle_unauthorized/2 callback implementation to determine the appropriate response in a custom way.

@impl true
def handle_unauthorized(action, socket) do
  if mounting?(socket) do
    {:halt, push_navigate(socket, to: socket.view.fallback_path())}
  else
    # Do whatever you want with the socket here...
    socket = assign(socket, :unauthorized, true)

    # Use :cont to continue processing the module's handle_params/3 handlers,
    # or :halt to halt the processing.
    {:halt, socket |> put_flash(:error, "You are not authorized to access this page")}
  end
end

By default, the handle_unauthorized/2 callback is implemented to do one of the following, whichever is first possible:

• remain on the same page and display a flash error message,
• halt the processing and redirect to the :fallback_path (with a flash error), defaulting to /.

Record not found

The handle_not_found/1 callback is provided to enable record-not-found error handling customization.

When using Permit.Ecto to load authorized records, a query is constructed based on defined permissions

• e.g. if the permission is view(Article, author_id: user_id, published: true), the query will be constructed as SELECT * FROM articles WHERE author_id = $1 AND published = TRUE AND id = $2, containing both record ID and authorization conditions. If a matching record is found, it's assigned and available to the handler; otherwise, it can mean either of the two:
• the record with given ID exists, but authorization conditions are not met,
• the record does not exist at all. To distinguish between these two cases, Permit.Ecto will execute a second query with only the record ID and whatever is defined in base_query/1 callback. If no matching record is found, it will call the handle_not_found/1 callback. Otherwise, the handle_unauthorized/2 callback is called.

By default, the handle_not_found/1 callback is implemented to raise a Permit.Phoenix.RecordNotFoundError.

See documentation for handle_unauthorized/2 and handle_not_found/1 for more guidance and explanation of default behaviour.