PermissionChecker Explained

          For my latest task I’ve been looking into re-implementing the persistence layer of Liferay permissions to authenticate users and obtain authorization data from a client identity and access management engine. In the process I thought I’d explain a little bit about the details of Liferay permissions and in this first post more specifically the PermissionChecker. How it’s implemented and where the integration points are.

So how does the portal determine what permissions to grant each user? In Liferay, permissions can be associated with a user in a few different ways. The permission can be assigned directly to a user or it can be inherited through the hierarchy of groups (with the assigned permission of course) that the user belongs to. Permissions can also be assigned to a role which then passes it on to whichever user or group has that role. Yes, quite verbose but very powerful. The PermissionChecker is where all this heavy lifting occurs and where we actually determine whether a user “has permissions” to perform certain actions. A PermissionChecker is created or borrowed from a pool and placed in the thread local and themeDisplay object on every request.

The implementation can be swapped out for your own class by extending com.liferay.portal.security.permission.PermissionCheckerImpl and overriding the necessary methods to implement your own functionality. Remember to specify your class name in portal.properties for the property permissions.checker.

Now let’s look at an example of how the PermissionChecker is used in a simple case where we want to add a new page to a community layout set. We start this explanation from within the Communities Portlet lifecycle.  We’re adding a new layout to the layout set of a Community group so a process action request gets served by EditPagesAction which is just a struts action class. The first thing that happens is a check permissions call which uses the PermissionChecker to determine whether the user has the rights to perform the action MANAGE_LAYOUTS on targeted layout set of the community group. You will see permission checks like this all over Liferay’s view and service layer classes whenever we try to perform an action on a portal object. An example of what this check might look like:

 

GroupPermissionUtil.contains(permissionChecker,group.getGroupId(), ActionKeys.MANAGE_LAYOUTS)

 

As mentioned earlier, a user can inherit a permission from a hierarchy of groups that the user belongs to or a role that is directly or indirectly associated with the user. This hierarchical complexity is handled by a class within the PermissionChecker called the PermissionCheckerBag. So what’s in the bag? On first call to perform an action the bag is actually empty (null to be technically correct). Based off the user id we grab all the Organizations and UserGroups that the user belongs to along with the corresponding Groups since all these “containers” are also represented as Groups. We also obtain and throw in the roles as well. You can think of the PermissionCheckerBag as a container for all the user’s Group and Role associations per community and also contains helper (permission shortcut) methods that determine whether a user is a community owner or admin. This object is stored for the remainder of the request and discarded when the PermissionChecker is returned to the pool. (For performance reasons we should cache this object for the entire user session. This issue is now http://support.liferay.com/browse/LEP-6273). This class can also be extended as the implementation class com.liferay.portal.security.permission.PermissionCheckerBagImpl is only used in PermissionChecker.

Now that we have the PermissionCheckerBag inside the PermissionChecker we are ready for the next step of the process, checking the bag's groups and roles for the permission to perform the action MANAGE_LAYOUTS. As with all service calls in Liferay this one begins with a *ServiceUtil helper class, in this case PermissionServiceUtil which is used to obtain the proper service via Spring. This service class can be easily swapped out in portal-spring.xml if so desired. The utility uses PermissionServiceFactory to get the PermissionService bean and its default implementation com.liferay.portal.service.impl.PermissionServiceImpl or a class that you implement yourself. In our example for adding a layout to the community layout set we first need to start by getting a list of resources scoped for Individual, Group, Group Template and Company through another service helper ResourceLocalServiceUtil (lets leave this service alone unless you are planning to offload resource management to another datastore). Resources identify the target object that you are trying to “MANAGE_LAYOUTS” on. Now with this list of resources and the PermissionCheckerBag we can do a check for the permissions we are looking for. The actual call looks like this:

 

PermissionLocalServiceUtil.hasUserPermissions(user.getUserId(), groupId, actionId, resourceIds, bag)

 

This PermissionService contains the bulk of the logic for Liferay permissions and brings together all the data gathered up to this point to perform the required queries. This call is made from the PermissionChecker and can also be customized to implement your own authorization logic if required. Again, just swap out the service implementation.

Let’s look at some of the SQL calls used to figure out permissions for a user to add a layout. First we want to find all the Permissions for the action we are performing on the resource.

 

SELECT {Permission_.*} FROM Permission_ WHERE (actionId = ?) AND (resourceId = ? OR resourceId = ? OR resourceId = ? OR resourceId = ?)  

 

Once we have all the Permissions for the action and resource we want to check to see if any of the user associations either directly or inherently has the permission. We do this via the PermissionFinder which is helper class for performing custom SQL calls for permissions. The PermissionFinder performs a custom SQL based on the permissions.user.check.algorithm specified in portal.properties and returns true if the user has an association to the permission. Of course these SQL calls are made once before they are cached in the portal for subsequent requests.

So there you have it. PermissionChecker Explained. In case anyone was wondering.

 

Blogs
Nice Joe,

Will the functionality of the PermissionChecker be the same in the future as it is now?
Once we commit the LEP you'll have a flag to decide whether you want to cache the bag. If you do, changes to a users role and group associations won't take affect until the next user login. The price you pay i guess. Right now we check every time, thats why changes are instant.
Hi Joe,
thank you for this post, I'm just wondering why Resource_ and Permission_ table are epmty. Did ResourceAction table substituted them ?
Hi Jakub,

Yeah, those two tables are used by algorithms 1 to 5. You are probably using algorithm 6 which is the default (and recommended) in Liferay 6 which uses the ResourceAction table.

Eventually the other algorithms might be removed and we won't need those other tables, but we need to make sure that doesn't cause problems to people before doing that.
Hey, Joe,

This is the first time I read your blog.

Your formal English is plain, clear and direct. It is good for non-English native speaker like us to understand.

There is many STUDENTS studying English at Dalian....

Back to the topic, I am digesting your knowledge of PermissionChecker, now.
Thanks for the info. A summary description of the following property would be a helpful compliment to this article:

permissions.user.check.algorithm
An explanation of the permission algorithms can be found in the administrator's guide:

liferay-4-administration-guide.pdf

The guide also covers other important security concerns.
more on liferay permissions
http://liferaydemystified.blogspot.com/search/label/Liferay%20Permissions
"A PermissionChecker is created or borrowed from a pool and placed in the thread local and themeDisplay object on every request."

Who/which method places the PermissionChecker in thread local or themeDisplay?
Great article helps to get a better understanding of how permissions are checked...

Have there been big changes to the newer versions?
Especially:
First is the PermissionCheckerBag already cached and if how often do it refresh?
Second is there any information on PermissionCacheUtil class (how to use it)?
Hi Joseph,

really good article in particular because it gives a "Liferay Internal" view that can help to undertand in deep. I'm wondering if Liferay can manage hirarchical roles and related permission assigments (enhancing the RBAC model to manage hierarchical roles)
(e.g.)

1) IT_ROLE (Role for EN users and related permissions)
1.1) IT_ADMIN_ROLE (inherit from parent and add specific permission)
1.1.1) IT_SUPERADMIN_ROLE (inherit from parent and add specific permission)

