Define composable authorization policies for actors in your system.

A policy is a data structure created for an actor in your system that defines the schemas that actor can access, the actions they can take, and any restrictions to the set of resources that can be accessed. These policies are generally created implicitly for actors passed to functions defined by Janus.Authorization, but they can also be created with build_policy/2.

creating-a-policy-modules

Creating a policy modules

While you can create a policy module with use Janus.Policy, you will usually invoke use Janus and implement build_policy/2:

defmodule MyApp.Policy do
  use Janus

  @impl true
  def build_policy(policy, _actor) do
    policy
  end
end

An implementation for build_policy/1 is injected into the policy module.

Policy modules can now be used to generate policy structs explicitly (though they will usually be created implicitly when calling functions defined by Janus.Authorization).

iex> policy = MyApp.Policy.build_policy(:my_user)
%Janus.Policy{actor: :my_user, rules: %{...}}

iex> MyApp.SecondaryPolicy.build_policy(policy)
%Janus.Policy{actor: :my_user, rules: %{...}}

permissions-with-allow-and-deny

Permissions with allow and deny

Permissions are primarily defined using allow/4 and deny/4, which allows or denies an action on a resource if a set of conditions match. Both functions take the same arguments and options. When permissions are being checked, multiple allow rules combine using logical-or, with deny rules overriding allow.

For example, the following policy would allow a moderator to edit their own comments and any comments flagged for review, but not those made by an admin.

@impl true
def build_policy(policy, %User{role: :moderator} = user) do
  policy
  |> allow(Comment, :update, where: [user: [id: user.id]])
  |> allow(Comment, :update, where: [flagged_for_review: true])
  |> deny(Comment, :update, where: [user: [role: :admin]])
end

While set of keyword options passed to allow and deny are reminiscent of keyword-based Ecto queries, but since they are functions and not macros, there is no need to use the ^value syntax used in Ecto. For example, the following would result in an error:

allow(policy, Comment, :update, where: [user: [id: ^user.id]])

where-and-where_not-conditions

:where and :where_not conditions

These conditions match if the associated fields are equal to each other. For instance, the moderation example above could also be written as:

@impl true
def build_policy(policy, %User{role: :moderator} = user) do
  policy
  |> allow(Comment, :update, where: [user_id: user.id])
  |> allow(Comment, :update,
    where: [flagged_for_review: true],
    where_not: [user: [role: :admin]]
  )
end

Multiple conditions within the same allow/deny are combined with a logical-and, so this might be translated to English as "allow moderators to edit comments they made or to edit comments flagged for review that were not made by an admin".

or_where-conditions

:or_where conditions

You can also use :or_where to combine with all previous conditions. For instance, the two examples above could also be written as:

@impl true
def build_policy(policy, %User{role: :moderator} = user) do
  policy
  |> allow(Comment, :update,
    where: [flagged_for_review: true],
    where_not: [user: [role: :admin]],
    or_where: [user_id: user.id]
  )
end

An :or_where condition applies to all clauses before it. Using some pseudocode for demonstration, the above would read:

# (flagged_for_review AND NOT user.role == :admin) OR user_id == user.id

These clauses could be reordered to have a different meaning:

policy
|> allow(Comment, :update,
  where: [flagged_for_review: true],
  or_where: [user_id: user.id],
  where_not: [user: [role: :admin]]
)

# (flagged_for_review OR user_id == user.id) AND NOT user.role == :admin

attribute-checks-with-functions

Attribute checks with functions

When equality is not a sufficient check for an attribute, a function can be supplied.

For instance, a published_at field might be used to schedule posts. Users may only have permission to read posts where published_at is in the past, but we can only check for equality using the basic keyword syntax presented above. In these cases, you can defer this check using an arity-3 function:

@impl true
def build_policy(policy, _actor) do
  policy
  |> allow(Comment, :read, where: [published_at: &in_the_past?/3])
end

def in_the_past?(:boolean, record, :published_at) do
  if value = Map.get(record, :published_at) do
    DateTime.compare(DateTime.utc_now(), value) == :gt
  end
end

def in_the_past?(:dynamic, binding, :published_at) do
  now = DateTime.utc_now()
  Ecto.Query.dynamic(^now > as(^binding).published_at)
end

As seen in the example above, functions must define at least two clauses based on their first argument, :boolean or :dynamic, so that they can handle both operations on a single record and operations that should compose with an Ecto query.

working-with-rulesets

Working with rulesets

Policies can also be defined by attaching rulesets created using allow/3 and deny/3. Instead of taking a policy as a first argument, these functions take a schema (or a ruleset).

Rulesets are specific to an individual schema and can be attached to a policy using attach/2. For example:

@impl true
def build_policy(policy, actor) do
  policy
  |> attach(rules_for(Thread, actor))
  |> attach(rules_for(Post, actor))
end

defp rules_for(Thread, %User{id: user_id}) do
  Thread
  |> allow(:read, where: [archived: false])
  |> allow([:create, :update], where: [creator_id: user_id])
end

defp rules_for(Thread, nil) do
  Thread
  |> allow(:read, where: [archived: false, visibility: :public])
end

defp rules_for(Post, _actor) do
  Post
  |> allow(:read, where: [thread: allows(:read)])
end

Depending on your specific needs, rulesets may allow you to organize policies in a way that is easier to maintain. In the above example, delegating to a private rules_for/2 function that returns a ruleset allows us to pattern-match on a nil user where it matters and share a ruleset where it doesn't.

This pattern has tradeoffs, however. You would need to ensure that the pattern-matching for each schema is exhaustive, for instance, otherwise a FunctionClauseError might be raised.

hooks

Hooks

Functions can be registered as hooks that run prior to authorization calls. See attach_hook/4 for more information.