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 integer bitstrings 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

# [:financials_read, :financials_write]
Guardian.Permissions.to_list(12, :admin)

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

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

# true
Guardian.Permissions.any?(12, [:users_read, :financial_read], :admin)

# true
Guardian.Permissions.any?(11, [:read_profile, :read_item])

# false
Guardian.Permissions.any?(11, [:delete_item, :write_item])

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,
  :access
  perms: %{ admin: [:users_read],
  default: [:read_item, :write_item] }
)

Encoding credentials with permissions

This will encode the permissions as a map with integer values

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