Securing Portal Contents

Ken Finnigan

January 2013

(For more resources related to this topic, see here.)


This article discusses the configurations aimed at providing security features to portals and all the related components. We will see that we can work using either the web console or the XML configuration files. As you would expect, the latter is more flexible in most instances.

Many of the configuration snippets shown in the article are based on Enterprise Deployment Descriptors (DD). Keep in mind that XML always remains the best option for configuring a product. We will configure GateIn in different ways to show how to adapt some of the internal components for your needs.

Enterprise Deployment Descriptors (DD) are configuration files related to an enterprise application component that must be deployed in an application server.

The goal of the deployment descriptor is to define how a component must be deployed in the container, configuring the state of the application and its internal components.

These configuration files were introduced in the Java Enterprise Platform to manage the deployment of Java Enterprise components such as Web Applications, Enterprise Java Beans, Web Services, and so on.

Typically, for each specific container, you have a different definition of the descriptor depending on vendors and standard specifications.

Typically, a portal consists of pages related to a public section and a private section. Depending on the purpose, of course, we can also work with a completely private portal.

The two main mechanisms used in any user-based application are the following:

  • Authentication
  • Authorization

In this article we will discuss authorization: how to configure and manage permissions for all the objects involved in the portal. As an example, a User is a member of a Group, which provides him with some authorizations. These authorizations are the things that members of the Groups can do in the portal.

On the other side, as an example, a page is defined with some permissions, which says which Groups can access it. Now, we are going to see how to configure and manage these permissions, for the pages, components in a page, and so on in the portal.

Securing portals

The authorization model of the portal is based on the association between the following actors: groups, memberships, users, and any content inside the portal (pages, categories, or portlets).

In this recipe, we will assign the admin role against a set of pages under a specific URL of the portal. This configuration can be found in the default portal provided with GateIn so you can take the complete code from there.

Getting ready

Locate the web.xml file inside your portal application.

How to do it...

We need to configure the web.xml file assigning the admin role to the following pages under the URL http://localhost:8080/portal/admin/* in the following way:

