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:
 
<div class="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' => $login,
    'password' => $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->getLogin());
}
```
</div>
 
@note The login of 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 login is
\link wcmf::lib::security::principal::impl::AnonymousUser::USER_GROUP_NAME `AnonymousUser::USER_GROUP_NAME`\endlink.
 
The configuration of the authentication process in the \ref app "default application"
looks like the following:
 
<div class="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
```
</div>
 
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 can 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__:
 
<div class="ini">
```
resource?context?action = +allowedRole -deniedRole ...
```
</div>
 
#### 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_
 
<div class="ini">
```
resource?context?action = +allowedRole -*
```
</div>
 
and is equivalent to
 
<div class="ini">
```
resource?context?action = +allowedRole
```
</div>
 
#### Default policy ####
 
If no permissions are defined on a resource, a _default policy_ will be applied by default.
\link wcmf::lib::security::impl::AbstractPermissionManager `AbstractPermissionManager`\endlink implements the 
default policy as follows:
 
- If the current user is __not authorized__, the default policy denies all actions
- If the current user is __authorized__, the default policy allows all actions
 
The \link wcmf::lib::security::PermissionManager::authorize `PermissionManager::authorize`\endlink method
allows to ignore the default policy by passing `false` as the `$applyDefaultPolicy` parameter, in which
case the method returns null, if no permissions are defined for the resource.
 
#### Operator precedence ####
 
Granted roles are evaluated before denied ones. That means that the following
code grants the permission to a user who has both roles (_allowedRole_ and _deniedRole_)
although the permission is denied for one of the roles.
 
<div class="ini">
```
resource?context?action = +allowedRole -deniedRole
```
</div>
 
#### 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`)
- _Media_ to restrict access to file resources
  (e.g. `media:/folderA??hidden`)
 
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.
While all actions can be applied to instances, for properties only _read_ and _update_
are taken into account.
 
@note __Entity relations__ are treated like entity properties, which means that read and update
access can be restricted.
 
The __actions for the file related resources__ are _read_, _write_, _locked_ (read only) and _hidden_.
 
#### Dynamic roles ####
 
Besides assigning _static roles_ to users, it's sometimes useful to have roles, that evaluate
dynamically in the current context (_requested resource_, _user_ and _action_). With these
so called _dynamic roles_ it is for example possible to assign permissions to the creator of
an instance or realize date/time based permissions.
 
Dynamic roles implement the \link wcmf::lib::security::principal::DynamicRole `DynamicRole`\endlink
interface and are defined in the `DynamicRoles` configuration section.
 
The following example shows the configuration of the
\link wcmf::lib::security::principal::impl::CreatorRole `CreatorRole`\endlink in
the \ref app "default application":.
 
<div class="ini">
```
[DynamicRoles]
creator = $creatorRole
 
[CreatorRole]
__class = wcmf\lib\security\principal\impl\CreatorRole
```
</div>
 
@note Dynamic roles are checked before static role assignments. That means you
could define a dynamic role with the same name as a static role and add custom
matching code.
 
#### 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:
 
<div class="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
 
# the tmp directory is hidden for everyone
# only administrators can rename or delete the uploads directory
media:/tmp??hidden = +*
media:/uploads??locked = -administrators +*
 
# custom permissions
customPermission??start = +tester
customPermission??stop = -tester
```
</div>
 
### 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:
 
<div class="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
```
</div>
 
- \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":
 
<div class="ini">
```
[DefaultPermissionManager]
__class = wcmf\lib\security\impl\DefaultPermissionManager
permissionType = app.src.model.wcmf.Permission
```
</div>
 
- \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:
 
<div class="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
```
</div>
 
- \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:
 
<div class="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, [
            new Criteria($userType, 'login', '=', $login)
        ], null);
 
// remove the temporary permission
$permissionManager->removeTempPermission($userType, '', PersistenceAction::READ);
```
</div>
 
### 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:
 
<div class="php">
```
$canRead = $permissionManager->authorize($object->getOID(), '', PersistenceAction::READ);
```
</div>
 
#### 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_
 
## Sessions ## {#sec_session}
 
wCMF provides the following \link wcmf::lib::core::Session `Session`\endlink
implementations:
 
- \link wcmf::lib::core::impl::DefaultSession `DefaultSession`\endlink is a session
  that uses PHP's default server side session implementation in combination with a
  session cookie.
- \link wcmf::lib::core::impl::AuthTokenSession `AuthTokenSession`\endlink additionally
  requires clients to send an `X-Auth-Token` request header.
- \link wcmf::lib::core::impl::ClientSideSession `ClientSideSession`\endlink has
  no server state as it stores the data in cookies.
 
## 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
- `$validateDesc` description of the validation to be applied to the value
 
The `$validateDesc` parameter is passed to the
\link wcmf::lib::validation::Validator::validate `Validator::validate`\endlink method
and `null` is returned if validation fails.
 
The following code demonstrates the usage:
 
<div class="php">
```
// validate an email value
$email = $request->getValue('email', '', 'filter:{"type":"validate_email"}');
 
// validate a date using a regular expression and return the current date on failure
$today = date('Y-m-d');
$date = $request->getValue('date', $today, 'regex:{"pattern":"/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/"}');
```
</div>
 
For more information about validation see \ref pers_validation.
 
### CSRF protection ### {#sec_input_csrf}
 
To avoid [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) vulnerabilities
in a web application, forms are usually protected by using _CSRF tokens_. The
\link wcmf::lib::presentation::Controller::generateCsrfToken `Controller::generateCsrfToken`\endlink
method is used to generate a unique token value for each form display. The token is validated by using the
\link wcmf::lib::presentation::Controller::validateCsrfToken `Controller::validateCsrfToken`\endlink
method when the form is submitted. For proper identification, tokens are referenced by a
name (e.g. the form's name) which is passed to these methods.
 
The following example demonstrates the usage of these methods.
 
A new token value is generated each time the form is displayed:
 
<div class="php">
```
class UserController {
 
  public function render() {
 
    $this->generateCsrfToken('login');
 
  }
}
```
</div>
 
This creates the `csrf_token` response variable. The variable is used to add
the token as a hidden field to the form:
 
<div class="html">
```
<input type="hidden" name="csrf_token" value="{$csrf_token}">
```
</div>
 
After form submission the controller validates the token and acts appropriately:
 
<div class="php">
```
class UserController {
 
  public function login() {
 
    if (!$this->validateCsrfToken('login')) {
      // error
    }
    else {
      // do login
    }
 
  }
}
```
</div>
*/