Authenticating Controller Actions
From FuseWiki
Using the FuseApplication Controller and Auth/User class, you can add an authentication scheme to your application that supports per-user and per-group permissions and restrictions. The controller action permissions can be set up and managed dynamically using database tables, but here we will discuss a simpler approach by specifying action restrictions in our controller.
Note: for legacy projects that use the object FuseUser, please visit Authenticating Controller Actions Legacy
Contents |
[edit] Configuration
[edit] 1. Enable and Configure Authentication
First, you will need to add some configuration options to your config/FUSE-common.conf.php file. If this file doesn't exist, create it. Its contents should look something like this:
<?php
Config::Set('auth.enabled', true);
Config::Set('auth.password_digest_salt', '12345');
Config::Set('auth.login_redirect_page_default', '/' );
?>
The options available for authentication are discussed in Auth.conf.php
[edit] 2. Setup the user database schema
Download users-mysql.sql and run it as a query into your database. This script will create the necessary tables for users, groups, privileges, preferences, and restrictions.
[edit] 3. Download the AuthController
Download the default FUSE AuthController from http://www.phpfuse.net/addons/controllers/AuthController.class.phps and put it in the controllers/ directory beneath your project root. Rename it to AuthController.class.php
[edit] 4. Download basic login views
Next, set up the front end templates that will be served to the user. Download the following files to /home/myproject/views/Auth/
You can alter these templates to suit your project, just be sure to leave in the "username" and "password" inputs.
[edit] 5. Add login routes
Add the following routes to /home/myproject/config/routes.conf.php (or wherever you have your routes)
FuseURIRouter::route_connect( 'auth/login', array(
'controller' => 'Auth',
'action' => 'login'
)
);
FuseURIRouter::route_connect( 'auth/logout', array(
'controller' => 'Auth',
'action' => 'logout',
)
);
FuseURIRouter::route_connect( 'auth/no_permission', array(
'controller' => 'Auth',
'action' => 'no_permission',
)
);
[edit] 6. Setup the method permissions in your controller
Let's assume we had a news controller (NewsController.class.php) and wanted to make sure that only authenticated users can add, edit, or delete news. The NewsController would look like this:
FUSE::Require_class('AppControl/FuseDataController');
class NewsController extends FuseDataController
public $method_access = array(
'add' => array('requires_login' => true, 'global_access' => true),
'edit' => array('requires_login' => true, 'global_access' => true),
'delete' => array('requires_login' => true, 'global_access' => true)
);
}
The second parameter to method_access() is an associative array of options. The options are as follows:
- requires_login - does the method require a login at all? If this is unset or false, the method will be publicly available without authorization.
- global_access - If true, any authenticated user without an explicit restriction for this method can access it. If false (and requires_login is true), the user must have an explicit permission entry in the user_privs or group_privs table for this controller and action. See the "Assigning Permissions" section below for information on setting up more detailed access control.
Note: If authentication is enabled, the controller will automatically check permissions for add(), edit(), and delete() and add "allow" parameters, respectively, to the template (view), with a value of true or false. This is especially useful in the "list" method, where you can show edit and/or delete options only if the logged in user has those permissions. The naming convention for this parameter is:
'allow_' . strtolower($controller_name) . '_' . $method_name;
So, for the NewsController, the three additional parameters would be:
- allow_news_edit
- allow_news_add
- allow_news_delete
[edit] Creating Users
FUSE comes with a script for creating users. This script is in the manage/ directory beneath your project and is called user.php. The first time you run user.php, it will prompt you to create an administrator user. The synax for creating a user is:
user.php create username password groupname
>php user.php create jim jimspass jimsgroupname
[edit] Assigning Permissions
The user.php script (found in the manage/ directory beneath your project) can also be used to assign permissions. To assign a user permission to use a specific controller method, use the usergrant action. For controller method permissions, the format is controller_name/controller_method. Note that controller_name does NOT include the "Controller" Suffix:
user.php usergrant username privilege_type [privilege_value]
>php user.php usergrant jim controller_method Photo/Add
to give jim access to the entire controller:
>php user.php usergrant jim controller Photo
The user.php script also supports the following functions:
user.php userrevoke username privilege_type [privilege_value]
user.php groupgrant groupname privilege_type [privilege_value]
user.php grouprevoke groupname privilege_type [privilege_value]
[edit] Getting the active user's info
By default, when a user is logged in, the following parameters are available in any view:
- active_username
- active_user_id
If you need to access the User model for the current user, you can do (in a controller):
$user = $this->get_active_user_obj(); //returns the User model
More information on the user object can be found at: API:Auth/User.class.php
[edit] Authenticating the entire controller
in FUSE, application controllers themselves support the public members $requires_login and $global_access, as discussed above in "Set up the method permissions in your controller". For example, the following will ensure that all controller access requires that the user is logged in:
class MyController extends FuseApplicationController {
public $requires_login = true;
}
The following will ensure that controller access is denied if the user is not logged in OR if the user doesn't have an explicit permission for the controller:
class PhotoController extends FuseApplicationController {
public $requires_login = true;
public $global_access = false;
}
To give a user permission to use the PhotoController, run the following in the manage/ directory beneath your project:
>php user.php usergrant jim controller Photo
