security.doxy

/*!
\page security Security
<div class="has-toc"></div>

# Security # {#sec_main}

Two key aspects of securing an application are _authentication_ and _authorization_.
While __authentication__ is the process of verifying the identity of a user,
__authorization__ means determining if the user is allowed to do what he or she
is about to do. That implies that authentication is a precondition for
authorization. Input __validation and filtering__ is another aspect, which is
especially important in web applications.

## Users and Roles ## {#sec_users_roles}

Users are essential for an authentication system. In wCMF users are represented
as instances of classes implementing the
\link wcmf::lib::security::principal::User `User`\endlink interface. Since wCMF's
authorization system is role based, users are organized in roles. Role classes
implement the \link wcmf::lib::security::principal::Role `Role`\endlink interface.
A user could have multiple roles, while multiple users could have the
same role.

The concrete implementations of these interfaces are configured in
\link wcmf::lib::security::principal::PrincipalFactory `PrincipalFactory`\endlink.

## Authentication ## {#sec_authentication}

In wCMF authentication is handled by implementations of
\link wcmf::lib::security::AuthenticationManager `AuthenticationManager`\endlink.

By default
\link wcmf::lib::security::impl::DefaultAuthenticationManager `DefaultAuthenticationManager`\endlink
is used. It implements a __login/password__ based authentication procedure by
matching the given user credentials against existing
\link wcmf::lib::security::principal::User `User`\endlink instances. These instances
are provided by implementations of
\link wcmf::lib::security::principal::PrincipalFactory `PrincipalFactory`\endlink.

The following code demonstrates the authentication process as implemented
in \link wcmf::application::controller::LoginController `LoginController`\endlink:

~~~~~~~~~~~~~{.php}
// get the user credentials from the request
$login = $request->getValue('user');
$password = $request->getValue('password');

try {
  // try to login using the credentials
  $authUser = $this->_authenticationManager->login($login, $password);
}
catch (Exception $ex) {
  Log::error("Could not log in: ".$ex, __CLASS__);
}

// set the authenticated user in the session
if ($authUser) {
  // login succeeded
  $session->setAuthUser($authUser);
}
~~~~~~~~~~~~~

@note The user, that is associated with the current session - the _current user_ -
is obtained using the
\link wcmf::lib::core::Session::getAuthUser `Session::getAuthUser`\endlink
method. Before successful authentication, this user is an instance of
\link wcmf::lib::security::principal::impl::AnonymousUser `AnonymousUser`\endlink.
It will be replaced by an instance of the application's
\link wcmf::lib::security::principal::User `User`\endlink type after successful
authentication.

The configuration of the authentication process in the \ref app "default application"
looks like the following:

~~~~~~~~~~~~~{.ini}
[AuthenticationManager]
__class = wcmf\lib\security\impl\DefaultAuthenticationManager
principalFactory = $principalFactory

[PrincipalFactory]
__class = wcmf\lib\security\principal\impl\DefaultPrincipalFactory
userType = app.src.model.wcmf.User
roleType = app.src.model.wcmf.Role
~~~~~~~~~~~~~

Since
\link wcmf::lib::security::principal::impl::DefaultPrincipalFactory `DefaultPrincipalFactory`\endlink
retrieves user instances from the storage, it needs to configured with the
appropriate entity types. If required, the default user type may be replaced
by custom implementations of \link wcmf::lib::security::principal::User `User`\endlink.

## Authorization ## {#sec_authorization}

The purpose of authorization is controlling access to application resources,
which could be controllers or entity instances. To establish __access control__,
rules have to be defined in the first place and enforced afterwards.

### Permissions ### {#sec_perm}

Access control rules are expressed as _permissions_. Permissions are either
granted or denied to a role (see \ref sec_users_roles).

A permission definition in wCMF consists of two parts:

- The __permission subject__ is a combination of a _resource_, a _context_ and an
  _action_ and the notation is the same as for action keys (see \ref arch_actionkey),
  except that the _controller_ value is an arbitrary resource.
- The __involved roles__ are listed space-separated and each one is prepended with
  a _modifier_ (<em>+</em> for granting and <em>-</em> for denying).

The following code illustrates the __format__:

~~~~~~~~~~~~~{.ini}
resource?context?action = +allowedRole -deniedRole ...
~~~~~~~~~~~~~

#### Implicit denial ####

Roles that are not listed in the permission are denied per default. The wildcard
character (<em>*</em>) is used to define the permission for all roles that are
not explicitly listed.

The following code grants the permission only to _allowedRole_

~~~~~~~~~~~~~{.ini}
resource?context?action = +allowedRole -*
~~~~~~~~~~~~~

and is equivalent to

~~~~~~~~~~~~~{.ini}
resource?context?action = +allowedRole
~~~~~~~~~~~~~

#### Built-in resources ####

The resource value could be set to any string to implement custom application
specific permissions.

Besides this, wCMF uses the following built-in resources:

- _Controller_ to restrict access on execution of a controller
  (e.g. `wcmf\application\controller\SaveController`)
- _Entity type_ to restrict access on all instances of an entity type
  (e.g. `app.src.model.wcmf.User`)
- _Entity property_ to restrict access on a certain property of an entity type
  (e.g. `app.src.model.wcmf.User.login`)
- _Entity instance_ to restrict access on one entity instance
  (e.g. `app.src.model.wcmf.User:123`)
- _Entity instance propery_ to restrict access on a certain property of one
  entity instance (e.g. `app.src.model.wcmf.User:123.login`)

The actions for the persistency related resources are properties of
\link wcmf::lib::persistence::PersistenceAction `PersistenceAction`\endlink,
e.g. \link wcmf::lib::persistence::PersistenceAction::READ `PersistenceAction::READ`\endlink.

#### Permission inheritance ####

Permissions on __entity instances__ are passed to child entities in a _composite
relation_ (see \ref model_associations). The following image illustrates this:

\image html permission-inheritance.png "Permission inheritance"

If access to the `Book` instance _Book A_ is restricted for one role, the same
restriction also applies for the `Chapter` instances belonging to it
(_Chapter A1_, _Chapter A2_). An inherited access restriction can be removed by
explicitly granting the permission on the object in question.

#### Examples ####

The following code shows some permission examples:

~~~~~~~~~~~~~{.ini}
// tester role is not allowed to update any authors except for the specified one
// tester role is not allowed to update any authors stage attribute
app.src.model.Author??update = -tester
app.src.model.Author:111??update = +tester
app.src.model.Author.stage??update = +administrators

// tester role is not allowed to update any publishers name except for the specified one
// tester role is not allowed to update any authors stage attribute
app.src.model.Publisher.name??update = -tester
app.src.model.Publisher:111.name??update = +tester

// tester role is not allowed to read any book name except for the specified one
app.src.model.Book??read = -tester
app.src.model.Book:111??read = +tester

// tester is not allowed to read chapter 111 and due to inheritance also not sub chapter 222,
// and sub sub chapter 333, sub chapter 555 explicitly allowed and due to inheritance
// also sub sub chapter 666
app.src.model.Chapter:111??read = -tester +administrators
app.src.model.Chapter:555??read = +tester +administrators

// tester role is not allowed to execute SaveController
wcmf\application\controller\SaveController?? = -tester

// custom permissions
customPermission??start = +tester
customPermission??stop = -tester
~~~~~~~~~~~~~

### Permission management ### {#sec_perm_manage}

Permission management includes _creation_, _modification_ and _deletion_ of permissions
as well as handling _authorization requests_. In an wCMF application an instance
of \link wcmf::lib::security::PermissionManager `PermissionManager`\endlink is
used for these tasks. It is configured in the `PermissionManager` configuration
section.

Generally there are two kinds of permissions to be defined in an application.

- _Static permissions_ are already known when the application is designed,
  e.g. restriction to entity types or controllers. Since these permissions are
  not likely to be changed by application users, they can be stored in the
  application configuration.
- _Dynamic permissions_ are defined on the application data. These permissions
  will be set when the appropriate data is created. To allow application users
  to change these permissions they are typically stored in the database.

Different permission types require different ways of permission management,
particularly regarding storing permissions. To support this wCMF provides
several implementations of the
\link wcmf::lib::security::PermissionManager `PermissionManager`\endlink interface:

- \link wcmf::lib::security::impl::StaticPermissionManager `StaticPermissionManager`\endlink
  is used to retrieve permissions from the application configuration. The
  permissions are stored in the `Authorization` configuration section like shown
  in the following code:

~~~~~~~~~~~~~{.ini}
[Authorization]
??login = +*
??logout = +*
??checkPermissions = +*
??checkPermissionsOfUser = +administrators
app.src.model.wcmf.User??read = +administrators
app.src.model.wcmf.User??update = +administrators
app.src.model.wcmf.User??delete = +administrators
app.src.model.wcmf.User??create = +administrators
~~~~~~~~~~~~~

- \link wcmf::lib::security::impl::DefaultPermissionManager `DefaultPermissionManager`\endlink
  handles permissions that are stored in the database. The entity type that actually
  stores the permissions is required to have a _resource_, _context_, _action_
  and _roles_ attribute and is defined in the application configuration. The
  following lines are taken from the configuration of the \ref app "default application":

~~~~~~~~~~~~~{.ini}
[DefaultPermissionManager]
__class = wcmf\lib\security\impl\DefaultPermissionManager
permissionType = app.src.model.wcmf.Permission
~~~~~~~~~~~~~

- \link wcmf::lib::security::impl::ChainedPermissionManager `ChainedPermissionManager`\endlink
  is used to combine different
  \link wcmf::lib::security::PermissionManager `PermissionManager`\endlink instances.
  When asked for authorization, it delegates the request to all it's managers, while
  creation, modification and deletion of permissions is always handled by the
  first contained manager. An example configuration of this manager is shown in
  the code below:

~~~~~~~~~~~~~{.ini}
[PermissionManager]
__class = wcmf\lib\security\impl\ChainedPermissionManager
managers = {$defaultPermissionManager, $staticPermissionManager}

[DefaultPermissionManager]
__class = wcmf\lib\security\impl\DefaultPermissionManager
permissionType = app.src.model.wcmf.Permission

[StaticPermissionManager]
__class = wcmf\lib\security\impl\StaticPermissionManager
~~~~~~~~~~~~~

- \link wcmf::lib::security::impl::NullPermissionManager `NullPermissionManager`\endlink
  acts like there is no permission manager and is merely used for testing.

All implementations inherit from
\link wcmf::lib::security::impl::AbstractPermissionManager `AbstractPermissionManager`\endlink,
which already provides most of parts for handling authorization requests.

#### Temporary permissions #### {#sec_perm_temp}

There are situations, where a piece of code requires a certain permission in the
context of the current user, which is not possible to grant throughout the whole
application. For example, if a user wants to sign in to the application,
\link wcmf::lib::security::principal::PrincipalFactory `PrincipalFactory`\endlink
needs to provide a user instance although the anonymous user is not allowed
to read user instances. To accomplish this,
\link wcmf::lib::security::PermissionManager `PermissionManager`\endlink allows
to set a transient, temporary permission like in the following example:

~~~~~~~~~~~~~{.php}
$permissionManager = ObjectFactory::getInstance('permissionManager');
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
$userType = 'app.src.model.wcmf.User';

// set up a temporary permission to read the user instance for the given login
$permissionManager->addTempPermission($userType, '', PersistenceAction::READ);

$user = $persistenceFacade->loadFirstObject($userType, BuildDepth::SINGLE,
            array(
                new Criteria($userType, 'login', '=', $login)
            ), null);

// remove the temporary permission
$permissionManager->removeTempPermission($userType, '', PersistenceAction::READ);
~~~~~~~~~~~~~

### Checking permissions ### {#sec_perm_check}

To test, if a user has the permission to access a resource in the requested way
the method
\link wcmf::lib::security::PermissionManager::authorize `PermissionManager::authorize`\endlink
is used. It returns a boolean value indicating whether the user is authorized
or not.

The following code shows how to determine, if the current user is allowed to read
the given object:

~~~~~~~~~~~~~{.php}
$canRead = $permissionManager->authorize($object->getOID(), '', PersistenceAction::READ);
~~~~~~~~~~~~~

#### Default policies #### {#sec_perm_default_policies}

Default policies answer the question, what happens if __no permission__ is defined
on a requested resource. These rules depend on the authentication status of the
current user and are defined in
\link wcmf::lib::security::impl::AbstractPermissionManager `AbstractPermissionManager`\endlink
as follows:

- _Not authenticated_: Resource is _not accessible_
- _Authenticated_: Resource is _accessible_

## Input ## {#sec_input}

Generally all external input sent to the application should be considered harmful.

In PHP this input is stored in so called _Superglobals_, e.g. <em>$_GET</em>,
<em>$_POST</em>, <em>$_FILES</em>. To avoid using these global variables directly
in code, wCMF encapsulates them in the
\link wcmf::lib::presentation::Request `Request`\endlink instance and makes
them available through the
\link wcmf::lib::presentation::Request::getValue `Request::getValue`\endlink
method. Besides the variable name this method defines the following optional
parameters:

- `$default` default value if the value is not contained in the request
- `$filter` [filter](http://php.net/manual/en/filter.filters.php) to be applied
  to the value
- `$options` filter parameters if necessary

The `$filter` and `$options` values are passed to the
[filter_var](http://php.net/manual/en/function.filter-var.php) function and the
result is returned by the method.

The following code demonstrates the usage:

~~~~~~~~~~~~~{.php}
// validate an email value
$email = $request->getValue('email', '', FILTER_VALIDATE_EMAIL);

// validate a date using a regular expression and
// return the current date on failure
$today = date('Y-m-d');
$options = array("options" => array("regexp" => "/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/"));
$date = $request->getValue('date', $today, FILTER_VALIDATE_REGEXP, $options);
~~~~~~~~~~~~~
*/