Authenticator Plugins

See also: Writing Registry Plugins

Some additional conventions are required when writing an Authenticator Plugin.

1. The name of the Plugin must match the format FooAuthenticator.
2. The Plugin must implement a model FooAuthenticator, and a corresponding Controller. (These are in addition to the other models and controllers required for Plugins.)
   1. This Model should extend AuthenticatorBackend, which defines some standard interfaces and provides some behind the scenes common functionality.
   2. The Controller should to extend SAuthController ("Standard Authenticator" Controller), which provides some common functionality.
   3. When a new Authenticator Backend is instantiated, a skeletal row in the corresponding co_foo_authenticators table will be created. There is no add operation or view required. The skeletal row will point to the parent Authenticator Model.
   4. When an Authenticator Backend is edited, the entry point to the Authenticator Plugin will be foo_authenticator/foo_authenticators/edit/#. This will be called immediately after the Authenticator Backend is first instantiated.
3. Note Authenticator has a hasOne (ie: 1 to 1) relationship with FooAuthenticator.
4. The table cm_foo_authenticators should include a foreign key to cm_authenticators:id.
   1. Other tables used by the plugin should reference cm_foo_authenticators:id.
5. The Plugin must implement several functions, which are defined in Model/AuthenticatorBackend.php. More details are in the next section.
6. The Plugin must implement a model for the Authenticator itself, Model/Foo.php. For example, for the PasswordAuthenticator Plugin, this Model is Password and is defined in Password.php. The Plugin must also implement a corresponding Controller, Controller/FoosController.php. This Controller should extend SAMController.php ("Standard Authenticator Model" Controller).

Implementing an Authenticator Plugin

There are two supported approaches for implementing an Authenticator Plugin. Plugins that only need to provide a form, storing the results in the database, can use the Simple method. Plugins with more complicated requirements, such as redirecting the user to an external service, must instead use the Complex method.

Simple Method

1. Define the database schema for the Authenticator model (Foo or Password in the above examples; Foo will be used going forward) in schema.xml as usual, and create the Model file (Foo.ctp) as usual.
2. Create two symlinks in your Plugin's View/Foos directory:
   1. info.ctp -> ../../../../View/Authenticators/info.ctp
   2. manage.ctp -> ../../../../View/Standard/edit.ctp
3. Create a fields.inc file in the same directory that contains the form elements you need for your Plugin. (See other Authenticator plugins in the AvailablePlugins directory for examples.)
4. Implement Model/FooAuthenticator.php as described above. Specifically, you must
   1. Override current() so that it returns the current record(s) based on the parameters passed via the function signature. The results from this function will be passed to your fields.inc View via the $vv_current variable.
   2. Override manage() so that it implements whatever backend logic your plugin requires, including data validation and the actual saving to the database. You should also create a history record indicating that the Authenticator was updated, as part of this call.
5. Implement reset() and status() calls.
6. FoosController.php should use $this->calculateParentPermissions() to calculate permissions for the required actions in isAuthorized().

Complex Method

In the Complex method, the plugin is expected to override the controller's manage() action (and reset() if appropriate) instead of overriding the model's functions as described above. In other words, if you override SAMController::manage(), you do not need to worry about overriding AuthenticatorBackend::manage() or current(). This gives your plugin the ability to perform whatever logic and process flow it needs.

Your controller's manage and (if appropriate) reset actions must manually call provisioning at the appropriate point in your plugin's logic.

...
// Finished updating our Authenticator's state in the database
$this->Authenticator->provision($coPresonId);
 
// All done
$this->performRedirect();

When you are finished, your controller should return control to COmanage by calling $this->performRedirect().

Use $this->calculateParentPermissions() to calculate permissions for the required actions in isAuthorized().