Public bulletin boards are great. Anyone can inform others of just about anything. On the other hand, anyone can post just about anything on the bulletin board. Some of this content might not be relevant to the community. Other content might be inappropriate. Thus, you sometimes need a way to restrict who can post or access content.
Fortunately, no matter what your portlet does, access to it and to its content can be controlled with permissions. Read on to learn about Liferay’s permissions system and how to add permissions to your application.
Liferay’s Permission System
Liferay’s permission system uses a flexible mechanism that defines the actions that a given user can perform within the context of Liferay or a specific application. Liferay developers break down the operations that can be performed in Liferay or in a certain application into distinct actions. The act of granting the ability to perform an action to a specific role is the act of granting a permission. In Liferay, permissions are not granted to directly to users. Instead, permissions are granted to roles. Roles, in turn, can be assigned to specific users, sites, organizations, or user groups.
Developers need to define the different types of operations that are required to suit the business logic of their applications. They don’t need to worry about which users will receive which permissions. Once the actions have been determined and configured, portal administrators can grant permissions to perform those actions to users, sites, organizations, or user groups by assigning roles. Administrators can use the portal’s administration tools to grant permissions to roles or they can use the permissions UIs of individual portlets.
In this tutorial, you’ll learn how to use Liferay’s permissions system to provide Liferay administrators the same level of control over permissions that they have over the out-of-the-box Liferay applications.
Before proceeding, make sure you understand these critical terms:
Action: An operation that can be performed by a Liferay user. For example,
actions that be performed on the Bookmarks application include ADD_TO_PAGE,
CONFIGURATION, and VIEW. Actions that can be performed with respect to
Bookmarks entry entity include ADD_ENTRY, DELETE, PERMISSIONS, UPDATE,
and VIEW.
Resource: A generic representation of any application or entity in the
portal on which an action can be performed. Resources are used for permission
checking. For example, resources within a Liferay instance could include the
RSS application with instance ID hF5f, a globally scoped Wiki page, a
Bookmarks entry of the site X, and a Message Boards post with the ID 5052.
Permission: An action that can be performed on a resource. In Liferay’s
database, resources and actions are saved in pairs. (Each entry in the
ResourceAction table contains both the name of a portlet or entity and the
name of an action.) For example, the VIEW action with respect to viewing the
Bookmarks application is associated with the
com_liferay_bookmarks_web_portlet_BookmarksPortlet portlet ID. The VIEW
actions with respect to viewing a Bookmarks Folder or viewing a Bookmarks
entry are associated with the com.liferay.bookmarks.model.BookmarksFolder
and com.liferay.bookmarks.model.BookmarksEntry entities, respectively.
There are two kinds of resources in Liferay: portlet resources and model
resources. Portlet resources represent portlet applications. The names of
portlet resources typically correspond to the IDs of the portlets themselves.
For example, the fully qualified name of the Bookmarks portlet class is
com.liferay.bookmarks.web.portlet.BookmarksPortlet. Its ID is defined in the BookmarksPortletKeys class like this:
public static final String BOOKMARKS =
"com_liferay_bookmarks_web_portlet_BookmarksPortlet";
This BOOKMARKS string is used when declaring portlet resources in
default.xml files, as discussed below.
There are two kinds of resources in Liferay: portlet resources and model
resources. Portlet resources represent portlets. The names of portlet
resources are the portlet IDs from the portlets’ portlet.xml files (or in the
case of core portlets, Liferay’s portlet-custom.xml). Model resources
refer to entities within Liferay. The names of model resources are the fully
qualified class names of the entities they represent. In the XML displayed
below, permission implementations are first defined for the portlet resource
and then for the model resources.
Model resources represent entities within Liferay, such as bookmarks folders or
bookmarks entries. The names of model resources are the fully qualified class
names of the entities they represent. In the default.xml files displayed
below, permission implementations are first defined for the portlet resource
and then for the model resources.
You can add permissions to your custom portlets using four easy steps (also known as DRAC):
-
Define all resources and their permissions.
-
Register all defined resources in the permissions system. This is also known as adding resources.
-
Associate the necessary permissions with resources.
-
Check permission before returning resources.
Define All Resources and Permissions
Here you’ll learn the first step, in which you define your resources and their
actions. The Bookmarks application is used here to demonstrate how to define
portlet resources and model resources. Open the default.xml file in
bookmarks-web module of the Bookmarks application:
default.xml.
There, you’ll see the following mapping of resources to actions:
<?xml version="1.0"?>
<!DOCTYPE resource-action-mapping PUBLIC "-//Liferay//DTD Resource Action Mapping 7.0.0//EN" "http://www.liferay.com/dtd/liferay-resource-action-mapping_7_0_0.dtd">
<resource-action-mapping>
<portlet-resource>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksAdminPortlet</portlet-name>
<permissions>
<supports>
<action-key>ACCESS_IN_CONTROL_PANEL</action-key>
<action-key>CONFIGURATION</action-key>
<action-key>VIEW</action-key>
</supports>
<site-member-defaults>
<action-key>VIEW</action-key>
</site-member-defaults>
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
<guest-unsupported>
<action-key>ACCESS_IN_CONTROL_PANEL</action-key>
<action-key>CONFIGURATION</action-key>
</guest-unsupported>
</permissions>
</portlet-resource>
<portlet-resource>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksPortlet</portlet-name>
<permissions>
<supports>
<action-key>ADD_TO_PAGE</action-key>
<action-key>CONFIGURATION</action-key>
<action-key>VIEW</action-key>
</supports>
<site-member-defaults>
<action-key>VIEW</action-key>
</site-member-defaults>
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
<guest-unsupported>
<action-key>CONFIGURATION</action-key>
</guest-unsupported>
</permissions>
</portlet-resource>
</resource-action-mapping>
This default.xml defines portlet resources. The bookmarks service module also
contains a
default.xml
file:
<?xml version="1.0"?>
<!DOCTYPE resource-action-mapping PUBLIC "-//Liferay//DTD Resource Action Mapping 7.0.0//EN" "http://www.liferay.com/dtd/liferay-resource-action-mapping_7_0_0.dtd">
<resource-action-mapping>
<model-resource>
<model-name>com.liferay.bookmarks</model-name>
<portlet-ref>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksPortlet</portlet-name>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksAdminPortlet</portlet-name>
</portlet-ref>
<root>true</root>
<weight>1</weight>
<permissions>
<supports>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_FOLDER</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>VIEW</action-key>
</supports>
<site-member-defaults>
<action-key>ADD_ENTRY</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>VIEW</action-key>
</site-member-defaults>
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
<guest-unsupported>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_FOLDER</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
</guest-unsupported>
</permissions>
</model-resource>
<model-resource>
<model-name>com.liferay.bookmarks.model.BookmarksFolder</model-name>
<portlet-ref>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksPortlet</portlet-name>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksAdminPortlet</portlet-name>
</portlet-ref>
<weight>2</weight>
<permissions>
<supports>
<action-key>ACCESS</action-key>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_SUBFOLDER</action-key>
<action-key>DELETE</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>UPDATE</action-key>
<action-key>VIEW</action-key>
</supports>
<site-member-defaults>
<action-key>ADD_ENTRY</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>VIEW</action-key>
</site-member-defaults>
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
<guest-unsupported>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_SUBFOLDER</action-key>
<action-key>UPDATE</action-key>
</guest-unsupported>
</permissions>
</model-resource>
<model-resource>
<model-name>com.liferay.bookmarks.model.BookmarksEntry</model-name>
<portlet-ref>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksPortlet</portlet-name>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksAdminPortlet</portlet-name>
</portlet-ref>
<weight>3</weight>
<permissions>
<supports>
<action-key>DELETE</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>UPDATE</action-key>
<action-key>VIEW</action-key>
</supports>
<site-member-defaults>
<action-key>SUBSCRIBE</action-key>
<action-key>VIEW</action-key>
</site-member-defaults>
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
<guest-unsupported>
<action-key>SUBSCRIBE</action-key>
<action-key>UPDATE</action-key>
</guest-unsupported>
</permissions>
</model-resource>
</resource-action-mapping>
This default.xml file defines model resources.
The <portlet-resource> tag is used to define actions that can be taken with
respect to the portlet window. For the Bookmarks application, such actions
include these:
ADD_TO_PAGE: Add the application to a pageCONFIGURATION: Access the application’s Configuration windowVIEW: View the application
All the supported actions are defined in the <supports> tag, a sub-tag of
the <permissions> tag (which is itself a sub-tag of the <portlet-resource>
tag:
<supports>
<action-key>ADD_TO_PAGE</action-key>
<action-key>CONFIGURATION</action-key>
<action-key>VIEW</action-key>
</supports>
The default permissions for site members are defined in the
<site-member-defaults> tag. In the case of the Bookmarks application, site
members can view any Bookmarks application in the site:
<site-member-defaults>
<action-key>VIEW</action-key>
</site-member-defaults>
Similarly, the default permissions for guests are defined in the
<guest-defaults> tag. Guests can also view any Bookmarks application in the
site:
<guest-defaults>
<action-key>VIEW</action-key>
</guest-defaults>
The <guest-unsupported> tag specifies permissions forbidden to guests. By
default, guests cannot access the Bookmarks application in the Control Panel
nor can they access the Bookmarks’s configuration window:
<guest-unsupported>
<action-key>ACCESS_IN_CONTROL_PANEL</action-key>
<action-key>CONFIGURATION</action-key>
</guest-unsupported>
With respect to model resources, guests are forbidden from adding bookmarks
entries and bookmarks folders. Guests are also not permitted to edit
permissions or subscribe. Remember, these are just default permissions that can
be changed by administrators. See the following entry in the first
<model-resource> tag:
<guest-unsupported>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_FOLDER</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
</guest-unsupported>
The <model-resource> tag is used to define actions that can be performed with
respect to models, also known as entities. There are two kinds of actions in
Liferay: top-level actions and resource actions. Top-level actions are not
applied to a particular resource. For example, the action of adding a new
entity is not applied to a particular resource, so it’s considered a top-level
action. The first <model-resource> tag defines adding bookmark entry and
bookmark folder resources as top-level actions:
<supports>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_FOLDER</action-key>
</supports>
The second and third <model-resource> tags define resource actions that can
be applied to the BookmarksFolder and BookmarksEntry entities,
respectively. For example, the permissions for the following actions are
defined with respect to the resource associated with the BookmarksEntry entity:
<supports>
<action-key>DELETE</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>UPDATE</action-key>
<action-key>VIEW</action-key>
</supports>
Similarly, the permissions for the following actions are defined with respect to
the resource associated with the BookmarksFolder entity:
<supports>
<action-key>ACCESS</action-key>
<action-key>ADD_ENTRY</action-key>
<action-key>ADD_SUBFOLDER</action-key>
<action-key>DELETE</action-key>
<action-key>PERMISSIONS</action-key>
<action-key>SUBSCRIBE</action-key>
<action-key>UPDATE</action-key>
<action-key>VIEW</action-key>
</supports>
In each <model-resource> tag, notice that the model name must be defined. The
<model-name> must be either the fully-qualified name of a package or of an
entity class. For example, com.liferay.bookmarks is the name of a package and
com.liferay.bookmarks.model.BookmarksEntry is the name of an entity class.
Using a package is the recommended convention for permissions that refer to
top-level actions:
<model-name>com.liferay.bookmarks</model-name>
The ADD_ENTRY and ADD_FOLDER permissions are defined this way since they’re
top-level actions. For resource actions, the entity class is specified:
<model-name>com.liferay.bookmarks.model.BookmarksEntry</model-name>
The <portlet-ref> element comes next and contains a <portlet-name> sub-tag.
<portlet-ref>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksPortlet</portlet-name>
<portlet-name>com_liferay_bookmarks_web_portlet_BookmarksAdminPortlet</portlet-name>
</portlet-ref>
The value of <portlet-name> references the name of the portlet to which the
model resource belongs. It’s possible for a model resource to belong to
multiple portlets referenced with multiple <portlet-name> elements. This is
the case here since both the Bookmarks application and the Bookmarks Admin
application can be used to perform actions on bookmark entries.
The <supports>, <site-member-defaults>, <guest-defaults>, and
<guest-unsupported> tags work the same way in the <model-resource> tag as
they do in the <portlet-resource> tag. The <supports> tag lets you specify a
list of supported actions that require permission to perform. The
<site-member-defaults> tag and the <guest-defaults> tags define default
permissions for site members and guests, respectively. And the
<guest-unsupported> tag specifies permissions forbidden to guests.
After defining resource permissions for your portlet, you need to point Liferay
to the default.xml file that contains your definitions. In Liferay’s core,
there are multiple permissions XML definition files for various core Liferay
portlets in the portal/portal-impl/src/resource-actions directory. The
default.xml file in that folder contains pointers to the definition files of
the various applications. This excerpt from Liferay’s default.xml references
the resource permission definition files for all built-in Liferay portlets:
<?xml version="1.0"?>
<!DOCTYPE resource-action-mapping PUBLIC "-//Liferay//DTD Resource Action Mapping 7.0.0//EN" "http://www.liferay.com/dtd/liferay-resource-action-mapping_7_0_0.dtd">
<resource-action-mapping>
<resource file="resource-actions/portal.xml" />
<resource file="resource-actions/announcements.xml" />
<resource file="resource-actions/asset.xml" />
<resource file="resource-actions/blogs.xml" />
...
</resource-action-mapping>
Your application’s permissions XML file should be named default.xml and
should be placed in a directory in your module’s classpath.
src/resource-actions is the standard location. Once your project’s
default.xml file has been created, you should create a properties file named
portlet.properties that contains a reference to your permissions XML file. In
your portlet.properties file, create a property named
resource.actions.configs with the relative path to your portlet’s
resource-action mapping file (e.g. default.xml) as its value. Here’s what
this property specification might look like:
resource.actions.configs=resource-actions/default.xml
Your permissions XML file must contain a root resource-action-mapping element.
Check out a copy of the Liferay source code from the
Liferay Portal repository
to see how resources and permissions are defined for core Liferay portlets.
Start by looking at the definition files found in the
portal-impl/src/resource-actions directory. For a simple example of defining
permissions in the context of a portlet plugin, check out the
Liferay Plugins repository
and examine the portlet sample-permissions-portlet.