User Security and Access Control in JBoss portals

Create dynamic, feature-rich, and robust enterprise portal applications


Authentication in JBoss portal builds on the JEE security provided by the JBoss server. The JEE specification defines the roles and constraints under which certain URLs and components are protected. However, this might not always be sufficient for building enterprise applications or portals. Application server providers such as JBoss supplement the authentication and authorization features provided by the JEE specification with additional features such as role-to-group mapping and session logout.

Authentication in JBoss portal can be divided into configuration files and portal server configuration.

The jboss-portal.sar/portal-server.war file is the portal deployment on the JBoss application server. Assuming that the portal server is like any JEE application deployed on an application server, all user authentication configurations go into the WEB-INF/web.xml and the WEB-INF/jboss-web.xml files.

  1. The WEB-INF/web.xml entry defines the authentication mode, with the default being form-based authentication. This file is also used to define the login and error pages, as defined by the JEE specification.
  2. The default security domain defined by the JBoss application server is java:/jaas/portal for JBoss portal. The security domain maps the JEE security constructs to the operational domain. This is defined in a proprietary file, WEB-INF/jboss-web.xml. The portal security domain authentication stack is defined in the jboss-portal.sar/conf/login-config.xml file, and is deployed along with the portal. Login-config.xml houses the JAAS modules for authentication. Custom modules can be written and added here to support special scenarios. The server provides a defined set of JAAS login modules that can be used for various scenarios. For example, the IdentityLoginModule is used for authentication based on local portal data, SynchronizingLdapLoginModule for authentication using LDAP, and DBIdentityLoginModule for authentication using a database.

Within the jboss-portal.sar/portal-server.war application, all portal requests are routed through a single servlet called org.jboss.portal.server.servlet.PortalServlet. This servlet is defined twice, as follows, in the configuration file WEB-INF/web.xml to ensure that all possible request sources are covered:

  • PortalServletWithPathMapping for path mappings
  • PortalServletWithDefaultServletMapping for the default servlet mapping

