Janus - Authorization library for applications using Ecto

Your Libraries & OS Mentoring Libraries
, ,
1

Links

Overview

Janus gives authorization superpowers to applications using Ecto.

Priorities of the library include:

  • 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.

Getting started

To try it out, you can add ex_janus as a dependency and run the policy generator to create a new policy module containing some (hopefully) useful functions using the Janus.Authorization API.

defp deps do
  [
    :ex_janus, "~> 0.2.0"
  ]
end

Generate a default policy module:

$ mix janus.gen.policy
* creating lib/my_app/policy.ex

Why (not) Janus?

Janus was created to scratch an itch: the same rules that authorize loaded data should be able to load authorized data. In concrete terms, a rule that defines whether a user can edit a resource should also be able to load all the resources that user can edit.

Loading data this way should be:

  1. efficient - loading everything and then filtering it in-memory doesn’t cut it;

  2. composable - it should be possible to add additional conditions when loading data;

  3. ergonomic - authorization should slot-in naturally without major rewrites.

Thankfully, integration with Ecto.Query solves for all of the above. One only needs authorization rules that can be translated into a query.

And thus, Janus was born.

Janus may be a good fit if…

  • you’re authorizing data backed by Ecto.Schema. Janus relies on the reflection capabilities of schemas to produce correct queries, cast values, navigate associations, etc.

  • you share interfaces between users with different permissions. Janus allows you to scope queries in a uniform way using the current user (or lack of one), making shared interfaces a natural default.

  • you prefer to have the final say. Janus takes an approach similar to Phoenix, generating code that supports certain conventions while allowing you to override or redefine behavior to fit your preferences.

  • you prefer a functional API for defining rules. Authorization policies are data; adding an authorization rule just transforms that data. Policies can be built using the full extent and natural composability of the Elixir language.

Janus may not be a good fit if…

  • you’re only authorizing actions that don’t have an obvious association to data backed by Ecto.Schema. For instance, a :send_welcome_email action without some kind of Email schema. Janus does, however, give you a natural place to define that sort of API yourself (your policy module).

  • you want an easy-to-read DSL for authorization rules. Janus policies are “just code”, so readability will depend on your own style and structure. If you value readability/scannability very highly, definitely check out LetMe, which provides a great DSL and makes some different trade-offs than Janus does.

  • you want runtime introspection for your authorization rules, like a list of all actions a user can perform. Janus does not currently provide structured access to this information, but you might again turn to LetMe, which provides introspection capabilities.

Feedback wanted!

Any feedback, positive or negative, would be sincerely appreciated!

9 Likes
2

Sounds interesting, will check it out. For now I just wanted to alert you that the links in the Documentation section of the GitHub readme are 404ing.

2 Likes
3

Had a quick look at the docs. I really like that it’s “just code” :slight_smile: Looks good, I will definitely have a use for this at some point!

4

I get 404s in the github’s documentation section for the cheatsheet and ideas behind your lib!

5

Thank you! If you find a chance to use it and have any feedback or questions, please reach out.

Will fix! I’m relying on HexDocs auto-linking, which doesn’t work on GitHub, so I need to just hard-link.

Edit: Links should be fixed on GitHub!

1 Like
6

v0.3.0 released

This release is primarily to make one notable breaking change, which is to adjust the argument order when attaching authorization rules to policies.

# Old argument order
policy
|> allow(:read, Thread, where: [...])
|> allow(:create, Thread, where: [...])
|> deny(:create, Thread, where: [...])

# New argument order
policy
|> allow(Thread, :read, where: [...])
|> allow(Thread, :create, where: [...])
|> deny(Thread, :create, where: [...])

This change was made for two reasons:

  1. To have a more consistent argument order throughout all Janus APIs, with the thing being authorized coming first, then the action, then the actor.
  2. To support a possible future allow/3 and deny/3 that takes the schema as the first argument and returns a composable “ruleset” for that schema that can be attached to a policy. This could be used optionally to organize and break up more complex policies.
policy
|> attach(rules_for(Thread, user))
|> attach(rules_for(Post, user))

defp rules_for(Thread, user) do
  Thread
  |> allow(:read, ...)
  |> allow(:create, ...)
  # ...
end

defp rules_for(Post, user) do
  Post
  |> allow(:read, ...)
  |> # ...
end
7

v0.3.1 released

This release fixes a regression that caused an incorrect validation error to occur when defining policies for schema modules whose code hadn’t yet been loaded.

It additionally introduces rulesets and simplifies the generated docs in policy modules generated with mix janus.gen.policy.

1 Like