Actually an user can inherith roles by group or organization assigment but permission (action and resource) assigment can be done only by User <->Role relation (as far as I know roles are not hierarchical).

I thikn it could be useful an improvement to to support Hierachical roles.

WDYT ?

Bye,
Denis.
Hi Joe,

I have some basic question about permissions and hopefully you could help me.

Details :
Users - user-one, user-two :
Associated roles : user-one member of role-one (user-one->role-one) and user-two member of role-two (user-two->role-two)

Categories in Message Board: CAT_ONE, CAT_TWO
Assigned Roles : CAT_ONE all the permissions assigned to owner (admin) and role-one.
CAT_TWO all the permissions assigned to owner(admin) and role-two.

ThemeDisplay themeDisplay = (ThemeDisplay)request.getAttribute(WebKeys.THEME_DISPLAY);
long scopeGroupId = themeDisplay.getScopeGroupId();
long groupThreadUserId = themeDisplay.getUserId();

PermissionChecker permissionChecker = themeDisplay.getPermissionChecker();

List<MBCategory> mbCategories = MBCategoryLocalServiceUtil.getCategories(scopeGroupId);

for(MBCategory mbCategory : mbCategories){

boolean hasPerm = permissionChecker.hasPermission(scopeGroupId, MBCategory.class.getName(), mbCategory.getCategoryId(), ActionKeys.VIEW);

System.out.println("****mb category name : ****\t" + mbCategory.getName() "\t **** hasPerm *** \t" + hasPerm);
}

OUTPUT : ****mb category name : **** CAT _ONE **** hasPerm *** true
****mb category name : **** CAT _TWO **** hasPerm *** true

I am not sure, what I am missing here, all I wanted to see is if the logged in user (member of above mentioned one of the role ) does not have permission on a category, I do not want to display that category. But in this case, hasPermission method always returning TRUE (:
Hello,
I must be too dumb, but I (or furthermore idea) can't find com.liferay.portal.security.permission.PermissionCheckerImpl in any jars that are provided with the liferay 6.1.2 download. Where do I find this class?