Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Permission engine

kristianmandrup edited this page · 11 revisions

The Permission Engine is the engine that handles everything relating to Permissions. The Permission engine is responsible for the following tasks

  • Load

    • Load rules from the store
    • Parse rules
    • Compile rules
    • Evaluate compiled rules as Permits
    • return rule set
  • Save (optional)

    • Save rules to the store

Permissions is the term we have given permits that are static in nature and persisted and later loaded from a store.

Permissions are static by nature, so when you need truly dynamic rules, you should use the Permit engine and define Permits (as Ruby classes). Due to their static nature and limited expressive power, permissions are limited in what they can do and data they can access as part of the rule evaluation.

The following types of Permissions are prepackaged with the CanTango Permission engine:

  • roles
  • role groups
  • licenses
  • users
  • user types
  • account types

1.0 release

If you create and register your own Permits you will be able to define permissions for those Permits. We also plan to rename the engines as part of a major refactoring. The permission engine will be renamed as the permit store engine.

Configuration

The CanTango permission engine can be configured and examined as demonstrated here:

CanTango.config.engine(:permission) do |engine|
  puts engine.modes
  engine.mode = :cache
  engine.set :on
  engine.reset! # state to default value
  puts "ON" if engine.on?
  puts "OFF" if engine.off?

  # permission engine specific
  puts engine.types # permission types available

  # permission file location
  engine.config_path 'my/special/permissions/location'
  engine.config_path = 'my/special/permissions/location'
  puts engine.config_path
end

Permission store

A Permission store can be any kind of key-value store, including a YAML file.

We recommend you start by using the Yaml permission store that comes with CanTango and is the easiest to use and with currently the most feature support.

A Permission store should be able to store all these sets of rules, each in their own subset. Note that permissions can reference Categories which are maintained in a special categories yaml file or registered directly with cantango.

Here an example of ways to configure the Permission store, using the store config API:

CanTango.config.engine(:permission) do |engine|
  engine.store do |store|
    store.options = {:port => 3000}
    store.default_type = :redis
    store.default_class = MyCustomPermissionStore
    store.factory Proc.new { MyCustomPermissionStore.new }
  end

Yaml Permissions store

The Yaml store is a Permission store which stores Permissions in a simple Yaml file. By default, CanTango assumes the location is in you Rails app config folder and that the file name is permissions.yml.

You can optionally configure an alternative permissions file location:

CanTango.config.engine(:permission).config_path

In the future, this config option might be moved to the store config API, a more natural location!

The Yaml permission file must use the following kind of structure:

account_types:
  guest:
    can:
      manage:
      - all
user_types:
  admin:
    can:
      manage:
      - all
roles:
  user:
    can:
      read:
      - ^articles
      - /Post/
      write:
      - Comment
    cannot:
      write:
      - Article
role_groups:
  bloggers:
    can:
      read:
      - /Article$/
      - /^Comment/
    cannot:
      write:
      - Article
      - Post
  editors:
    can:
      read:
      - Article
      - Comment
    cannot:
      write:
      - Article
      - Post
licenses:
  editors:
    can:
      manage:
      - all
users:
  stan@theman.com:
    can:
      manage:
      - all
  kris@thewiz.dk:
    cannot:
      read:
        - /.*Book/

Note the special ^ symbol, such as ^articles for the user role at the top. This is used to reference a Category (set of models) stored in the Categories yaml file.

The regular expressions marked between /, allows you to say fx that a rule should apply for any model relating to a concept, fx a Book, not just the Book class itself.

In a regular expression the $ sign is used to indicate the end of the string and the ^, the beginning of the string.

This can be used to fx say any model starting with Book:

/^Book/ would match BookGuide

or any model ending with Book:

/Book$/ would match GuideBook

Something went wrong with that request. Please try again.