Download the PHP package lucinda/security without Composer

All classes inside belong to Lucinda\WebSecurity namespace!

Configuration

To configure this API you must have a XML with following tags inside:

• security: (mandatory) configures the api
• users: (optional) required only if authentication is by XML (access control list)
• routes: (optional) required only if authorization is by XML (access control list)

Security

Maximal syntax of this tag is:

Where:

• security: (mandatory) holds global web security policies.
  • csrf: (mandatory) holds settings necessary to produce an anti-CSRF token (useful to sign authentication with)
    • secret: (mandatory) password to use in encrypting csrf token (use: Token\SaltGenerator)
    • expiration: (optional) seconds until token expires. If not set, token will expire in 10 minutes.
  • persistence (mandatory) holds one or more mechanisms useful to preserve logged in state across requests (at least one is mandatory!)
    • session: (optional) configures persistence of logged in state by HTTP session
      • parameter_name: (optional) name of $_SESSION parameter that will store logged in state. If not set, "uid" is assumed.
      • expiration: (optional) seconds until session expires. If not set, session will expire as server-default.
      • is_http_only: (optional) whether or not to set session cookie as HttpOnly (can be 0 or 1; 0 is default).
      • is_https_only: (optional) whether or not to set session cookie as HTTPS only (can be 0 or 1; 0 is default).
      • handler: (optional) name of class (incl. namespace or relative path) implementing SessionHandlerInterface to which session handling will be delegated to.
    • remember_me: (optional) configures persistence of logged in state by HTTP remember me cookie
      • secret: (mandatory) password to use in encrypting cookie (use: Token\SaltGenerator)
      • parameter_name: (optional) name of $_COOKIE parameter that will store logged in state. If not set, "uid" is assumed.
      • expiration: (optional) seconds until cookie expires. If not set, cookie will expire in one day.
      • is_http_only: (optional) whether or not to set cookie as HttpOnly (can be 0 or 1; 0 is default).
      • is_https_only: (optional) whether or not to set cookie as HTTPS only (can be 0 or 1; 0 is default).
    • synchronizer_token: (optional) configures persistence of logged in state by signing every request with a synchronizer token
      • secret: (mandatory) password to use in encrypting token (use: Token\SaltGenerator)
      • expiration: (optional) seconds until token expires. If not set, token will expire in 1 hour.
      • regeneration: (optional) seconds from the moment token was created until it needs to regenerate on continuous usage. If not set, token will be regenerated in 1 minute.
    • json_web_token: (optional) configures persistence of logged in state by signing every request with a json web token
      • secret: (mandatory) password to use in encrypting token (use: Token\SaltGenerator)
      • expiration: (optional) seconds until token expires. If not set, token will expire in 1 hour.
      • regeneration: (optional) seconds from the moment token was created until it needs to regenerate on continuous usage. If not set, token will be regenerated in 1 minute.
  • authentication: (mandatory) holds one or more mechanisms to authenticate (at least one is mandatory!)
    • form: (optional) configures authentication via form. If no dao attribute is set, authentication is done via XML and users tag is required!
      • dao: (optional) name of PSR-4 autoload-compliant class (incl. namespace) implementing Authentication\DAO\UserAuthenticationDAO that performs form authentication in database. [1]
      • throttler: (optional) name of PSR-4 autoload-compliant class (incl. namespace) extending Authentication\Form\LoginThrottler that performs login throttling prevention
      • login: (optional) configures login
        • page: (optional) page that performs login operation (all requests to this page will pass through this filter), also one to redirect back if login is unsuccessful. If none, then "login" is implicitly used.
        • target: (optional) destination page after successful login. If none, then "index" is implicitly used.
        • parameter_username: (optional) name of $_POST parameter username will be submitted as. If none, then "username" is implicitly used.
        • parameter_password: (optional) name of $_POST parameter password will be submitted as. If none, then "password" is implicitly used.
        • parameter_rememberMe: (optional) name of $_POST parameter that activates "remember me" option (value can be 0 or 1). If none, then "remember_me" is implicitly used.
      • logout: (optional) configures logout
        • page: (optional) page that performs logout operation (all requests to this page will pass through this filter). If none, then "logout" is implicitly used.
        • target: (optional) destination page after successful or unsuccessful logout. If none, then "login" is implicitly used.
    • oauth2: (optional) configures authentication via oauth2 provider
      • dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) implementing Authentication\OAuth2\VendorAuthenticationDAO that saves results of authentication in database
      • target: (optional) destination page after successful login. If none, then "index" is implicitly used.
      • login: (optional) generic page where login by provider option is available. If none, then "login" is implicitly used.
      • logout: (optional) page that performs logout operation. If none, then "logout" is implicitly used.
  • authorization: (mandatory) holds a single mechanism to authorize requests (at least one is mandatory!)
    • by_dao: (optional) configures authorization by database
      • page_dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) extending Authorization\DAO\PageAuthorizationDAO that checks user rights in database
      • user_dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) extending Authorization\DAO\UserAuthorizationDAO that checks page rights in database
      • logged_in_callback: (optional) callback page for authenticated users when authorization fails. If none, then "index" is implicitly used.
      • logged_out_callback: (optional) callback page for guest users when authorization fails. If none, then "login" is implicitly used.
    • by_route: (optional) configures authorization by XML, in which case routes tag is required. [1]
      • logged_in_callback: (optional) callback page for authenticated users when authorization fails. If none, then "index" is implicitly used.
      • logged_out_callback: (optional) callback page for guest users when authorization fails. If none, then "login" is implicitly used.

