View Source Janus (Janus v0.2.1)
Authorization superpowers for applications using Ecto
.
Priorities:
Single source of truth - The same rules that authorize loaded data should be able to load authorized data.
Authentication-agnostic - Janus should not care about how users are modeled or authenticated.
Minimal library footprint - Expose a small but flexible API that can be used to create an optimal authorization interface for each application.
Escape hatches where necessary - Complex authorization rules and use-cases should be representable when Janus neglects to provide a short cut.
Janus is split into two primary components:
Janus.Policy
- functions and behaviour for defining policy modules, which describe the allowed actors, actions, and resources in your application. This is where you look if you're writing a policy module.Janus.Authorization
- functions and behaviour used by the rest of your application to authorize and load resources. This is where you look if you're using a policy module.
Janus defines a Mix task to generate the basic policy module that will get you started:
$ mix janus.gen.policy
policies
Policies
Policy modules are created by invoking use Janus
, which implements
both the Janus.Policy
and Janus.Authorization
behaviours:
defmodule Policy do
use Janus
@impl true
def build_policy(policy, _user) do
policy
end
end
When you invoke use Janus
, default implementations are injected for
required callbacks, except for Janus.Policy.build_policy/2
. This
callback is your foundation, as it returns the authorization policy
for an individual user of your application.
The policy above is not very useful (it doesn't allow anyone to do
anything) but that can be changed by using the Janus.Policy
API to
define actions, resources, and conditions that make up your
authorization rules.
def build_policy(policy, %User{role: :moderator} = mod) do
policy
|> allow(:read, Post)
|> allow([:edit, :archive, :unarchive], Post, where: [user: [role: :member]])
|> allow([:edit, :archive, :unarchive], Post, where: [user_id: mod.id])
|> deny(:unarchive, Post, where: [archived_by: [role: :admin]])
end
See the Janus.Policy
documentation for more on defining policies.
authorization
Authorization
With our policy module defined, it can now be used to load and authorize resources.
iex> Policy.authorize(some_post, :archive, moderator)
{:ok, some_post}
iex> Policy.authorize(post_archived_by_admin, :unarchive, moderator)
{:error, :not_authorized}
iex> Policy.scope(Post, :read, moderator)
%Ecto.Query{}
iex> Policy.scope(Post, :read, moderator) |> Repo.all()
[ ... posts the moderator can read ]
iex> Policy.any_authorized?(Post, :edit, moderator)
true # there are rules allowing moderators to edit posts
iex> Policy.any_authorized?(Post, :delete, moderator)
false # there are no rules that allow moderators to delete posts
These functions make up the Janus.Authorization
behaviour, and their
definitions were injected by default when we invoked use Janus
. This
is the "public API" that the rest of your application will use to
authorize resources.
See the Janus.Authorization
documentation for more.
integration-with-ecto-query
Integration with Ecto.Query
The primary assumption that Janus makes is that your resources are
backed by an Ecto.Schema
. Using Ecto's schema reflection
capabilities, Janus is able to use the same policy to authorize a
single resource and to construct a composable Ecto query that is aware
of field types and associations.
# This query would result in the 5 latest posts that the current
# user is authorized to see, preloaded with the user # who made
# the post (but only if the current user is allowed to see that
# user).
Post
|> Policy.scope(:read, current_user,
preload_authorized: :user
)
|> order_by(desc: :inserted_at)
|> limit(5)
This integration with Ecto queries is main reason Janus exists.
configuration
Configuration
Some defaults can be configured by passing them as options when
invoking use Janus
. Those are:
:repo
-Ecto.Repo
used to load associations when required by your authorization rules:load_associations
- Load associations when required by your authorization rules (requires:repo
config option to be set or to be passed explicitly at the call site), defaults tofalse
For example:
defmodule MyApp.Policy do
use Janus,
repo: MyApp.Repo,
load_associations: true
# ...
end
These defaults will be referenced in the Janus.Authorization
documentation where they are used.
Link to this section Summary
Functions
Sets up a module to implement the Janus.Policy
and
Janus.Authorization
behaviours.
Link to this section Types
Link to this section Functions
Sets up a module to implement the Janus.Policy
and
Janus.Authorization
behaviours.
Using use Janus
does the following:
adds the
Janus.Policy
behaviour, imports functions used to define the required callbackJanus.Policy.build_policy/2
, and defines abuild_policy/1
helperadds the
Janus.Authorization
behaviour and injects default (overridable) implementations for all callbacks
options
Options
:load_associations
- Load associations when required by your authorization rules (requires:repo
config option to be set or to be passed explicitly at the call site), defaults tofalse
:repo
-Ecto.Repo
used to load associations when required by your authorization rules
See "Configuration" section for details.
example
Example
defmodule MyApp.Policy do
use Janus, repo: MyApp.Repo
@impl true
def build_policy(policy, _actor) do
policy
# |> allow(...)
end
end