You must first sign up to be able to contribute.

Version 1 (modified by Draven, 11 years ago)

RBAC System for Symfony (Beta 2)

RBAC 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.

The system includes two base applications.

  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.
  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.

If you want to rename these applications to match your needs, simply review the steps for adding an application below and rename the applications accordingly.

Also included is my Admin generator theme with the menu already set-up to include the admin modules needed to administer the user permissions.

Installing with a new project

  1. Download the RBAC.rar file attached and extract it to a place on your system.
  2. Create a new Symfony project with two applications in it, admin and frontend
  3. Now copy the contents of the RBAC folder to your newly created project. Be sure to accept overwritting of files when prompted.
  4. Edit your database.yml file located in project/config/database.yml to point to your database for this project.
  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.
  6. Now we need to build our model. Open your console and from within your project folder type
    $ symfony propel-build-model
  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

Installing in an exisiting project

Coming soon!

How to's:

Below 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.

Adding a new Application to manage

RBAC 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.

# default values
      admin: admin
      frontend: frontend
  current_app: admin

To 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

# default values
      admin: admin
      frontend: frontend
      calendar: calendar
  current_app: admin

The 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.

Adding a new module to manage

When 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.

The 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.

That'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.

Create a user

To 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.

Create a role

To 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.

Create a security file

In 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.

  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.
  1. 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.

For 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.

  is_secure:  on
  is_secure: on
  credentials: [[view_listing, create_button, edit_button, delete_button]]
  description: Role Listing Page
  is_secure: on
  credentials: [edit]
  description: Edit roles
  is_secure: on
  credentials: [create]
  description: Create new roles

Set permissions for roles

Setting 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).

On 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.

Set permissions for a user exclusively

Just 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.

Under 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.

Checking Permissions from within a script or template

There 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.

Lets 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.

  is_secure: on
  credentials: [special_permission]
  description: A permission for our super secret code

Now 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.

// example usage in an action
if($this->getUser()->hasCredential('special_permission', 'module_name', 'specialPermission'))
  // execute some code if the user has permission.

If the logged in user has the special_permission credential the containing code will be executed, if not the code is skipped.

We 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...

if($sf_user->hasCredential('special_permission', 'module_name', 'specialPermission')){
  echo "<input type='button' value='super secret button'>";

You 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.