# LetMe
[](https://github.com/woylie/let_me/actions) [](https://hex.pm/packages/let_me) [](https://hexdocs.pm/let_me/readme.html) [](https://coveralls.io/github/woylie/let_me)
LetMe is an authorization library for Elixir that defines a Domain Specific
Language (DSL) for authorization rules.
Policy expressions are optimized at compile time and evaluated lazily using
[Spek](https://github.com/woylie/spek). It is possible to get the evaluated
part of the policy expression in the error case, which can be useful for
debugging, detailed error messages, or authorization decision logs.
The library also provides introspection functions that allow you to:
- List all authorization rules including their boolean expression tree for a
documentation page.
- Fetch an authorization rule by name.
- Filter authorization rules by subject, object, or checks that are applied.
## Installation
Add LetMe to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:let_me, "~> 3.0.1"}
]
end
```
Include LetMe in your `.formatter.exs` file:
```elixir
[
import_deps: [:let_me]
]
```
This ensures that `mix format` doeos not add unnecessary parentheses to the
LetMe macro calls for policy definitions.
## Policy module
You define your authorization rules in a policy module using the LetMe macros.
These rules are compiled into [Spek](https://github.com/woylie/spek)
expressions, and functions for both authorization checks and introspection are
defined.
For instance, this is how you could define a policy for a simple article CRUD
interface:
```elixir
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
desc "Create a new article"
end
# Viewing articles is always allowed, unless the user is banned.
action :read do
allow true
deny :banned
desc "Read an article"
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]
desc "Update an article"
end
# Deleting an article is allowed if the user is an editor.
action :delete do
allow role: :editor
desc "Delete an article"
end
end
end
```
You can work with a single policy module, or you can define one policy module
for each of your contexts.
While this example uses Role-Based Access Control (RBAC), LetMe does not make
any assumptions about your access control model. You can define your
authorization rules in any way you see fit.
## Check module
Authorization rules are based on the subject (usually the current user), the
object on which the action is performed, and the action itself (the verb). LetMe
does not enforce a particular authorization model or check implementation.
The checks passed to `LetMe.Policy.allow/1` reference functions in your own
check module (by default `__MODULE__.Checks`; in this example,
`MyApp.Policy.Checks`). Each function in your check module should
accept the subject, the object, and optionally an extra argument. If no options
are passed to `allow` or `deny` (e.g. `deny :banned`), the check function must
be a 2-arity function. If an option is passed (e.g. `allow role: :writer`), the
function must be a 3-arity function. All check functions must return a boolean,
an `:ok` or `:error` tuple, `:ok`, or `:error` (see `t:Spek.result/0`).
For the policy example provided earlier, a corresponding check module could look
like this:
```elixir
defmodule MyApp.Policy.Checks do
alias MyApp.Accounts.Scope
alias MyApp.Accounts.User
@doc """
Returns `true` if the `banned` flag is set on the user.
"""
def banned(%Scope{user: %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(
%Scope{user: User{id: id}},
%{user_id: id}
) 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(%Scope{user: %User{role: role}}, _object, role), do: true
def role(_, _, _), do: false
end
```
Note the usage of the `Scope` struct. This is a struct defined in your
application that contains the current user and any additional information
needed for policy decisions, like the remote IP address or the
authenticator assurance level (AAL).
The usage of the `Scope` struct is in line with a new feature of the Phoenix
generators introduced in Phoenix 1.8. You could also use the `User` struct
directly, but basing authorization rules on a `Scope` struct will make it
easier to update your application later if your authorization requirements
become more complex.
## Callbacks
Adding `use LetMe.Policy` to the start of your policy module will generate
several functions from the authorization rules:
- 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
With the authorization rules and checks in place, you can authorize user actions
wherever needed. A natural place are the functions in your context modules. This
way, authorization checks are part of your business logic, and they will be
applied independently from the interface that is used. For example, even if you
have a LiveView application, a REST API, and a GraphQL API, the authorization
checks will only have to be added once to the context modules.
A Blog context could like this:
```elixir
defmodule MyApp.Blog do
alias MyApp.Accounts.Scope
alias MyApp.Blog.Article
alias MyApp.Policy
def list_articles(%Scope{} = scope) do
with :ok <- Policy.authorize(:article_read, scope) do
{:ok, Repo.all(Article)}
end
end
def fetch_article(%Scope{} = scope, id) do
with :ok <- Policy.authorize(:article_read, scope, id) do
case Repo.get(Article, id) do
nil -> {:error, :not_found}
article -> {:ok, article}
end
end
end
def create_article(%Scope{user: %User{} = current_user}, params) do
with :ok <- Policy.authorize(:article_create, current_user) do
%Article{}
|> Article.changeset(params)
|> Repo.insert()
end
end
def update_article(
%Scope{user: %User{} = current_user},
%Article{} = article,
params
) do
with :ok <- Policy.authorize(:article_update, current_user, article) do
article
|> Article.changeset(params)
|> Repo.update()
end
end
def delete_article(
%Scope{user: %User{} = current_user},
%Article{} = article
) do
with :ok <- Policy.authorize(:article_delete, current_user, article) do
Repo.delete(article)
end
end
end
```
Every context function takes the `Scope` struct as the first argument. Before
performing any actions on the articles, we first ensure the current user
is authorized to perform the intended action.
#### Error responses
By default, the `c:LetMe.Policy.authorize/4` function returns
`{:error, :unauthorized}` if an authorization check fails.
```elixir
iex> MyApp.Policy.authorize(:article_read, scope)
{:error, :unauthorized}
```
To obtain a `LetMe.UnauthorizedError` struct with the evaluated expression,
set the `error` option on `LetMe.Policy` to `:detailed`.
```elixir
use LetMe.Policy, error: :detailed
```
To obtain a `LetMe.UnauthorizedError` struct without the evaluated expression,
set `error` option to `:simple`.
You can also override the default value at runtime:
```elixir
iex> MyApp.Policy.authorize(:article_update, scope, object, error: :detailed)
%LetMe.UnauthorizedError{
message: "unauthorized",
expression: %Spek.AnyOf{
children: [
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :editor],
result: false,
satisfied?: false
},
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :writer],
result: false,
satisfied?: false
}
]
}
}
iex> MyApp.Policy.authorize(:article_update, scope, object, error: :simple)
%LetMe.UnauthorizedError{
message: "unauthorized",
expression: nil
}
iex> MyApp.Policy.authorize(:article_update, scope, object, error: :forbidden)
{:error, :forbidden}
```
#### Typespecs
LetMe automatically generates typespecs for the authorize functions in your
policy modules, which helps Dialyzer to ensure that only valid actions are
passed to the authorize functions.
### Introspection
LetMe generates introspection functions for your authorization rules. This can
be useful if you want to render a documentation page, or if you want to show
a user's capabilities in their user profile.
```elixir
iex> MyApp.Policy.list_rules()
[
%LetMe.Rule{
action: :create,
expression: %Spek.AnyOf{
children: [
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :admin]
},
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :writer]
}
]
},
description: "Create a new article",
name: :article_create,
object: :article,
pre_hooks: [],
metadata: []
},
# ...
]
```
To find a specific rule by its name:
```elixir
iex> MyApp.Policy.get_rule(:article_create)
%LetMe.Rule{
action: :create,
expression: %Spek.AnyOf{
children: [
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :admin]
},
%Spek.Check{
module: MyApp.Policy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :writer]
}
]
},
name: :article_create,
object: :article,
# ...
}
```
To list all actions associated with a particular role (or any other check):
```elixir
iex> MyApp.Policy.list_rules(check: {:role, :writer})
[
%LetMe.Rule{
action: :create,
object: :article,
# ...
},
%LetMe.Rule{
action: :update,
object: :article,
# ...
}
]
```
You can also define metadata on an `action`, which can be used to extend
the library's functionality.
For example, imagine you want to expose certain actions through your Absinthe
GraphQL schema while excluding others. You could achieve this by adding a
`:gql_exclude` key to the metadata.
```elixir
defmodule GraphqlPolicy do
use LetMe.Policy
object :user do
action :disable do
allow role: :admin
metadata :gql_exclude, true
end
end
end
```
```elixir
iex> MyApp.Policy.get_rule(:user_disable)
%LetMe.Rule{
action: :disable,
expression: %Spek.Check{
module: GraphqlPolicy.Checks,
fun: :role,
args: [{:ctx, :subject}, {:ctx, :object}, :admin]
},
description: nil,
name: :user_disable,
object: :user,
pre_hooks: [],
metadata: [
gql_exclude: true
]
}
```
## Scoped queries
Often, a user should have access to a certain resource type, but only to 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 narrow down 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.
```elixir
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:
```elixir
def list_articles(%Scope{user: %User{} = current_user} = scope) do
with :ok <- Policy.authorize(:article_read, scope) do
articles =
Article
|> Article.scope(current_user)
|> Repo.all()
{:ok, articles}
end
end
def fetch_article(
%Scope{user: %User{} = current_user} = scope,
id
) 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](https://hex.pm/packages/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, a 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`.
```elixir
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.
```elixir
def list_users(%Scope{user: %User{} = current_user} = scope) 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.
```elixir
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 limited dependencies (LetMe depends on a single
library by the same author).
## 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.
## Status
This library is actively maintained, but given its narrow feature set, you may
not see frequent updates. If you miss a feature or encounter an issue, don't
hesitate to open an issue.
## Alternatives
For comparison, consider exploring these Elixir libraries:
- [Canada](https://hex.pm/packages/canada)
- [Canary](https://hex.pm/packages/canary)
- [Bodyguard](https://hex.pm/packages/bodyguard)
- [Speakeasy](https://hex.pm/packages/speakeasy)
The article
[Authorization for Phoenix Contexts](https://dockyard.com/blog/2017/08/01/authorization-for-phoenix-contexts)
may also be a helpful resource.