LetMe

LetMe is a user-friendly authorization library for Elixir. Designed with a simple and expressive Domain Specific Language (DSL), it provides an intuitive way to define and manage your authorization rules.

The strength of LetMe lies not only in its simplicity but also in its introspection capabilities. It equips you with functions to answer important questions about your application's authorization landscape, such as:

• Which actions are defined in my application?
• What are the conditions for a particular action?
• Which actions are permissible for a user assigned a specific role?

With its intuitive DSL for rule definition coupled with introspection capabilities, LetMe makes managing permissions in your application a breeze.

Installation

Add LetMe to your list of dependencies in mix.exs:

def deps do
  [
    {:let_me, "~> 1.2.2"}
  ]
end

Include LetMe in your .formatter.exs file:

[
  import_deps: [:let_me]
]

This ensures that your LetMe authorization rules are formatted correctly when you run mix format.

Now, you're ready to start defining authorization rules with LetMe!

Policy module

The Policy module sits at the heart of LetMe. It provides macros that allow you to define the authorization rules of your application. These rules are then compiled into functions for both authorization checks and introspection.

For instance, here's how you might define a policy for a simple article CRUD interface:

defmodule MyApp.Policy do
  use LetMe.Policy

  object :article do
    # Creating articles is allowed if the user role is `editor` or `writer`.
    action :create do
      allow role: :editor
      allow role: :writer
    end

    # Viewing articles is always allowed, unless the user is banned.
    action :read do
      allow true
      deny :banned
    end

    # Updating an article is allowed if (the user role is `editor`) OR
    # (the user role is `writer` AND the article belongs to the user).
    action :update do
      allow role: :editor
      allow [:own_resource, role: :writer]
    end

    # Deleting an article is allowed if the user is an editor.
    action :delete do
      allow role: :editor
    end
  end
end

The design of your policy modules—whether you have a single module for your entire application, one for each context, or some other arrangement—is completely up to you. LetMe offers the flexibility to organize your policy in the way that best fits your application's needs.

Please note that while this example uses Role-Based Access Control (RBAC) for simplicity, LetMe doesn't make any assumptions about your access control model. You are completely free to define your authorization rules in any way you see fit.

Check module

Authorization rules, generally speaking, are based on the subject (usually the current user), the object on which the action is performed, and the action itself (the verb). LetMe doesn't enforce a particular authorization model or check implementation, instead allowing you to define what makes sense for your application.

The checks passed to LetMe.Policy.allow/1 reference functions in your own check module (by default __MODULE__.Checks, so in the given example, this would be MyApp.Policy.Checks). Each function in your check module should accept the subject, the object, and optionally an extra argument. They must return a boolean value indicating the result of the check.

For the policy example provided earlier, a corresponding check module could look like this:

defmodule MyApp.Policy.Checks do
  alias MyApp.Accounts.User

  @doc """
  Returns `true` if the `banned` flag is set on the user.
  """
  def banned(%User{banned: banned}, _, _), do: banned

  @doc """
  Checks whether the user ID of the object matches the ID of the current user.

  Assumes that the object has a `:user_id` field.
  """
  def own_resource(%User{id: id}, %{user_id: id}, _opts) when is_binary(id), do: true
  def own_resource(_, _, _), do: false

  @doc """
  Checks whether the user role matches the role passed as an option.

  ## Usage

      allow role: :editor

  or

      allow {:role, :editor}
  """
  def role(%User{role: role}, _object, role), do: true
  def role(_, _, _), do: false
end

This way, you can establish checks that are perfectly tailored to your application's specific authorization requirements.

Callbacks

When you incorporate use LetMe.Policy at the start of your policy module, LetMe generates a suite of useful functions for you:

• Authorization functions: See c:LetMe.Policy.authorize/4, c:LetMe.Policy.authorize!/4 and c:LetMe.Policy.authorize?/4.
• Introspection functions: See c:LetMe.Policy.list_rules/0, c:LetMe.Policy.list_rules/1, c:LetMe.Policy.get_rule/1 and others.

Authorization

You can employ the authorization functions wherever your application needs to make authorization decisions. An ideal place to use these functions would be in your context modules. Here's an example illustrating how you could incorporate authorization into a blog's context module:

