Guardian.Permissions

Functions for dealing with permissions sets.

Guardian provides facilities for working with many permission sets in parallel. Guardian must be configured with it’s permissions at start time.

config :guardian, Guardian,
       permissions: %{
         default: [
           :read_profile,
           :write_profile,
           :create_item,
           :read_item,
           :write_item,
           :delete_item
         ],
        admin: [
          :users_read,
          :users_write,
          :financials_read,
          :financials_write,
        ]
       }

Guardian.Permissions encodes the permissions for each as bitstrings (integers) so you have 31 permissions per group. (remember javascript is only a 32 bit system) Guardian tokens will remain small, event with a full 31 permissions in a set. You should use less sets and more permissions, rather than more sets with fewer permissions per set. Permissions that are unknown are ignored. This is to support backwards compatibility with previously issued tokens.

Example working with permissions manually

# Accessing default permissions
Guardian.Permissions.to_value([:read_profile, :write_profile]) # 3
Guardian.Permissions.to_list(3) # [:read_profile, :write_profile]

# Accessing 'admin' permissions (see config above)
Guardian.Permissions.to_value([:financials_read, :financials_write], :admin) # 12
Guardian.Permissions.to_list(12, :admin) # [:financials_read, :financials_write]

# Checking permissions
Guardian.Permissions.all?(3, [:users_read, :users_write], :admin) # true
Guardian.Permissions.all?(1, [:users_read, :users_write], :admin) # false

Guardian.Permissions.any?(12, [:users_read, :financial_read], :admin) # true
Guardian.Permissions.any?(11, [:read_profile, :read_item]) # true
Guardian.Permissions.any?(11, [:delete_item, :write_item]) # false

Reading permissions from claims

Permissions are encoded into claims under the :pem key and are a map of “type”:

claims = %{ pem: %{
  "default" => 3,
  "admin" => 1
} }


Guardian.Permissions.from_claims(claims) # 3
Guardian.Permissions.from_claims(claims, :admin) # 1

# returns [:users_read]
Guardian.Permissions.from_claims(claims) |> Guardian.Permissions.to_list

Adding permissions to claims

This will encode the permissions as a map with integer values

Guardian.Claims.permissions(existing_claims, admin: [:users_read], default: [:read_item, :write_item])

Assign all permissions (and all future ones)

max = Guardian.Permissions.max
Guardian.Claims.permissions(existing_claims, admin: max, default: max)

Signing in with permissions

This will encode the permissions as a map with integer values

Guardian.Plug.sign_in(user, :token_type, perms: %{ admin: [:users_read], default: [:read_item, :write_item] })

Minting credentials with permissions

This will encode the permissions as a map with integer values

Guardian.mint(user, :token_type, perms: %{ admin: [:users_read], default: [:read_item, :write_item] })

Summary

all?(value, expected, key \\ :default)
any?(value, expected, key \\ :default)
available()

Fetches the list of known permissions for the default type

available(type)

Fetches the list of known permissions for the given type

from_claims(claims)

Fetches the permissions from the claims. Permissions live in the :pem key and are a map of ““:

max()
to_list(thing)
to_list(list, type)
to_list(, type, list)
to_value(list)

Fetches the value as a bitstring (integer) of the list of permissions in the type list

Functions

all?(value, expected, key \\ :default)
any?(value, expected, key \\ :default)
available()

Specs:

  • available :: List

Fetches the list of known permissions for the default type

available(type)

Specs:

  • available(atom) :: List

Fetches the list of known permissions for the given type

from_claims(claims)

Specs:

  • from_claims(Map) :: Lsit

Fetches the permissions from the claims. Permissions live in the :pem key and are a map of ““:

max()
to_list(thing)
to_list(list, type)
to_list(, type, list)
to_value(list)

Specs:

  • to_value(Integer) :: Integer

Fetches the value as a bitstring (integer) of the list of permissions in the type list