<security-constraint> <web-resource-collection> <web-resource-name> admin authentication </web-resource-name> <url-pattern>/admin/*</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint>

The role must be declared in a different section under the security-constraint tag through the security-role tag. The role-name tag defines the id of the role:

<security-role> <description>the admin role</description> <role-name>admin</role-name> </security-role>

How it works...

GateIn allows you to add different roles for every sections of the portal simply by adding a path expression that can include a set of sub-pages using wildcard notation (/*).

This is done by first defining all the needed roles using the security-role element, and then defining a security-constraint element for each set of pages that you want to involve.

PicketLink is also for users and memberships, and can manage the organization of the groups.

There's more...

Configuring GateIn with JAAS

GateIn uses JAAS (Java Authentication Authorization Service) as the security model.

JAAS (Java Authentication Authorization Service) is the most common framework used in the Java world to manage authentication and authorization. The goal of this framework is to separate the responsibility of users' permissions from the Java application. In this way, you can have a bridge for permissions management between your application and the security provider.

For more information about JAAS, please see the following URL:

Java EE Application servers and JSP/servlet containers, such as JBoss and Tomcat, also support JAAS with specific deployment descriptors.

The default JAAS module implemented in GateIn synchronizes the users and roles from the database. In order to add your portal to a specific realm, add the following snippet in web.xml:

<login-config> . . . <realm-name>gatein-domain</realm-name> . . . </login-config>

Notice that a realm can be managed by JAAS or another authorization framework—it is not important which is used for the Java Enterprise Edition.

gatein-domain is the ID of the default GateIn domain that we will use as the default reference for the following recipes.

See also

  • The Securing with JBoss AS recipe

  • The Securing with Tomcat recipe

Securing with JBoss AS

In this recipe, we will configure GateIn with JAAS using JBoss AS (5.x and 6.x).

Getting ready

Locate the WEB-INF folder inside your portal application.

How to do it...

Create a new file named jboss-web.xml in the WEB-INF folder with the following content:

<jboss-web> <security-domain> java:/jaas/gatein-domain </security-domain> </jboss-web>

How it works...

This is the JNDI URL where the JAAS module will be referenced. This URL will automatically search the JAAS modules called gatein-domain.

The configuration of the modules can be found inside the file gatein-jboss-beans.xml. Usually, this file is inside the deployed <PORTAL_WAR_ROOT>/META-INF, but it could be placed anywhere inside the deploy directory of JBoss, thanks to the auto-discovery feature provided by the JBoss AS.

Here is an example:

<deployment xmlns="urn:jboss:bean-deployer:2.0"> <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-domain"> <authentication> <login-module code= "" flag="optional"> <module-option name="portalContainerName"> portal </module-option> <module-option name="realmName"> gatein-domain </module-option> </login-module> <login-module code= "" flag="required"> ……….. </application-policy> </deployment>

JAAS allows adding several login modules, which will be executed in cascade mode according to the flag attribute. The following represents a description of the valid values for the flag attribute and their respective semantics as mentioned in the Java standard API:

  • Required: The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed to the next LoginModule in the list.

  • Requisite: The LoginModule is required to succeed. If it succeeds, authentication continues on the next LoginModule in the list. If it fails, the control immediately returns to the application and the authentication process does not proceed to the next LoginModule.

  • Sufficient: The LoginModule is not required to succeed. If it does succeed, the control immediately returns to the application and the authentication process does not proceed to the next LoginModule. If it fails, authentication continues forward to the next LoginModule

  • Optional: The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed to the next LoginModule.

Look at the recipe Choosing the JAAS modules for details about each login module.

See also

  • The Securing portals recipe

  • The Securing with Tomcat recipe

  • The Choosing the JAAS modules recipe

Securing with Tomcat

In this recipe, we will configure a JAAS realm using Tomcat 6.x.x/7.x.x.

Getting ready

Locate the declaration of the realm inside <PORTAL_WAR_ROOT>/META-INF/context.xml.

How to do it…

  • Change the default configuration for your needs, as described in the previous recipe. The default configuration is the following:

    <Context path='/portal' docBase='portal' debug='0' reloadable='true' crossContext='true' privileged='true'> <Realm className= 'org.apache.catalina.realm.JAASRealm' appName='gatein-domain' userClassNames= '' roleClassNames= '' debug='0' cache='false'/> <Valve className= 'org.apache.catalina.authenticator.FormAuthenticator' characterEncoding='UTF-8'/> </Context> ;

  • Change the default configuration of the JAAS domain that is defined in the TOMCAT_ HOME/conf/jaas.conf file. Here is the default configuration:

    <gatein-domain { optional; required; required; };

How it works…

As we have seen in the previous recipe, we can configure the modules in Tomcat using a different configuration file. This means that we can change and add login modules that are related to a specific JAAS realm.

The context.xml file is stored inside the web application. If you don't want to modify this file, you can add a new file called portal.xml in the conf folder to override the current configuration.

See also

  • The Security with JBoss AS recipe

  • The Choosing the JAAS modules recipe

Choosing the JAAS modules

In this recipe, we will see the available JAAS modules provided by GateIn and how to customize them. They are based on a simple approach, so if you are in a particular environment, you may need to create a new module or extend one of them, which is easy to do.

Getting ready

We are going to choose one of the available modules for JAAS:

  • Locate the login modules file at the following path: gatein.ear/META-INF/ gatein-jboss-beans.xml

  • Locate the JAAS configuration file in your application server. See the previous two recipes Securing with JBoss AS and Securing with Tomcat for the locations of the JAAS configuration files

How to do it…

Depending on your security requirements, you can choose the login modules required for your architecture.

How it works…

The complete list of all the JAAS modules provided by GateIn is as follows:

  • A standard wrapper module used between Tomcat, JBoss, and Jetty. It's the default first module.

  • Dedicated to refresh the current authentication session. It can be used on cluster environment.

  • Keeps user credentials in the cache to avoid reauthentication requests when the session is closed.

  • This is a simple generic login module compliant with all application servers.

  • Stores the identity for the logged user in the default registry.

  • Adapts to the login and logout operations on JBoss. It always must be used as last module in the JBoss authentication chain.

  • This is the base module for Jetty.

  • This is the base module for Tomcat.

  • DigestAuthenticationJbossLoginModule: The JBoss module for digest authentication.

  • DigestAuthenticationJettyLoginModule: The Jetty module for digest authentication.

  • DigestAuthenticationTomcatLoginModule: The Tomcat module for digest authentication.

  • CustomMembershipLoginModule: This login module can be used to add authenticated user to some group after a successful login. For example, a user can be added as member to the group /platform/users after the login process. Group name and Membership type are configurable, and if they are not provided by the configuration, then the value member is used as the default value for membership type and /platform/users for group

This list describes minimally the function of the modules. If you need more details about the modules, you should consult the GateIn reference guide available at: US/html/

All these modules use the Organization Service internally used by GateIn to manage users, groups, and membership information. The unique exception is WCILoginModule, which is a wrapper dedicated to provide wide compatibility for application servers.

There's more…

In order to implement your own JAAS module, you should take a look at the source code and use your preferred Java IDE. The concrete class must extend the following Java interface:

All the methods of this interface that you need to extend are:

Public interface LoginModule { public abstract void initialize( arg0, arg1, java.util.Map arg2, java.util.Map arg3 ); public abstract boolean login(); public abstract boolean commit(); public abstract boolean logout(); public abstract boolean abort(); }

Once you create your own module implementation, you only need to add it to the module's configuration file. See the previous two recipes Securing with JBoss AS and Securing with Tomcat for the locations of the JAAS configuration files

See also

  • The Securing portals recipe

  • The Security with Tomcat recipe

  • The Security with JBoss AS recipe

Creating a login page

In this recipe, we will configure a login page for a new portal.

Getting ready

To complete this task, we need to have some knowledge of the following technologies

  • Servlets/JSPs

  • JAAS

  • GateIn, as many Java products use JAAS for authentication management, JSPs for the login forms, and servlets for operations such as login, logout, remind me, change password, and so on.

How to do it…

  1. In the web.xml of the main GateIn web application, add the code:

    <login-config> <auth-method>FORM</auth-method> <realm-name>gatein-domain</realm-name> <form-login-config> <form-login-page>/initiatelogin</form-login-page> <form-error-page>/errorlogin</form-error-page> </form-login-config> </login-config>

  2. Add a JSP inside the portal root with this path:

    login ---jsp -----login.jsp

A simple login.jsp can be written using the default JAAS variables as:

<form method="POST" action="j_security_check"> Login:<input type="text" name="j_username"><br/> Password:<input type="password" name="j_password"><br/> <input type submit="Login"/> </form>

The web container will search the current JAAS module and will know where to redirect the log in action.

How it works…

This authentication system is implemented through an HTML form connected to the domain, gatein-domain, and two paths for the login page and error page that reference the internal servlets, org.exoplatform.web.login.InitiateLoginServlet and org. exoplatform.web.login.ErrorLoginServlet. These servlets call a controller, the WCI Controller, which by default reads the pages inside the login/jsp directory.

The goal of the WCI Controller is simply to allow the compatibility between the application servers guaranteed by GateIn, meaning fewer problems in a migration.

There's more...

A more complete login.jsp page can be seen in the main portal under the path seen above, so we will not explore the details.

Instead of the j_security_check, we can use a custom action in the form provided by the eXo team that calls the servlet PortalLoginController. It adds the feature for the "remember me". Here is an example of the configuration of the servlet in the web.xml file:

<servlet> <servlet-name>PortalLoginController</servlet-name> <servlet-class> PortalLoginController</servlet-class> </servlet> … <servlet-mapping> <servlet-name>PortalLoginController</servlet-name> <url-pattern>/login</url-pattern> </servlet-mapping>

Here is an example of login.jsp using this servlet:

<form name="loginForm" action="<%= request.getContextPath()+ "/ login"%>" method="post" style="margin: 0px;"> … add the jaas fields seen before for the username and password <input type="checkbox" name="rememberme" value="true"/> </form>

Synchronizing users

Through WEBUI, we can configure initializers that register the default users.

Getting ready

Simply add in the XML file /WEB-INF/conf/organization/organizationconfiguration.xml, the users, roles, and membership types to pre-charge.

How to do it...

Use the following code to add, for example, the root user:

<object type= "$User"> <field name="userName"> <string>root</string></field> <field name="password"> <string>gtn</string></field> <field name="firstName"> <string>Root</string></field> <field name="lastName"> <string>Root</string></field> <field name="email"> <string>root@localhost</string></field> <field name="groups"> <string> manager:/platform/administrators,member:/platform/users, member:/organization/management/executiveboard </string> </field> </object>

The membership type for the root user:

<object type=" $MembershipType"> <field name="type"> <string>manager</string></field> <field name="description"> <string>manager membership type</string></field> </object>

And the group called administrators for the root user:

<object type=" OrganizationConfig$Group"> <field name="name"> <string>administrators</string></field> <field name="parentId"> <string>/platform</string></field> <field name="description"> <string>the /platform/administrators group</string> </field> <field name="label"> <string>Administrators</string></field> </object>

Notice some details in this snippet are related to the tree structure of the group; the parentId field represents the name field of an other group to insert in the XML.

How it works...

GateIn provides one class to import users, membership types, and groups in the database:

Through this service, we can add permissions available for the portal. The identity objects will be inserted in the database at the first start of the portal.

Securing pages

In this recipe, we will see how to set access permissions on a single page. As for the portals, we can configure those through the web console and XML.

Getting ready

Start Gatein and connect through a browser to the web console. Enter in the portal root application to see the XML files.

How to do it...

  1. On the web console, select one page, for example Application Registry:

  2. Now edit the page by clicking on the Edit Page link.

  3. Click on the View Page properties button in the Page Editor box as shown in the following screenshot:

  4. Here we can choose the permissions:

    By using XML, we can open the file of the portal configuration where the dashboard page is configured, inside gatein.ear/02portal.war/WEB-INF/conf/portal/group/ organization/management/executive-board/pages.xml. Here is the configuration:

<page> <name>management</name> ... <access-permissions> *:/organization/management/executive-board </access-permissions> <edit-permission> *:/organization/management/executive-board </edit-permission> ... </page>

How it works...

Who receives the information of the access on the page and coordinates it? JCR is the key. Everything is registered in the JCR repository. See the How it works... section of the Securing categories recipe to learn more about this.

Securing categories

Categories are used by GateIn to categorize applications, meaning that, we can search an application in a simple manner because the applications are ordered. These categories can be secured too.

Getting ready

We will test the security with the two applications Application Registry Portlet and WSRP Portlet. The first can be found via the web console inside Administration/ Application Registry. The second is inside the Application Registry portlet or in the box of applications visible in any page in edit mode, assuming you have the correct permissions.

How to do it...

  1. To secure the categories, access via the browser the portal as administrator and click on Application Registry:

    This is the Application Registry Portlet:

  2. Click on the Edit Category button to see the window with the permissions:

    Here you can make changes according to your needs. The available categories for a user or group can be seen inside the Management box. For example, going to the Group Editor on the voice Edit Page panel with demo user you will see only the categories Dashboard and Gadgets:

If we set an authorized permission on the portlet, but we do not have permissions on the category, the portlet will not be shown unless we set a different available category to the portlet. Now we will see how to put the WSRP Portlet in the Dashboard category.

  1. Login as the administrator user and go to the Portlet Registry as seen before and click on the + button:

  2. Select the WSRP portlet and click on the Add button:

  3. Re-login as a demo user to see the new portlet in the Edit Page Panel:

The WSRP Portlet is available for the demo user because he/she has the necessary privileges to see it. Otherwise, it will not be shown.

The category permissions are also configurable through WEBUI in the file gatein. ear/02portal.war/WEB-INF/conf/portal/application-registryconfiguration. xml inside the ApplicationCategoriesPlugins component Plugin of the ApplicationRegistryService component:

<object type="org.exoplatform.application.registry. ApplicationCategory"> ... <field name="accessPermissions"> <collection type="java.util.ArrayList" item-type="java.lang.String"> <value> <string>*:/platform/administrators</string> </value> <value> <string>*:/organization/management/executive-board</string> </value> </collection> </field> ... </object>

Edit permissions are useless in category management. Also, the relationships of the portlets are configurable in this component:

<object type="org.exoplatform.application.registry. ApplicationCategory"> …… <field name="applications"> <collection type="java.util.ArrayList"> <value> <object type= "org.exoplatform.application.registry.Application"> <field name="applicationName"> <string> ApplicationRegistryPortlet</string> </field> ……. </field> </object>

As the portal allows you to change manually everything on the web console, these XML configurations only kick in on the first boot when the database is clean, otherwise you would risk an override of the manual configurations at each restart.

Notice that WEBUI does not have the concept of portlets. WEBUI calls the portlets as applications. This allows you to manage other components like the portlet, such as gadgets.

How it works...

The categories, applications, and pages are components based on JCR. JCR allows for an easy way of development and maintenance of these contents because all the metadata is registered. For example, we can query a JCR node in any part of the portal and we can take each little piece of information about content.

GateIn uses Chromattic to access JCR and eXo JCR as the JCR repository. The details of Chromattic can be seen here: The details for eXo JCR are available at the following URL:

Securing applications

In this recipe, we will talk about applications as a set of portlets and gadgets, and we will see how to secure them.

Getting ready

We need the Application Registry Portlet to start. See the previous recipe to find out how to use it.

How to do it...

As for the categories, the permissions of the applications can be managed through Application Registry. They can be configured graphically, as for the categories, and through XML. Here is the configuration of the Account Portlet:

<object type="org.exoplatform.application.registry.Application"> <field name="applicationName"> <string>AccountPortlet</string> </field> …….. <field name="accessPermissions"> <collection type="java.util.ArrayList" item-type="java.lang. String"> <value> <string>*:/platform/administrators</string> </value> <value> <string>*:/organization/management/executive-board</string> </value> </collection> </field> ……… </object>

As the application is not used only for administration, we can set the access for the instance. For example, we could get more applications of the same type in a portal. Doing this through the web console is very simple.

  1. Select a page and click on Edit Page:

  2. Select the body of the application. A tool row will appear at the top-left corner, as shown in the following screenshot:

  3. Click on the pencil icon to edit the application and go to the permission panel. In this panel, we can set the required permissions.

The Application Registry seen before automatically injects the default permissions. Here we can change the permissions for this page. For example, we can get a public page with two applications, one visible only by one group and another by another group depending upon the login.

How it works…

As for the categories, the pages are imported from eXo JCR through Chromattic. All permissions are content metadata in GateIn. We can access Chromattic anywhere (groovy scripts, portlets, POJO) and get the information that we need if we have the correct permissions.

As for the categories, there is no difference between the Edit and Access permissions. The access permissions are read by pages and toolboxes. If a toolbox cannot access an application, it means that the toolbox has no edit permission for that application.

Securing portlets

Now let us see how to secure a new portlet that uses only standard configurations.

Getting ready

In this recipe, we will access these Java Web Technologies:

  • JSP/Servlet

  • Portlet 286

  • WebUI

How to do it…

This is the structure of a simple project working with portlets

The web.xml file contains only an empty web-app tag to allow the deployment of the application.

Here is the welcome.jsp:

<%@ taglib uri="" prefix="portlet"%> <portlet:defineObjects /> <div class="portlet-section-header"> | <%=renderRequest.isUserInRole("users")%> | <%=renderRequest.isUserInRole("administrators")%> </div>

Add the following roles in the portlet.xml file and deploy the application:

<security-role-ref> <role-name>administrators</role-name> <role-link>administrators</role-link> </security-role-ref> <security-role-ref> <role-name>users</role-name> <role-link>users</role-link> </security-role-ref>

If we add the new portlet in a page when we login as a root user, the portlet will show the following result:

How it works...

What does it mean? It means that the developer is now ready to work with the permissions. The role names configured in the portlet, administrators, and users are mapped automatically in GateIn as the roles: /platform/administrators and /platform/users. The same thing can be done for any group name; the important thing is that the group exists inside the /platform folder in any level.

There's more...

If we don't want to use the /platform folder for our groups, we can use the root folder (/) and add as first node the group of interest. For example, for the group /organization/ management/executive-board, you need to use the role organization in your portlet.

If we don't want to use this, either, we need to extend the Role Extractor Component. This component is used to extract the roles of the portal to use for Java standard operations, for example, JAAS authorization. Here the extension is to add in a configuration.xml file (for example the idm-configuration.xml):

<component> <key> </key> <type> </type> <init-params> <value-param> <name></name> <description>authentication service use this value to authenticate</description> <value>platform</value> </value-param> </init-params> </component>

Put the desired value instead of platform.

However, remember that the platform folder contains the administrators, guests, and common users, so before you do it, it is mandatory to create new groups and users associations with the new group folder. Make sure that you do this!

When we deploy the portlet, it is configured as public in the Application Registry:

If we don't want a public portlet, we can simply unflag the public option and configure the permissions through the web console.


In this Article, we have discussed Securing portals, configuring GateIn with JAAS using JBoss & TomCat. We also discussed the available JAAS modules and how to customize them. Configuring a login page for a new portal and configuring initializers that register the default users have also been discussed in this article. Topics like accessing Java Web technologies were also discussed in this article.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

GateIn Cookbook

Explore Title