defmodule MyApp.Blog do
  alias MyApp.Accounts.User
  alias MyApp.Blog.Article
  alias MyApp.Policy

  def list_articles(%User{} = current_user) do
    with :ok <- Policy.authorize(:article_read, current_user) do
      {:ok, Repo.all(Article)}
    end
  end

  def fetch_article(id, %User{} = current_user) do
    with :ok <- Policy.authorize(:article_read, current_user, id) do
      case Repo.get(Article, id) do
        nil -> {:error, :not_found}
        article -> {:ok, article}
      end
    end
  end

  def create_article(params, %User{} = current_user) do
    with :ok <- Policy.authorize(:article_create, current_user) do
      %Article{}
      |> Article.changeset(params)
      |> Repo.insert()
    end
  end

  def update_article(%Article{} = article, params, %User{} = current_user) do
    with :ok <- Policy.authorize(:article_update, current_user, article) do
      article
      |> Article.changeset(params)
      |> Repo.update()
    end
  end

  def delete_article(%Article{} = article, %User{} = current_user) do
    with :ok <- Policy.authorize(:article_delete, current_user, article) do
      Repo.delete(article)
    end
  end
end

In this example, before performing any actions on the articles, we first ensure the current user is authorized to perform the intended action. This makes our application secure by making sure only authorized users can perform sensitive operations.

Typespecs

LetMe automatically generates typespecs for the authorize functions in your policy modules. This helps you to leverage Dialyzer's static type checking to ensure valid actions are specified in your authorize calls. It's another way LetMe helps you write reliable, error-free code.

Introspection

LetMe equips you with introspection functions, enabling you to access the comprehensive list of authorization rules. This can be beneficial, for instance, to render them on a documentation page:

iex> MyApp.Policy.list_rules()
[
  %LetMe.Rule{
    action: :create,
    allow: [
      [role: :admin],
      [role: :writer]
    ],
    deny: [],
    description: nil,
    name: :article_create,
    object: :article,
    pre_hooks: [],
    metadata: []
  },
  # ...
]

If you wish to find a specific rule by its name, you can do so as well:

iex> MyApp.Policy.get_rule(:article_create)
%LetMe.Rule{
  action: :create,
  allow: [
    [role: :admin],
    [role: :writer]
  ],
  name: :article_create,
  object: :article,
  # ...
}

Moreover, you can list all actions associated with a particular role (or any other check):

iex> MyApp.Policy.list_rules(allow: {:role, :writer})
[
  %LetMe.Rule{
    action: :create,
    object: :article,
    # ...
  },
  %LetMe.Rule{
    action: :update,
    object: :article,
    # ...
  }
]

You can also define metadata on an action. This feature can be used to extend the library's functionality.

For example, imagine wanting to expose certain actions through your Absinthe GraphQL schema but needing to exclude others. You could achieve this by adding a :gql_exclude key to the metadata.

defmodule GraphqlPolicy do
  use LetMe.Policy

  object :user do
    action :disable do
      allow role: :admin
      metadata :gql_exclude, true
    end
  end
end

iex> MyApp.Policy.get_rule(:user_disable)
%LetMe.Rule{
  action: :disable,
  allow: [
    [role: :admin]
  ],
  deny: [],
  description: nil,
  name: :user_disable,
  object: :user,
  pre_hooks: [],
  metadata: [
    gql_exclude: true
  ]
}

This gives you the power to customize your authorization policies even further.

Scoped queries

There are situations where a user, despite having general access to a certain resource type, is only permitted to view a subset of the data. Consider a blog system: a user might be restricted to viewing only published articles, unless they hold the role of a writer. Similarly, in a system where users are part of specific companies, they might only be allowed to see users from their own company.

To tailor your queries based on the user type, implement the c:LetMe.Schema.scope/3 callback of the LetMe.Schema behavior, typically within your Ecto schema module.

defmodule MyApp.Blog.Article do
  use Ecto.Schema
  use LetMe.Schema

  import Ecto.Query
  alias MyApp.Accounts.User

  # Ecto schema and changeset

  @impl LetMe.Schema
  def scope(q, user, opts \\ nil)
  def scope(q, %User{role: :editor}, _), do: q
  def scope(q, %User{role: :writer}, _), do: q
  def scope(q, %User{}, _), do: where(q, published: true)
end

In this example, the Ecto query is modified to only return published articles, unless the user is an editor or writer. The third argument can be utilized for additional options.

With this setup, your list and fetch functions can be updated as follows:

def list_articles(%User{} = current_user) do
  with :ok <- Policy.authorize(:article_read, current_user) do
    articles =
      Article
      |> Article.scope(current_user)
      |> Repo.all()

    {:ok, articles}
  end
end

def fetch_article(id, %User{} = current_user) do
  with :ok <- Policy.authorize(:article_read, current_user, id) do
    result =
      Article
      |> where(id: ^id)
      |> Article.scope(current_user)
      |> Repo.one()

    case result do
      nil -> {:error, :not_found}
      article -> {:ok, article}
    end
  end
