UserRbac (diff)

You must first sign up to be able to contribute.

Changes from Version 1 of UserRbac

Draven (IP:
08/30/06 19:15:24 (11 years ago)



  • UserRbac

    v0 v1  
     1= RBAC System for Symfony (Beta 2) = 
     3RBAC stands for Role Based Access Control. Its a system used to grant users certain privelages to areas or functionality of a website. In Symfony, it allows you to give groups of people access to modules, action, and even whether or not to execute code within actions or templates. 
     5The system includes two base applications. 
     6  1. '''Admin''': this is the application which allows you to manage all of your permissions as well as your applications administration features. This application utilizes the admin generator with some set modules and actions there by allowing you to still add all your other admin functions in the usual way using the admin generator. 
     7  2. '''Frontend''': this is the application which holds your front end application modules that your users will use. The only module included in this application is a user module which handles the logging in of users. The user module includes the functions and templates (very basic templates to allow you to customize their look and feel) needed to set-up your users session and permission checks. 
     9If you want to rename these applications to match your needs, simply review the steps for adding an application below and rename the applications accordingly. 
     11Also included is my Admin generator theme with the menu already set-up to include the admin modules needed to administer the user permissions. 
     13=== Installing with a new project === 
     14  1. Download the RBAC.rar file attached and extract it to a place on your system. 
     15  2. Create a new Symfony project with two applications in it, '''admin''' and '''frontend''' 
     16  3. Now copy the contents of the RBAC folder to your newly created project. Be sure to accept overwritting of files when prompted. 
     17  4. Edit your database.yml file located in project/config/database.yml to point to your database for this project. 
     18  5. Under your projects /data folder you'll find an sql folder contining the database structure and some basic data needed to get the system up and running, execute this file so your DB is seeded with the data and table strucutres. 
     19  6. Now we need to build our model. Open your console and from within your project folder type  
     21$ symfony propel-build-model 
     23  7. Congratulations, your new RBAC system is now installed. Point your browser to your projects admin homepage http://project/admin_dev.php/ and you should get a login screen. Login using '''admin/admin''' 
     25=== Installing in an exisiting project === 
     26  Coming soon! 
     30= How to's: = 
     32Below is a list of how-to's to help guide you through using the RBAC system to manage users in any application within a project. 
     33=== Adding a new Application to manage === 
     34RBAC system is designed to handle multiple applications within a project. To add a new application or to edit the naming of an application (like the frontend app for example) open your admin app.yml config file found in apps/admin/config/app.yml. It should look like this. 
     37# default values 
     39  apps: 
     40    all: 
     41      admin: admin 
     42      frontend: frontend 
     43  current_app: admin 
     46To add a new application to the list simple add a new line after frontend:frontend using the name of your app. For example, if we wanted to add a new application called calendar, which we created in our apps directory, you would add calendar: calendar like this 
     49# default values 
     51  apps: 
     52    all: 
     53      admin: admin 
     54      frontend: frontend 
     55      calendar: calendar 
     56  current_app: admin 
     59The RBAC admin system usings this configuration to identify what applications are present in the system, and what the name of the admin application is, represent by the current_app config. 
     61=== Adding a new module to manage === 
     62When you create a new module which you want have RBAC handle permissions for, you need to let the system know that this module exists and under which application the new module resides. To do this, login to the admin application and under admin menu at the top select '''configuration''' and then '''Modules'''. 
     64The following page lists all the current modules registered within the system and under which application the module resides. To add a new module simply click the create button and enter the modules name and select which application which the module resides under from the drop down list. 
     66That's it, the system will now search under that modules config directory for a security.yml file and, if present, will allow you to assign credentials to user and roles with it. 
     68=== Create a user === 
     69To create a new user, login to the admin apllication and under the admin menu '''User Management''' select '''Users''' and then '''Create User'''. Fill out the form with the new users detail and assign atleast role by checking the checkbox next to the roles name. 
     71=== Create a role === 
     72To create a new role, login to the admin application and under the admin menu '''User Management''' select '''Group Roles''' and then '''Create Roles'''. Enter the new role name and click save. That's it. The next time you edit or create a user the new role will be available to assign. 
     74=== Create a security file === 
     75In order to define security credentials required for an action, you need to create a security.yml file for each module under the systems control. Luckily, the system uses the exact same security file as the basic security features implemented in symfony with 2 minor additions. 
     77  1. There is an additional setting called description: which, as the name suggests, is a description for what the action you are assign permissions to does. This is used by the admin panel to describe each actions responsibilty so it's easy for admins of the system to identify what permissions they are setting. 
     79  2. You can assign security to actions which don't exist. The reason being, if you want to check some permission from within an action or template, you need a away to NAME that permission action without setting a permission on the overall action and thereby negating the check from within a chunk of code. More info can be found on this under the heading '''Checking Permissions from within a script or template'''. 
     81For more info on the proper way to create a security.yml file I suggest reading the symfony book under the '''Security''' link. FOr examples sake I give you an example of a typical action definition in a security.yml file. This is from the Role module in the admin application. 
     85  is_secure:  on 
     88  is_secure: on 
     89  credentials: [[view_listing, create_button, edit_button, delete_button]] 
     90  description: Role Listing Page 
     93  is_secure: on 
     94  credentials: [edit] 
     95  description: Edit roles 
     98  is_secure: on 
     99  credentials: [create] 
     100  description: Create new roles 
     103=== Set permissions for roles === 
     104Setting permissions for roles is quite simple. Login to the admin application, under the admin menu go to the List Roles page. On this page you'll see each of the roles available in the system, and to the right of each role is a Permissions, Edit, and Delete button. Click the Permissions button (looks like a key). 
     106On the permissions page you are presented with two drop down menus. The first called '''Applications''' allows you to select under which application you  would like to set permissions. Next to that is a list of available modules under that application. By selecting applications and modules the page will reload and present a list of Permissions to be set for that application and module. Simply check off the permissions you want to assign this role and click save, then move on to the next module or application. That's it. Now any users assign to that role will be granted access to whatever permissions you assigned. 
     108=== Set permissions for a user exclusively === 
     109Just like the role permissions, you can assign individual users a set of permissions which you don't want an entire group to have, but instead just a single user while still aloowing the user access to his group role permissions. 
     111Under the users list page in the admin application you'll find next to each user a permissions button just like that found in the roles. By clicking the permissions button you can assign permissions in exactly the same manner as you did with the roles, with the difference that these permissions are special to only that particular user. 
     113=== Checking Permissions from within a script or template === 
     114There are often times when you want to safe gaurd a particular part of an action or the display of a button without having to set a credential for an entire action. The RBAC system allows you to accomplish this by simply adding a new security action definition to your security file whos name does not match and exisiting action.  
     116Lets say we have a piece of code with an action that we want to run only with a user meets a specific permission. First we need to add the permission to our security file, we'll call it '''specialPermission'''  (creative eh?) Now lets open our security.yml file under module we want to assign this permissions and add the following. 
     120  is_secure: on 
     121  credentials: [special_permission] 
     122  description: A permission for our super secret code 
     125Now that we have defined our permission, it will be available in our admin application to assign to users or roles. Next, lets add the check for this permission to an action. Within our action we can do the check using the following. 
     128// example usage in an action 
     129if($this->getUser()->hasCredential('special_permission', 'module_name', 'specialPermission')) 
     131  // execute some code if the user has permission. 
     135If the logged in user has the special_permission credential the containing code will be executed, if not the code is skipped. 
     137We can even use this in our templates. Lets say we have a super secret button that is somehow linked with our script that we want to also hide if the user doesn't have permission. We can do so like this in our template... 
     141if($sf_user->hasCredential('special_permission', 'module_name', 'specialPermission')){ 
     142  echo "<input type='button' value='super secret button'>"; 
     147You can also use permissions set for actions to hide scripts in the action or template, just replace the action name and permission settings in the checks with the appropriate values. You can also perform checks against permission settings from different modules by changing the identifying module name. NOTE: You cannot however use a permission setting in one application from another, scoping in symfony does not allow this however it's unlikely that need would ever arise.