policy_wonk v0.2.1 PolicyWonk View Source
A lightweight authorization and resource loading tool for use with any Plug or Phoenix application.
Examples
In a router:
pipeline :browser_session do
plug PolicyWonk.LoadResource, :current_user
plug PolicyWonk.Enforce, :current_user
end
pipeline :admin do
plug PolicyWonk.Enforce, {:user_permission, "admin"}
end
In a controller:
plug PolicyWonk.Enforce, {:user_permission, "admin_content"}
plug PolicyWonk.EnforceAction
Authentication vs. Authorization
Authentication (Auth-N) is the process of proving that a user or other entity is who/what it claims to be. Tools such as comeonin or guardian are mostly about authentication. Any time you are checking hashes or passwords, you are doing Auth-N.
Authorization (Auth-Z) is the process of deciding what a user/entity is allowed to do after they’ve been authenticated.
Authorization ranges from simple (ensuring somebody is logged in), to very rich (make sure the user has specific permissions to see a resource or that one resource is correctly related to the other resources being manipulated).
Plugs
PolicyWonk provides three main plugs.
PolicyWonk.LoadResource
loads resources into the conn’s assigns map.PolicyWonk.Enforce
evaluates a specified policy. It either continues or halts the plug chain depending on the policy result.PolicyWonk.EnforceAction
evaluates a policy for each incoming controller action in Phoenix.
Decisions are made before controller actions are called, isolating authorization logic, encouraging policy re-use, and reducing the odds of messing Auth-Z up as you develop your controllers.
Behaviours
PolicyWonk defines two behaviours for creating policies and resource loaders.
PolicyWonk.Policy
Callbacks for a defining a policy and handling policy failures.PolicyWonk.Loader
Callbacks for defining a resource loader and handing load failures.
You should look at the PolicyWonk.Policy
documentation.
Policies outside plugs
In addition to evaluating policies in a plug chain, you will often want to test a policy when rendering ui, acting in a controller, or somewhere else.
PolicyWonk.Enforce
offers an authorized?
function just for that purpose. The documentation explains how to use it along with some handy syntactic sugar.
Configuration
There are several parameters you can set in the policy_wonk
configuration block.
config :policy_wonk, PolicyWonk,
policies: MyApp.Policies,
loaders: MyApp.Loaders,
load_async: true
Parameters
policies
Module containing your centralizedpolicy
functions. Can also be a list of modules. Default isnil
.loaders
Module containing your centralizedload_resource
functions. Can also be a list of modules. Default isnil
.load_async
Boolean value indicating that multiple resources in a singlePolicyWonk.LoadResources
invocation should be loaded asynchronously. Default isfalse
. Recommend you setfalse
for your tests,true
elsewhere.