The servlet is mapped four times with variations to address a combination of secure SSL access and authenticated URLs, as follows:

  • /*: Default access, and with no security constraint, allows access to everybody
  • /sec/*: All requests to a secure protocol are routed through this path, ensuring SSL transport
  • /auth/*: Authenticated access. Requires user to be authenticated before accessing the content under this tree
  • /authsec/*: An authenticated and secure access

The following snippet from web.xml shows the entries:

<!-- Provide access to unauthenticated users -->
<!-- Provide secure access to unauthenticated users -->
<!-- Provide access to authenticated users -->
<!-- Provide secure access to authenticated users -->

The URL patterns can be changed based on personal preference.


Authorization is the process of determining if an authenticated user has access to a particular resource. Similar to authentication, JBoss portal provides in-built support for authorization, through Java Authorization Contract for Containers(JACC). JACC is a JSR-115 specification for the authorization models of the Java2 and JEE enterprise platforms. In the next few sections, we will look at how JBoss portal facilitates authorization using JACC. However, before we go into the details of access controls and authorization configurations, let's quickly look at how roles are configured in JBoss Portal.

User and role management

A role is an authorization construct that denotes the group that a user of the portal belongs to. Typically, roles are used to determine the access rights and the extent of these rights for a given resource. We saw in an earlier section how to configured portal assets such as, portals, pages, and portlet instances, to restrict certain actions to specific roles. We used a role called SPECIAL_USER for our examples. However, we never really defined what this role means to JBoss portal.

Let's use the JBoss portal server console to register this role with the server.

Log in as admin, and then click on the Members tab. This takes us to the User Management and Role Management tabs.

User Security and Access Control in JBoss portals


The User Management tab is used for creating new users. We will come back to this shortly, but for now, let's switch over to the Role Management tab and click on the Create role link on the bottom right of the page. We can now add our SPECIAL_USER role and provide a display name for it. Once we submit it, the role will be registered with the portal server.

User Security and Access Control in JBoss portals


As we will see later, every attempt by an authenticated user to access a resource that has security constraints through a specific role will be matched by the portal before granting or denying access to the resource.

Users can be added to a role by using the User Management tab. Each user has a role property assigned, and this can be edited to check all of the roles that we want the user to belong to. We can see that for the user User, we now have an option to add the user to the Special User role.

The portal permission

A permission object carries the relevant permission for a given entity. The object is used to describe permission for the portal. Like all the other entity-specific permission classes, it extends the class, and any permission checked in the portal should extend the PortalPermission as well. Two additional fields of significance are as follows:

  1. uri: A string that specifies the URI of the resource that is described by the permission
  2. collection: An object of class, which is used when the permission acts as a container for other permissions

The authorization provider

The authorization provider is a generic interface of the type, and provides access to several services.

public interface AuthorizationDomain
String getType();
DomainConfigurator getConfigurator();
PermissionRepository getPermissionRepository();
PermissionFactory getPermissionFactory();

Let us look into these classes a bit more in detail:

  • provides configuration access to an authorization domain. The authorization schema consists of bindings between URIs, roles, and permissions.
  • provides runtime access to the authorization domain. It is used to retrieve the permissions for a specific role and URI. It is used at runtime by the framework, to take security decisions.
  • is a factory to instantiate permissions for the specific domain. It is used at runtime to create permission objects of the appropriate type by the security framework.

Making a programmatic security check

With this understanding of the background of the configuration files and the appropriate authorization API, we are now ready to make a programmatic security check. All we have to do is to create a permission of the correct type and check this against the org.jboss.portal.spi.auth.PortalAuthorizationManager service. This service is used internally by JBoss server and is connected to the various authorization providers, for a runtime decision based on the type of permission. Access to this service is through org.jboss.portal.spi.auth.PortalAuthorizationManagerFactory. The factory is a portal service that is usually added to services as follows:

<?xml version="1.0" encoding="UTF-8"?>
<mbean code='MyService"

It can be added to the servlet context of a WAR file in the WEB-INF/jboss-portlet.xml file, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 3.0//EN"

Here is an example of how a security check is made for a specific page:

PortalAuthorizationManager pam = factory.getManager();
PortalObjectId id = page.getId();
PortalObjectPermission perm = new PortalObjectPermission(id,
if (pam.checkPermission(perm) == false)
System.out.println("Current user is not authorized to view page " + id);

Configuring an authorization domain

Configuring a domain can be done through the DomainConfigurator interface:

public interface DomainConfigurator
Set getSecurityBindings(String uri);
void setSecurityBindings(String uri, Set securityBindings)
throws SecurityConfigurationException;
void removeSecurityBindings(String uri)
throws SecurityConfigurationException;

The various methods of this interface allow configuration of security bindings for a given resource, where a resource is naturally identified by a URI. The object is an object that encapsulates a role name and a set of actions bound to this role.

RoleSecurityBinding binding1 = new RoleSecurityBinding(Collections.singleton("view"), "Admin");
RoleSecurityBinding binding2 = new RoleSecurityBinding(Collections.singleton("view"), "User");
Set bindings = new HashSet();
configurator.setSecurityBinding(pageURI, bindings);

LDAP configuration

Light-weight Directory Access Protocol (LDAP) is an important component of an enterprise portal architecture. Due to its specialized nature, it is usually the repository of all user information, including user IDs/passwords and roles.

LDAP support can be enabled through the following steps:

  1. Configure LDAP properties on the server. LDAP can be configured in JBoss portal in two ways. We can either change the IdentityServiceController section of the portal service configuration file jboss-service.xml to point to a different identity file, or we can leave the configuration intact and change the identity file.
  2. Let's look at these options in detail:

    Let's open the file $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml.

    Change the ConfigFile option to ldap-identity-config.xml; this file comes with the portal server and can be found in the conf/ directory.

    <attribute name="JndiName">
    <attribute name="RegisterMBeans">true</attribute>
    <attribute name="ConfigFile">
    <attribute name="DefaultConfigFile">

    Alternatively, we can swap the contents of the identity-config.xml and ldap_dentity-config.xml files.

  3. Set up an LDAP Connection. After identifying the appropriate configuration file for identity management, we can now configure LDAP properties and connections in the file, ldap_identity-config.xml (or identity-config.xml, depending on the approach chosen above).
  4. An LDAP tree appears as follows. It has clearly defined groups, users, and their names organized in a tree form. A typical LDAP interaction process involves connecting to the LDAP server and then looking up a user by using the tree structure.

    User Security and Access Control in JBoss portals

Our configuration file to connect to the LDAP server will look like this:

<value> uid=admin,ou=system </value>

We are now connected to the LDAP server; all subsequent requests for authentication will now be routed to this server.

So, the user wpauli will have the following information stored for him in the LDAP tree. After authentication, we can also get the other details of the user.

User Security and Access Control in JBoss portals

Apart from these, there are few other LDAP features provided by the server, such as connection pooling, SSL-based access, tree management, and so on, that can facilitate a productive interaction with an LDAP server.

Single sign-on

Single Sign-On, or SSO, is a process in which the user logs into the system only once, and all his or her future interaction with any subsequent systems is seamless and doesn't require the user to be authenticated over and over again for each system. Portlets within a portal server integrate seamlessly as the user credentials are transferred easily within the system, but the same is not true for systems that are outside of the portal server, on the intranet or on the Internet.

JBoss portal offers support for various SSO packages in the industry that help to provide seamless integration between various functionalities and systems.

We will consider the Central Authentication Service (CAS) as our SSO provider, and we need to make sure that we have both the server and client CAS binaries, along with the deployable WAR file, with us before we start the integration. The binaries can be found on the CAS web site at

The following steps walk us through the configuration and integration of CAS with JBoss portal server:

  1. Open the cas.war file provided by the CAS project, and copy the portalidentity-lib.jar and portal-identity-sso-lib.jar files. Please note that the WAR file can have a different name based on the release. Copy the file from $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib to $JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/lib.
  2. Uncomment the following entry in the file $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml. This configures the login, logout, and validate pages when requests for these actions are made on the portal.
  3. <Valve

    The ports and the server name should be changed based on the local configuration. Please note that CAS requires SSL to function effectively. Hence, it might be a good idea to enable SSL on the JBoss server. You can find more details at

  4. Add the casclient.jar library to the portal project. The client JAR can be found at
  5. Uncomment the following lines in the $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml file. This notifies the portal server that all authentication-related requests need to be directed to CAS.
  6. <mbean
    <attribute name="HavingRole"></attribute>
  7. So far, we have been creating interfaces for use by CAS authenticationHandler. We will now create the authenticationHandler instance in CAS, which will use the service that we created earlier in the JBoss server. Edit the $JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/deployerConfigContext.xml file, and replace the following line in the authenticationHandlers section:
  8. <bean class="" />

    with the following line:

    <bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" />

A good test to verify the installation and configuration of CAS is to go to the portal home page and click on the Login link. IF CAS is installed successfully, the Login page should now be a CAS authentication server login page, overriding the default JBoss portal login page.

User Security and Access Control in JBoss portals


Once authenticated, CAS will hand over the control back to the application and pass the user credentials.

Books to Consider

comments powered by Disqus