[This is preliminary documentation and subject to change.]
CAZE is a finite state machine (FSM)-based authorization engine that
is driven by an application-defined
authorization policy. The authorization
policy is represented as a set of
authorization rules associated with
an application-defined business object. The authorization policy consists of
Roles,
States,
Actions,
Properties and
Authorization rules.
Roles are named sets of users sharing the same set of permissions with
respect to the application and / or the business object. For example,
"Document Authors" can create new documents (application-level permission) and
they can edit their own documents (object-level permission).
States represent the different "constitutions" defined for the type of the
business object, for example "waiting for approval". The usage of states in
the CAZE authorization policy is optional, but at least one state has to be defined.
Actions represent the set of operations defined for the business object; typically,
the set of public methods defined for the business object's class.
Properties are attributes of the business object, for example a document's title.
The use of properties in the authorization policy is optional; you'll use them only if you
want to control access to the business object's individual properties.
Authorization rules associate actions and properties with roles, states and a
boolean "enabled" flag. For example, an authorization rule might say:
"Authors can send existing documents to approval." The rule means that users in the "Author" role
are allowed to execute the "Send" action on an "existing" (state) document.
The authorization policy is brought to life by means of an
authorization context,
which is represented by an
IPrincipal object associated with the policy and
used to resolve role membership and the
current state of the policy.
The functionality of the CAZE authorization policy is encapsulated in the core
AuthorizationPolicy
class, which is the primary API you'll use in your application.
You design the authorization policy by using the Policy Designer application.
The Policy Designer stores the policy in an authorization policy file
(a XML file with a
.caze extension). You can also
populate an authorization policy in code by using the CAZE API. Nevertheless,
in most cases you'll
want to use the Policy Designer, because it's
more comfortable and allows you to also test the policy before deployment.
After designing and testing an authorization policy you'll need to integrate
it with your application's logic. First you'll need to populate an instance of the
AuthorizationPolicy
class by using the
AuthorizationPolicyLoader
class to load the previously designed authorization policy from disk,
application resource or a database.
Next you'll initialize the authorization context by setting the
CurrentPrincipal
and the
CurrentState
properties.
Finally, you'll execute access checks, enumerate available actions and properties
and execute actions by calling the various
AuthorizationPolicy
methods (
ExecuteAction,
IsActionExecutable,
IsPropertyChangeable
...etc).
Setting up a project for CAZE
Before using the CAZE API in your project, you'll have to add references to
the following CAZE assemblies:
LaMarvin.Common.dll
exposes types supporting the implementation the
LaMarvin.Constable.dll assembly.
LaMarvin.Constable.dll
exposes the core
AuthorizationPolicy
class and supporting types.
The CAZE API contains three namespaces; we'd recommend to import them in your application's
source files where you'll be using CAZE functionality:
[Visual Basic]
Imports LaMarvin.Constable
Imports LaMarvin.Constable.Model
Imports LaMarvin.Constable.Principal
[C#]
using LaMarvin.Constable;
using LaMarvin.Constable.Model;
using LaMarvin.Constable.Principal;