Background
Traffic Plugins allow for the manipulation of the platform's login flow. Instantiated Traffic Plugins are called Traffic Detours.
Entry Point Model
The Entry Point model for Traffic Plugins allows for plugin specific configurations to be managed, and will be used to construct the URL targets for runtime redirects. Traffic Plugins can intercept the authentication flows at various points, described below. Traffic Plugins declare which Detour Contexts they support via setSupportedDetourContext().
Because authentication happens at the Platform level, Traffic Plugins are only instantiated within the COmanage CO. In order to allow Traffic Plugins maximum flexibility, they are invoked via redirects, and must redirect back to Traffic Controller after performing their work, most easily by calling finishDetour(). (Specifying the supported Detour Contexts reduces the number of unnecessary redirects.)
Login Flow
The Login Flow begins when RegistryAuthComponent::beforeFilter determines that authentication is required to access the target resource. A redirect is issued to /traffic/prepare-login (handled by TrafficController).
Login Preparation
Login Preparation allows for setup tasks to be run before the actual login happens.
The Traffic Plugin interface for the Login Preparation phase is not currently supported.
After Login Preparation is complete, TrafficController issues a redirect to /traffic/initiate-login.
Login Handling
The actual authentication event takes place during Login Handling.
The Traffic Plugin interface for the Login Handling phase is not currently supported.
If no Traffic Plugin handles login, TrafficController issues a redirect to the default web server authentication location (/auth/login/login.php).
After Login Handling is complete, TrafficController or the Traffic Plugin that handled login issues a redirect to /traffic/process-login.
Post Login Processing
After the user authenticates during the Login Handling phase, Traffic Plugins can perform follow up tasks before control is returned to the application. Traffic Plugins implementing this interface should declare support for the postlogin context. The entry point for this context is /registry/plugin/entrypointmodel/postlogin?detour_id=x.
Before invoking any Traffic Plugins, TrafficController will record the login event.
The authenticated username is available via the Auth.external.user session variable.
After Post Login Processing is complete, TrafficController returns control to the application.
Logout Flow
Traffic Plugin support for the Logout Flow is not currently available.
Considerations
Browser Redirect Limits
In order to avoid redirect loops, web browsers implement a limit on the number of redirects that may be issued before a page is rendered, typically around 16 - 20. Because as many as 5 redirects can be issued before a Traffic Plugin is called, Traffic Plugins should take to use as few redirects as possible, or to render an intermediate page to ensure the redirect limit is not reached.
Plugin Execution Order
In general, it is expected that relatively few Traffic Plugins will be used for a given deployment, and so in order to simplify configuration there is only one Plugin configuration point (in the COmanage CO). The same Traffic Detour order is used for all contexts, Traffic Plugins that do not support a given context are skipped.
Unauthenticated Context
Because Traffic Plugins are responsible for handling some aspect of the authentication sequence, the normal authentication and authorization procedures are not in use. Traffic Plugins should avoid disclosing sensitive data (except perhaps in the postlogin context) or relying on the correct sequence of execution (since a malicious user could manually issue traffic requests out of order).
Example
// $plugin/src/config/plugin.json
{
"types": {
"traffic": [
"WidgetDetours"
]
}
}
// $plugin/src/Model/Table/WidgetDetoursTable.php
namespace WidgetDetour\Model\Table;
use \App\Lib\Traits\TrafficDetourTrait;
class WidgetDetoursTable extends Table {
// Standard Cake model stuff here
$this->setPrimaryLink(['traffic_detour_id']);
$this->setAllowEmptyPrimaryLink(['postlogin']);
$this->setRequiresCO(false);
$this->setSupportedDetourContext('postlogin');
}
// $plugin/src/Controller/WidgetDetoursController.php
namespace WidgetDetour\Controller;
use App\Controller\StandardDetourController;
class WidgetDetoursController extends StandardDetourController {
// Standard Cake controller stuff here
// "postlogin" context handler
public function postlogin() {
$session = $this->getRequest()->getSession();
$detourId = $this->getRequest()->getQuery("detour_id");
// Do some work
$authenticatedUsername = $session->read('Auth.external.user');
return $this->finishDetour();
}
}