For examples of XMLs, check WrapperTest @ unit tests!

Notes: (1) If authorization is by_route, authentication is form with a dao attribute, then class referenced there must also implement Authorization\UserRoles!

Users

This tag is required if XML authentication (form tag is present and has no dao attribute) + authorization (by_route tag is present) are used. Syntax is:

Where:

• users: (mandatory) holds list of site users, each identified by a user tag
  • roles: (mandatory) holds list of roles guests (non-logged in users) belong to, separated by commas
  • user: (mandatory) holds information about a single user
    • id: (mandatory) holds unique user identifier (eg: 1)
    • username: (optional) holds user's username (eg: john_doe). Mandatory for XML authentication!
    • password: (optional) holds user's password hashed using password_hash (eg: value of ). Mandatory for XML authentication!
    • roles: (optional) holds list of roles user belongs to, separated by commas (eg: USERS, ADMINISTRATORS). Mandatory for XML authentication+authorization

If no user is detected in list above, GUEST role is automatically assumed!

Routes

This tag is required if XML authorization (by_route tag is present) is used. Syntax is:

Where:

• routes: (mandatory) holds list of site routes, each identified by a route tag
  • roles: (mandatory) holds list of roles all pages are assumed to belong by default to, separated by commas (eg: GUEST)
  • route: (mandatory) holds policies about a specific route
    • id: (mandatory) page relative url (eg: administration)
    • roles: (mandatory) holds list of roles page is associated to, separated by commas (eg: USERS, ADMINISTRATORS)

Binding Points

In order to remain flexible and achieve highest performance, API takes no more assumptions than those absolutely required! It offers developers instead an ability to bind to its prototypes in order to gain certain functionality.

Declarative Binding

It offers developers an ability to bind declaratively to its prototype classes/interfaces via XML:

Programmatic Binding

It offers developers an ability to bind programmatically to its prototypes via Wrapper constructor:

Execution

Once Wrapper, which defines following public methods:

Both authentication and authorization require following objects to be set beforehand and constructor injected:

• Request: encapsulating request to be handled
• Authentication\OAuth2\Driver[]: encapsulating a list of OAuth2 vendors to authenticate with

