LetMe - authorization DSL

Awesome Library. Looks succinct. I loved the introspection aspect and redaction of information!

I was curious about how the library will handle Role explosion and some of the scenarios mentioned below?

Say a customer comes to bar, instead of having a role depicting that they can consume alcohol, they claim that they can_drink.

We can take the claim and restrict it with policy saying, age must be drinking age, based on attribute country.

And maybe add a scope, saying that the customer can only access the drinks available on counter.

Later, bouncer might grant or revoke access on the fly!

Maybe the customer gets recognised as a VIP, so now he should have access to drinks from cellar! Perhaps they fancy a private lounge. (Instead of creating another role for people who can enter the lounge or drink special wine, they can be assigned claims like: can_enter_private_lounge)

I have a verbose way achieving the above scenarios:

P.S. I am excited about this. I won’t have to write much code. I am just trying to piece together how I can make use of the library.

The examples only use RBAC for illustration, but LetMe does not make any assumption about the kind of checks you run. If you need to make a decision based on one or multiple claims, you can just write checks for those claims. It also does not make any assumptions about the format of the subject or the object, which means you can also pass a tuple or a map with claims or anything else as a subject, and an object or multiple objects or more data relating to the object in any format you need, as long as your check functions understand them. You can also register pre-hooks to run before running the checks, e.g. to load more data necessary in multiple checks (LetMe.Policy — LetMe v3.0.1).

So in your example, assuming that there are multiple bars, the user can have different customer statuses in each bar, and you already loaded the location, drink, and customer status for the specific bar before running the permission checks, you could end up with a policy module like this:

defmodule MyApp.Policy do
    use LetMe.Policy

    object :drink do
      action :consume do
        allow storage: :counter
        allow customer_status: :vip, storage: :cellar

        # deny access to alcoholic drinks if user is below drinking age, no matter what
        deny [:drink_is_alcoholic, :below_drinking_age]

        # deny access to any banned user
        deny customer_status: :banned
      end
    end
  end

With these check functions:

  defmodule MyApp.Policy.Checks do
    def customer_status(%User{}, %{customer_statuses: statuses}, status) do
      Enum.find_value(statuses, false, &(&1.type == status))
    end

    def storage(_, %{drink: %Drink{storage: storage}}, storage), do: true
    def storage(_, %{drink: %Drink{}}, _), do: false

    def drink_is_alcoholic(_, %{drink: %Drink{alcoholic: alcoholic}}),
      do: alcoholic

    def below_drinking_age(%User{} = user, %{location: %Location{} = location}) do
      age = SomeModule.get_age(user.birthdate)
      legal_drinking_age = SomeModule.get_legal_drinking_age(location.country)
      age < legal_drinking_age
    end
  end

With this, you pass all the necessary information to the authorize function:

  user = %User{id: 10, birthdate: ~D[2002-02-05]}

  object = %{
    # storage can be :counter, :cellar, :private_lounge
    drink: %Drink{alcoholic: true, storage: :counter},
    location: %Location{id: 20, country: "uk"},
    customer_statuses: [
      # type can be :vip, :banned, :private_lounge_access
      %CustomerStatus{user_id: 10, location_id: 20, type: :vip}
    ]
  }

  Policy.authorize?(:drink_consume, user, object)

Alternatively, you could only pass the drink and the location, and preload the customer statuses with a pre-hook. Or maybe the location is preloaded in the drink struct. Whatever it is, LetMe doesn’t care about these details. It’s up to you!

In general, I would opt for parameterized rules if possible, as opposed to very specific rules (e.g. allow customer_status: :vip instead of allow :is_vip). Personally, I wouldn’t go too far with abstractions in favor of readability, but if you wanted, you could define more general check functions, e.g. one that checks for equality of a value in any nested map: allow match: {[:path, :to, :value], :value_to_check}.

This doesn’t cover every single rule you listed, but should be enough to illustrate how you can compose complex rule sets.

This looks great! I really like the idea of separating the rules from the implementation. Couple of notes:

• I’d prefer for the policy to be linked explicitly to the checks, something like use LetMe.Policy, checks: SomeModule (unless this is already the case?),
• I found this example a bit confusing:

I think it would read better as deny :banned?. Still, first it’s allow everything but then there are some “conflicting” rules. Would be great if it was obvious from the code (not the docs) how the rules are combined and what’s the behavior when no rules are specified (is it sum or intersection, allow by default or deny by default?). Maybe rename action macro to something else?

I’d prefer for the policy to be linked explicitly to the checks, something like use LetMe.Policy, checks: SomeModule (unless this is already the case?),

You can set a different check module: Check module

Would be great if it was obvious from the code (not the docs) how the rules are combined and what’s the behavior when no rules are specified (is it sum or intersection, allow by default or deny by default?).

