terminator - Granular elixir ACL/permissions library suggestions/thoughts

[MilosMosovsky]

Hello everyone! None of the provided authorization libraries worked for me in a way that I needed (I need granular permissions per Role, User, Entity) therefore I created small library for ACL permissions.

Initially I was doing the code inside my project but then I created library from it. I would love to hear any suggestions/thoughts about that. Initially I went with existing libraries like authorize or canary but as I need many actions to be performed I ended up with ~20 custom can? methods just for 1 schema and it was almost impossible to build admin panel for it to manage those permissions.

https://github.com/MilosMosovsky/terminator
https://hex.pm/packages/terminator

What terminator includes?

Database based permission system

When you are building large app with many actions and each action needs to have different permissions + you need some admin panel to manage those permissions existing libraries are just not enough.

Role based permissions

With existing libraries it was really hard to introduce 5 custom roles with different permissions (e.g. admin can done everything, editor can edit post description, super_editor can delete posts, writer can write new posts and registered user can view them. Terminator allows me to create as much roles as I need with assigned permissions to them

Compatibility with ecto projects

I already had existing project without any permissions therefore it was crucial to have something which I can plug-in with several lines without modyfing existing code. Performer which is main actor in terminator can be plugged to any existing schema (I have it plugged to Account schema)

Easy to read DSL

When I tried to create permission with existing libraries after a while I felt like a compiler in my head. You have to read extensively through multiple can? implementations and pattern match them in head to see easily which permission you are modifying. I created easily readable DSL:

permissions do
  has_ability(:delete)
  has_role(:admin)
end

as_authorized do
  "I can safely proceed"
end

Full code coverage

As I understand how ACL is crucial for app I am maintaining 100% code coverage and keep library “over-tested”

Future ideas

• I am using ueberauth, absinthe in my app, I want to do easy plugs to load performer from plugs (session) or absinthe context.

• Currently I have WIP version for field based authorization in GraphQL (e.g. you have user shape but only admins and owner of an account can query email field, you can solve it with multiple shaped queries but I created middleware on the top of terminator which protects resulting shape and returns nil on particular field) this allows you to have only 1 query
  query { account { id, email } } and terminator protects email field in resolver.

As I am originally react developer I realize that code is probably not perfect but I would love to hear any suggestions/ideas and try-outs! Thank you!

[Eiji]

I have some found problems/questions related to your READM.md file …

#1 Missing do keyword at line 1:
defmodule Sample.Post → defmodule Sample.Post do

#2 Wrong module call at line 20:
Sample.Repo.get(Sample.Post, id) |> Sample.repo.delete() → Sample.Repo.get(Sample.Post, id) |> Sample.Repo.delete()

#3 Wrong module call at line 26:
:ok -> Sample.Repo.get(Sample.Post, id) |> Sample.repo.delete() > :ok -> Sample.Repo.get(Sample.Post, id) |> Sample.Repo.delete()

#4 Firstly you give example:

    permissions do
      has_role(:admin) # or
      has_role(:editor) # or
      has_ability(:delete_posts) # or
    end

and then you give this one:

    permissions do
      calculated(:confirmed_email)
      calculated(:is_owner, [post])
    end

so it will succeed when owner of specified Post does not had confirmed email, right? It does not looks like a perfect example here

#5 Another problem is in this example:

defmodule Sample.Post do
  def create() do
    user = Sample.Repo.get(Sample.User, 1)
    post = %Post{owner_id: 1}
    load_and_authorize_performer(user)

    permissions do
      has_role(:editor)
    end

    as_authorized do
      case is_owner(performer, post) do
        :ok -> ...
        {:error, message} -> ...
      end
    end
  end

  def is_owner(performer, post) do
    load_and_authorize_performer(performer)

    permissions do
      calculated(fn p, [post] ->
        p.id == post.owner_id
      end)
    end

    is_authorized?
  end
end

Here performer in case statement is completely magic. Newbies would not get how it’s actually working.

#6 Also as_authorized do … case … end looks too complicated comparing to or examples.

Personally I would suggest some compile time scenarios like:

defmodule Example.MyModel do
  def_scenario :scenario_id do
    abilities([…])
    roles([…])
  end

  def_scenario :another_scenario_id do
    any_of(abilities: […], roles: […], scenarios: […]) # and
    all(abilities: […], roles: […], scenarios: […])
  end
end

and use it in with like:

defmodule Example do
  def sample(post_id, user_id) do
    with user <- Sample.Repo.get(Sample.User, 1),
      performer <- load_and_authorize_performer(user),
      :ok <- validate_scenario(performer, :scenario_name), # and
      :ok <- validate_role(performer, :role_name), # and
      :ok <- validate_ability(performer, :ability_name) do
      # here goes contents of `:ok` case result
    end
  end
end

What to do when you have performer User which is in Company in many to many relation? When you have function like def is_owner(performer, post) do … end there is no way to read company or company_id.

#7 Session plug to get current_user

Again, what if you have authorization based on multiple models?

#8 Will you provide any way to solve dynamic ecto queries?
Let’s say that somehow you have received not trusted generated ecto query which you want to validate, but you do not want to fetch millions of records. Instead you want to validate it properly on database level. Maybe there should be something like:

defmodule Example.MyModel do
  def_auth_check(user_id) do
    ensure_join(…, args: [user_id]) # join args here
    # continue ensure_join(…) in other models until reaching final model
  end
end

defmodule Example.MyFinalModel do
  def_auth_check(user_id) do
    ensure_join(…, as: :joined_name, …, on: [id: ^user_id]) # join args here
  end
end

defmodule Example.MyAuthModel do
  def_auth_check do
    check_ability(:read)
    # this would filter everything which in any depth joins this model
  end
end
# this is of course example written in "5 min"

In short I believe that there could be such changes:

1. More compile-time data - limit run-time for calculated functions which would be called manually anyway.
2. Think about some way to validate ecto queries without fetching records (as a second way - of course doing it for delete as you show is also good, but think about typical get and list REST API)
3. Consider remove some “magic” in order to have library which could be faster to understand for everyone
4. Consider making API more easy for and checks - not only for or cases

Let me know what do you think about it.

[MilosMosovsky]

Awesome feedback! Yes your points are valid, I was also thinking about AND rules, either to introduce some terminating words or signatures like :next or :stop but your any_of and all is looking good. It’s good example as you can have defined more scenarios and validate only those which are needed inside function. I love it actually.

I will fix README.md

#7 I didn’t get the question “authorization” based on multiple models" do you mean that you have for example User → Company but both user and company are performers ?

#8 Understood makes sense, but for now I didn’t run to such case, but nice thing to put in roadmap

Again really thank you for your feedback, sometimes is really hard when you work on something too long, everything seems “obvious”, now I see where it is missing more clarity. Thank you! I will definitely implement something like scenarios. I like it.

[Eiji]

@MilosMosovsky

#7 I didn’t get the question “authorization” based on multiple models" do you mean that you have for example User -> Company but both user and company are performers ?

I had even more complicated scenario

Of course I can’t share project details, but some general info about use case should be ok.

Imagine that you have typical User model. Every User could create or join Company. When it joins Company it can access, add and modify some data based on many-to-many relation between User<->Company and its enum field called role (of course you are going to replace such field with your solution), so what we need to properly determine scenario is:

1. Create Plug(s) for handling User and Company tokens (under different request headers).
2. When User is not nil and Company is not nil we firstly need to check if there is unique relation between specific User and Company
3. If such relation exists use scenario based on its role field (for example editor) and use company_#{role} scenario (for example company_editor).
4. If such relation does not exists return 400 error (bad request) if Company token was passed
5. If no Company token is passed use basic_user scenario or return 400 error if User token was incorrect
6. If no token is passed use guest_user scenario

I would like to see your example solution for that use case.

[MilosMosovsky]

Got it, to simplify solution, let’s eject token handling out of the scope of solution and let’s assume that we have some function which needs to be authorized and we will pass user/company as arguments

• 1. I would add new performer to user field same as I did in my readme
• 2. I Would create new ability, let’s say :edit_company for example
• 3. I would create new role for basic users :basic_user
• 4. I would put Terminator.Performer.grant(user, role) to ecto changeset on user creation
• 3. I would put new grant/hook when User will join Company so I would do

  iex> user = %User{}
  iex> ability = %Ability{identifier: “edit_company”}
  iex> company = %Company{}
  iex> Terminator.Performer.grant(user, ability, company)

Now this particular user has ability to edit this particular company once he join it. Also this user has :user role as we inserted related record when he registered. Now let’s illustrate protected action:

defmodule Sample do
   use Terminator

   edit(user, company) do
      if has_role?(user, :basic_user) do
         if has_ability?(user, :edit_company, company) do
           perform(:company_user)
         else
           perform(:basic_user)
         end
      else
         perform(:guest)
      end
   end
  
   def perform(:basic_user), do: ...
   def perform(:company_user), do: ...
   def perform(:guest), do: ....
end

If you can assure calling grant method on user creation / company creation / company join. Example should work. What do you think? But I think introducing :scenarios as you posted in first post will make it much cleaner

[Eiji]

@MilosMosovsky

Got it, to simplify solution, let’s eject token handling out of the scope of solution and let’s assume that we have some function which needs to be authorized and we will pass user/company as arguments

Your solution looks ok, but personally I would do it a bit differently.

Assuming that we are after token validation then everything is even more simplified.

defmodule Example do
  # look that plug should already create full context here
  # so there is no need for checking guest and basic_user
  # such cases should be rejected in Absinthe.Middleware
  # or any other equivalent way of validating routing based on tokens

  def sample(%{company_user: company_user}, type, model, data) do
    model_name = Example.Helper.model_name(model)
    if has_role?(company_user, :"#{type}_#{model_name}") do
      apply(model, type, [data])
    else
      # return 403
    end
  end

  def sample(_context, _type, _model, _model_name, _data), do: # return 400
end

Example.sample(%{…}, :edit, Example.Company, %{name: "Example"})

Look that if we already have CompanyUser then storing reference to User and Company separately is bad idea. Assuming that we want to delete Company then we are going to remove all its members anyway. When we are going to delete account then we need to delete reference to Company as well. So instead of 2 checks (i.e. Company delete and User delete) we can have just one (CompanyUser delete) since it’s required to remove associated database rows before remove target row.

In case when CompanyUser (many to many) relation is not needed (i.e. no other data than company_id, user_id and acl is stored) then we do not need CompanyUser and your solution is better in such case. If you agree with me then I believe that those 2 examples (with and without CompanyUser) should be mentioned somewhere as an usage in bigger projects.

[OvermindDL1]

For note, ueberauth integration is not needed at all. ueberauth is an authentication library, not an authorization, and thus its purview ends where terminators begins.

Overall, a lot to take in here. I wouldn’t really use roles as I do detailed testing on everything, so perhaps an example. Right now I do a lot of checks like this:

    conn
    |> can(%Permissions.AH.Requirement{action: :edit, tag: ah_tag, id: id, pidm: pidm})
    ~> case do conn ->
      # Do stuff...

      records =
        Something.get_records(...)
        |> Enum.filter(&can?(conn, %Permissions.AH.Requirement{action: :edit, tag: ah_tag, id: id, pidm: pidm, record: &1.name}))

      # Do more stuff...
    end

Where can/2 takes an environment (whether a conn, channel socket, token, etc…) and an ‘ability’ structure (to use a terminator term, just called a ‘permission’ here) and it returns either the environment back out (possible modified with cache data if allowed, but in general I use Cachex a lot instead) or it returns an exception structure (which is what the ~> is handling via the exceptional library, but that can be easily tested anyway), or I can use can?/2, which is the same but returns true/false.

In the admin interface all permission structures are listed in every account that can be added/removed/modified on a key-by-key basis. When an environment is looked up it’s permission data for the specific account is looked up in the database as well as the permissions for the groups and then they are merged in a way that works for my permissions_ex library (everything is either Allow/NotAllowed/Deny where not defined means NotAllowed and Allow overrides NotAllowed to allow but Deny overrides all others to always Deny regardless of all other settings).

But the above example tests if the current user has access to the AH Requirement of the proper tag, ID and for the PIDM record then filters the specific record names that the user has access to before proceeding. I use lots and lots of these checks everywhere and can is very well optimized for lots of use (a cache, database sends an event when permissions updated, etc… etc…). How would this pattern be done in terminator? I’m having an interesting time understanding the README.md, like is load_and_authorize_performer a magic function that does something, what do the permissions and as_authorized blocks actually do, how does it handle permission failure (like in my system an exception causes the system to redirect to the login page along with a message saying what permission they failed and to log in to an account that has such a permission for example), etc…? The ‘abilities’ in my system are hard-coded (it makes no sense to make them dynamic as the functionality everywhere only uses what it knows anyway, thus they are structs that the system can gather a list of via behaviour implementations).

[MilosMosovsky]

@OvermindDL1 Thanks for taking a look!

1. Regarding ueberauth, in fact ueberauth returns %Uebear.Auth struct with UID (which is unique external ID for example of google/twitter account) This can be used directly as performer so you even don’t need to create Users table in app, so that was my IDEA of integrating ueberauth is not like integration bot more like compatibility .

Your solution looks very similar to mine (in fact I think there are living many solutions like mine/yours nowadays) as it’s like normal scenario in any app.

2. Regarding load_and_authorize_performer , many people are coming from rails, even canada/canary library took rails as example GitHub - ryanb/cancan: Authorization Gem for Ruby on Rails. · GitHub which is very common gem to be used as can? library in rails. It has similar load_and_authorize_resource method as AR models are OOP you always have instance of model bound to DB record so load_and_authorize_resource just load it from database and do the authorization. I took this example for load_and_authorize_performer which setup something like new “auth” session in context of Terminator and this performer is used for any subsequent calls of abilities. That means inside permissions macro, each call is checked against entity loaded with load_and_authorize_performer so instead of writing ability(performer, :view) you can write just ability(:view) and performer is fetched from “current session”

3. Regarding roles, they are not needed for terminator at all, they can be omitted and it would look almost same as your snippet It’s just sugar on top if you want to assign for example 30 abilities to different user you can just group them to Role. If you want to reject 1 ability from all those users you revoke it from role and you don’t have to update all users in database

4. as_authorized is just macro for is_authorized? which wraps passed block. There is no difference between is_authorized? and as_authorized macro.

5. Regarding dynamic abilities, it really depends on use case. If you have small codebase and 1000 users it’s easy to handle everything in structs. If you have 100 000 users and you need to assign 200 users to view particular entity, fun is just starting.

If I would have application with relatively small amount of “users” and small amount of permissions Terminator looks like an overkill. But for example if you have some enterprise app where companies can sign up, and you have like 100 000 companies, and 500 staff members as “Sales” reps, and you need to assign some sales people to operate with that company, it’s hard to prepare good architecture only with structs. Not saying it’s impossible but when 200 developers are working on same codebase it’s usually really magical to find correct place.

I didn’t roll out Terminator on large codebase yet so I can’t say how optimized it is and how it would perform if single page load would call let’s say 30 times is_authorized?, probably after that I will come to a decision to drop Terminator :D. My goal to achieve is call load_and_authorize_performer once on every request which will prepare all abilities with 1 DB load and all subsequent calls to authorization will be done against cache.

[MilosMosovsky]

Oh, and btw @OvermindDL1 I have been looking to GitHub - OvermindDL1/permission_ex · GitHub and probably I will try to build terminator on the top of that As my primary goal wasn’t to test permissions (as you did in your lib very nicely) but have dynamic management system around it in database and way how to very easily “prepare” arguments for something like your test_permission function. When I prepare everything from database I have my own test_permission function which I think I will just call from your library.

[OvermindDL1]

@MilosMosovsky

Regarding ueberauth, in fact ueberauth returns %Uebear.Auth struct with UID (which is unique external ID for example of google/twitter account) This can be used directly as performer so you even don’t need to create Users table in app, so that was my IDEA of integrating ueberauth is not like integration bot more like compatibility .

That would only be for the specific account that was auth’d. The user should always convert that to some local ID that multiple sources all reify into, otherwise you get a set of disparate accounts.

@MilosMosovsky

It has similar load_and_authorize_resource method as AR models are OOP you always have instance of model bound to DB record so load_and_authorize_resource just load it from database and do the authorization. I took this example for load_and_authorize_performer which setup something like new “auth” session in context of Terminator and this performer is used for any subsequent calls of abilities. That means inside permissions macro, each call is checked against entity loaded with load_and_authorize_performer so instead of writing ability(performer, :view) you can write just ability(:view) and performer is fetched from “current session”

Does that mean it hits the database on every request?

Where does it cache the information for the authorize calls? Hmm, looks like it uses an ETS table. I’m not seeing where it gets cleared out, will this table infinitely fill up to the unique ID count (I have a few tens of thousands of accounts in my system of which most are not logged in at a time except occasional times where ‘most’ of them log in within a short time period). Is it never purged over time?

@MilosMosovsky

Regarding roles, they are not needed for terminator at all, they can be omitted and it would look almost same as your snippet It’s just sugar on top if you want to assign for example 30 abilities to different user you can just group them to Role. If you want to reject 1 ability from all those users you revoke it from role and you don’t have to update all users in database

I go a different route where instead of ‘abilities’ like edit+ah+record+pidm+etc I combine those into a singular record. This means that I have full knowledge of every possible combination at compile-time for the admin view (and others) generation. Thus I generally only test a singular ‘ability’/permission at a time. I guess mine kind of combine your ability/role into a singular well-typed unit.

@MilosMosovsky

as_authorized is just macro for is_authorized? which wraps passed block. There is no difference between is_authorized? and as_authorized macro.

Hmm, it looks like every authorization check hits ETS quite a number of times, how well is that handled with filtering out records that a user should not be able to see, it seems like it would cause a bit of a slowdown?

@MilosMosovsky

Regarding dynamic abilities, it really depends on use case. If you have small codebase and 1000 users it’s easy to handle everything in structs. If you have 100 000 users and you need to assign 200 users to view particular entity, fun is just starting.

That’s what my groups are for, there is a many<->many account<->group binding in the database, and both accounts and groups have permission set, which get aggregated together appropriately (in the database layer actually).

I have a few tens of thousands of account (actually I can check, hold on… 18054, there should be about 30k but that means a lot of people aren’t logging in that should be logging in as the accounts are created on first access ^.^), with a few dozen permissions (each permission covers a HUGE range of access capabilities as they are configurable).

My specific use-case is a college if you are curious, I write the backend system.

@MilosMosovsky

Oh, and btw @OvermindDL1 I have been looking to GitHub - OvermindDL1/permission_ex · GitHub and probably I will try to build terminator on the top of that

Eh, it’s a very tiny library, I just wanted something rock solid with a minimal feature set that I needed. You could certainly do something better for something more specific to the user-case. That is the library that my permission matching is built on though.

I never released my overarching system that uses it though because I’m not happy with it, not the design or use, but I just can’t seem to come up with something better. It’s efficient enough that my server is the fastest of all that we have so I haven’t worried too much about that even during heavy load times, and the configurable permission structures have covered every case I’ve needed so far (and a great deal more), so I haven’t felt the need to try to iterate further on it.

For note, I’m poking at this because I’d really really want to see it replace my system. The less I have to manage and keep up to date myself, the better. I’ve also been very unhappy at all the other authorization frameworks I’ve seen in Elixir as well (this is something java does really well…).

EDIT: Oh, and another note, mine also pulls permission data from other servers as well, not just the database, but also a LDAP and CAS systems so any replacement I use needs to be able to have pluggable ‘stores’.

[MilosMosovsky]

1. Yes it hits DB all the time.

2. ETS table is very small as it is cleared on each load_and_authorize_performer and permissions macro. But I imaginage to have some cache there and sweeper which will truncate the cache after some time.

3. Yeah I see that you can achieve the SAME with permissions_ex lib + some database layer, and that’s the point of Terminator. To take this responsibility from devs who just don’t care and want have simple API interface around permissions.

So final notes are probably like this: You can achieve same with can? or without can? + permission_ex + DB. But there is no complex solution which does it. Something which will prepare everything together as 1 to go solution. There are nice libs as canary/canada/permission_ex which does this checking very nicely BUT ONLY WHEN you know what to pass there (those tags, groups, ids, entities). So my goal is to extract this part to simple has_ability?(user, :ability) and grant(user, :ability) which will do everything else under the cover. I hope I made my goal more clear now So my idea is not to focus on perfect solution which will do permission check as probably you can go with existing libraries. But perfect solution which will PREPARE and translate those arguments to appropriate calls and returns 1 aggregated boolean.

[OvermindDL1]

@MilosMosovsky

ETS table is very small as it is cleared on each load_and_authorize_performer and permissions macro. But I imaginage to have some cache there and sweeper which will truncate the cache after some time.

Uh, cleared on each? What if you have two concurrent requests coming in? Doesn’t that mean that one could potentially get the others permissions or get no permissions or some combination thereof?

[bjunc]

I created a library a little while back called Access Decision Manager. I think it might do what you’re looking for. It’s based on logic by the same name in PHP’s Symfony framework. Quick examples:

granted?(viewer, "CREATE_FOO", some_entity) # true / false

This uses a “voter” system that allows for per-entity permissions. You can also use it for simpler scenarios like this:

granted?(viewer, "ROLE_SUPER_ADMIN")

This is where the “subject” and “entity” are the same (eg. you want to know if the viewer has the super admin role).

We’re currently using this in production, in both Guardian plugs, as well as Absinthe resolvers. Slightly paired back resolver example:

def update(%{input: %{id: floor_plan_id}}, %{context: %{viewer: viewer}}) do
    case FloorPlan.get(floor_plan_id) do  
      %FloorPlan{} = floor_plan ->
        if granted?(viewer, "EDIT_FLOOR_PLAN", floor_plan.project) do
          # ... update floor plan

        else
          {:error, message: "Permission denied.", code: 403}
        end

      nil ->
        {:error, message: "Floor Plan doesn't exist.", code: 404}
    end
  end