If authentication/authorization reached a point where request needs to be redirected, constructor throws a SecurityPacket. It may also throw:

• Authentication\Form\Exception: when login form is posted with wrong parameters names
• Authentication\OAuth2\Exception: when OAuth2 provider answers with an error to authorization code or access token requests
• PersistenceDrivers\Session\HijackException: when user id in session is associated to a different IP address
• Token\EncryptionException: when token could not be decrypted
• Token\Exception: when CSRF token is invalid or missing as "csrf" POST param @ form login or "state" GET param @ oauth2 authorization code response
• ConfigurationException: when XML is misconfigured, referenced classes are not found or not fitting expected pattern

Handling SecurityPacket

Developers of non-stateless applications are supposed to handle this exception with something like:

Developers of stateless web service applications, however, are supposed to handle this exception with something like:

Handling other exceptions

They can be handled as following:

Installation

First choose a folder, associate it to a domain then write this command in its folder using console:

Then create a configuration.xml file holding configuration settings (see getting results above) in project root with following code:

Then make this file a bootstrap and start developing MVC pattern on top:

Unit Tests

For tests and examples, check following files/folders in API sources:

• test.php: runs unit tests in console
• unit-tests.xml: sets up unit tests
• tests: unit tests for classes from src folder

Reference Guide

Class SecurityPacket

SecurityPacket class encapsulates an response to an authentication/authorization event that typically requires redirection and defines following methods relevant to developers:

Values of getStatus depend on argument enum case:

Usage example:

https://github.com/aherne/lucinda-framework/blob/master/src/Controllers/SecurityPacket.php

Class Request

Request encapsulates information about request necessary for authentication and authorization via following public methods:

Usage example:

https://github.com/aherne/lucinda-framework-engine/blob/master/src/RequestBinder.php

Interface OAuth2 Driver

Authentication\OAuth2\Driver interface encapsulates an oauth2 vendor to authenticate with and defines following methods:

Usage example:

https://github.com/aherne/lucinda-framework-engine/blob/master/src/OAuth2/AbstractSecurityDriver.php

Interface OAuth2 UserInformation

Authentication\OAuth2\UserInformation interface contains blueprints for retrieving information about logged in user on OAuth2 provider via following methods:

Usage example:

https://github.com/aherne/lucinda-framework-engine/blob/master/src/OAuth2/AbstractUserInformation.php

Interface OAuth2 VendorAuthenticationDAO

Authentication\OAuth2\VendorAuthenticationDAO interface contains blueprints for saving info about logged in user on OAuth2 provider via following methods:

Usage example:

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersOAuth2Authentication.php

Interface UserAuthenticationDAO

Authentication\DAO\UserAuthenticationDAO interface contains blueprints for form-based database authentication via following methods:

Usage example:

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersFormAuthentication1.php

Abstract Class LoginThrottler

Authentication\Form\LoginThrottler abstract class encapsulates form login throttling algorithm (against brute-force attacks) on a datasource (sql or nosql) via following public methods:

Class must be extended in order to implement following abstract protected method:

Usage example:

https://github.com/aherne/lucinda-framework-engine/blob/master/src/AbstractLoginThrottler.php https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/SqlLoginThrottler.php

Abstract Class UserAuthorizationDAO

Authorization\DAO\UserAuthorizationDAO abstract class encapsulates database authorization where user accounts are checked in database via following public methods:

Class must be extended in order to implement following abstract method:

Usage example:

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersAuthorization1.php

Abstract Class PageAuthorizationDAO

Authorization\DAO\PageAuthorizationDAO abstract class encapsulates database authorization where access control list is checked in database via following public methods:

Class must be extended in order to implement following abstract methods:

Usage example:

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/PagesAuthorization.php

Interface UserRoles

Authorization\UserRoles interface defines blueprints for any authorization where user roles are checked in database via following public methods:

Usage example:

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersFormAuthentication3.php