An action is allowed if any allow rule evaluates to true and no deny rule evaluates to true. I think that’s a fairly standard way of dealing with access control rules. To make this completely explicit, you’d have to string together all rules and checks with boolean operators. But I’m pretty happy with the API as it is

Maybe rename action macro to something else?

It could have been operation, but I guess that ship has sailed.

Just released patch version 1.0.2. Nothing exciting, only documentation updates. ex_doc’s cheat sheet feature is nice, though: Rules and Checks — LetMe v3.0.1

LetMe 1.1.0 was released, which adds a metadata macro and a metadata field to the LetMe.Rule struct, which allows you to extend the functionality of the library. Thanks to Stephen for the contribution.

[1.2.0] - 2023-06-19

Added

• Added an optional opts argument to the authorize functions, so that
  additional options can be passed to pre-hooks.
• Updated LetMe.filter_rules/2 to allow filtering by meta data.

Changed

• Pre-hook options are now expected to be passed as a keyword list.

I just released LetMe 2.0.0!

What’s New?

Internal Policy Rule Representation

The internal representation of the policy rules has been changed to a tree-like expression format using AllOf, AnyOf, Check, Literal, and Not structs. An expression might look like this:

%AllOf{
  children: [
    %Check{name: :role, arg: :admin},
    %Check{name: :two_fa}
  ]
}

Or this:

%AllOf{
  children: [
    %Not{expression: %Check{name: :suspended}},
    %Check{name: :two_fa},
    %AnyOf{
      children: [
        %Check{name: :user_type, arg: :admin},
        %Check{name: :user_type, arg: :client}
      ]
    }
  ]
}

Or just:

%Literal{passed?: true}

These expressions are generated from the policy rules you define with the macro DSL. At compile time, a few basic normalization steps are applied, for example to remove unnecessary nesting or to factorize common checks in AnyOf expressions.

Lazy Evaluation

All expressions are now evaluated lazily when an authorization check is performed.

Checks With Custom Return Values

Previously, all check functions had to return a boolean. Now, the return type is boolean | :ok | :error | {:ok, term} | {:error, term}.

Detailed Authorization Errors

By default, c:LetMe.Policy.authorize/4 still returns {:error, :unauthorized} if an authorization check fails. But there is a new error option you can pass to use LetMe to set a default value and to c:LetMe.Policy.authorize/4 and c:LetMe.Policy.authorize!/4 to override the default. The available values are:

:detailed

If you set the value to :detailed, authorize/4 returns an UnauthorizedError struct with the parts of the expression that were evaluated until a decision was made. You can find the exact return value of the check function in the result field of the Check struct. The UnauthorizedErrorexception raised by authorize!/4 also contains the expression with this option value.

defmodule MyApp.Policy
  use LetMe.Policy, error: :detailed
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{
  :error,
  %LetMe.UnauthorizedError{
    expression: %LetMe.AllOf{
      children: [
        %LetMe.Check{
          name: :role,
          arg: :admin,
          result: true,
          passed?: true
        },
        %LetMe.Check{
          name: :aal2,
          result: {:error, :aal1},
          passed?: false
        }
      ],
      passed?: false
    },
    message: "unauthorized"
  }
}

:simple

If you set the value to :simple, authorize/4 returns an UnauthorizedError struct without the expression. Likewise, authorize!/4 raises an UnauthorizedError exception without it.

defmodule MyApp.Policy
  use LetMe.Policy, error: :simple
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{:error, %LetMe.UnauthorizedError{
  message: "unauthorized",
  expression: nil
}}

any

Any other value will be used directly in the error tuple:

defmodule MyApp.Policy
  use LetMe.Policy, error: :forbidden
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{:error, :forbidden}

Upgrade from v1

The policy DSL and authorization API remain unchanged. The only breaking changes are:

• The removal of the allow and deny fields of the LetMe.Rule struct in favor of the new expression field.
• The removal of the error_reason and error_message options from use LetMe.Policy in favor of the new error option.
• The removal of the allow and deny filter options on LetMe.filter_rules/2 and
  c:LetMe.Policy.list_rules/1 in favor of a single check option.

For more details, refer to the changelog.

Since the release of version 2, I extracted the expressions, evaluation, and optimization logic into a separate library called Spek. I just released version 3.0.0 of LetMe, which removes that code from the library and adds a dependency on Spek. That means that now you can reuse LetMe authorization rules in larger Spek expressions, and you can pass the expressions defined with LetMe to the Spek functions, for example to collect error reasons from the expression tree into a flat list.

The update should be straightforward. Code changes are only necessary if you used the LetMe expression structs directly. See changelog for details.