end

If you've worked with Bodyguard before, this might look familiar. In Bodyguard, you can find a Bodyguard.scope/2 function that derives the Ecto schema module from the Ecto.Queryable and forwards the call to that module. In LetMe, you need to call the scope/2 function of your Ecto schema directly. The behaviour then only serves to enforce this pattern.

Field redactions

In certain scenarios, a user may be authorized to access a resource but should only see a subset of its fields. For instance, one user might be able to see basic details of another user, such as name and avatar, but shouldn't see sensitive information like email or phone number. One way to manage such cases would be to conditionally show or hide specific information on the frontend. However, a cleaner solution is to have your context functions omit sensitive fields entirely.

To assist in these kinds of situations, the LetMe.Schema behaviour has another callback: c:LetMe.Schema.redacted_fields/3.

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  use LetMe.Schema

  alias MyApp.Accounts.User

  # Ecto schema and changeset

  @impl LetMe.Schema
  def redacted_fields(%User{}, %User{role: :admin}, _), do: []
  def redacted_fields(%User{id: id}, %User{id: id}, _), do: []
  def redacted_fields(%User{}, %User{}, _), do: [:email, :phone_number]
end

The redacted_fields/2 function takes the object as the first argument, the subject as the second argument, and an options argument. The function should return a list of fields to redact.

In the example above, all fields are visible if the user has an 'admin' role, or if the user being viewed (the object) is the same as the current user (the subject). In other cases, the 'email' and 'phone_number' fields are hidden.

There are two strategies for handling field redactions:

1. Modify the query to exclude the redacted fields.
2. Redact the fields after retrieving the resource(s) from the database.

Modifying the query

One approach to field redaction involves adjusting the database query to exclude redacted fields. Ecto's __schema__/1 function can retrieve the non-virtual schema fields from your Ecto module. From this list, you can reject any redacted fields and add a select clause that includes only the unredacted fields.

def list_users(%User{} = current_user) do
  fields = User.__schema__(:fields)
  filtered_fields = LetMe.reject_redacted_fields(fields, %User{}, current_user)

  Article
  |> select(^filtered_fields)
  |> Repo.all()
end

This method has the advantage of preventing the transfer of redacted fields from the database. However, it also comes with several drawbacks:

1. Decisions about which fields to select cannot be made based on data in the struct. For instance, with the redacted_fields/2 function described earlier, we can ensure that admins can see all fields, but we cannot guarantee that users can view all fields in their own user account.
2. All redacted fields will appear as nil, and you won't be able to distinguish between fields that were redacted and fields that are simply empty. This distinction might be necessary for display in the frontend.
3. More complex select clauses may not be compatible with this syntax.

Redacting the query result

To address the limitations of modifying the query, you can redact fields after retrieving the data from the database. This can be done using the LetMe.redact/2 function.

def list_articles(%User{} = current_user) do
  Article
  |> Repo.all()
  |> LetMe.redact(current_user)
end

The redact function can handle structs, lists of structs, and nil values.

Why use this library?

Consider using this library if:

• You're seeking an easy-to-read DSL for authorization rules that offers the flexibility to implement your authorization checks as desired.
• You prefer to locate your authorization rules within your business layer, thereby decoupling them from your interfaces.
• You'd like to centralize your authorization rules in one place (or one per context).
• You want to generate a list of authorization rules.
• You need to filter your authorization rules, e.g., to identify which actions a certain user role can perform.
• You're in need of a library that aids with query scopes and field redactions.
• You prefer a library with zero dependencies.

When not to use this library?

This library might not be the best fit if:

• You prefer to couple authorization checks with your interfaces.
• You favor using plugs or middlewares for authorization checks and require ready-made solutions (though you can create your own plugs and middlewares around this library's functions).
• You dislike DSLs and prefer to write functions directly (keep in mind, the DSL only describes which checks to run and how to apply them; you'll still write the actual checks as regular functions).
• Introspection isn't a priority for you.
• You need to provide details on why an authorization request fails. Checks in LetMe currently return only a boolean value, meaning users receive a generic error without knowing which exact check failed.

Status

This library is actively maintained. Given its zero dependencies and precisely scoped feature set, you may not see frequent updates. However, this is not an indication of stagnation but of stability. If you ever find something missing or encounter an issue, don't hesitate to open an issue – your feedback and contributions are always welcome.

Alternatives

For comparison, consider exploring these Elixir libraries:

• Canada
• Canary
• Bodyguard
• Speakeasy

The article Authorization for Phoenix Contexts may also be a helpful resource.