JBoss Portal 2.2

The policy configuration factory is an abstract singleton that serves as the access point for policy configurations. It features a static accessor to get the factory implementation.

                            public static PolicyConfigurationFactory getPolicyConfigurationFactory()
                               throws ClassNotFoundException, PolicyContextException
                            {
                                ....
                            }
                        

The policy configuration factory to load can be specified in a VM system property (-D) "javax.security.jacc.PolicyConfigurationFactory.provider". The default implementation that will be loaded if nothing else is defined, is org.jboss.security.jacc.JBossPolicyConfigurationFactory.

The policy configuration interface is the access point for all configured permissions of one context id. It allows to manipulate the content of the security policy (see below) which is the ultimate policy decission point. In the standard J2EE model, a context id is equivalent to the deployed context: the war or ejb archive. In the case of JBoss portal, this model was extended to allow a more flexible definition of the context id. The default implementation of the portal's JBossSecurityProvider (see below) creates a separate context id for each portal resource. This allows the portal to reload the content of a specific portal resources without having to refresh any of the other resource's security attributes.

The jacc policy is the ultimate policy decission point. It makes the decission wether a permission is implied or not. To make this decission it can do whatever is needed. The default implementation (org.jboss.security.jacc.DelegatingPolicy) delegates the decission to the policy context, which in turn delegates it to the java.security.Permissions that make up all configured permissions for a given role in the requested policy context.

The portal security provider interface wrapps the functionality in the jacc PolicyConfigurationFactory. It allows access to all available policy configurations. It also offers a method the check wether a particular policy context is in service or not. The jacc policy singleton is also available via this interface.

                            // check if the provided policy context id is available
                            boolean inService(String policyContextID) throws PolicyContextException;
                            // get the policy configuration for the provided policy context id
                            PolicyConfiguration getPolicyConfiguration(String contextID, boolean remove) throws PolicyContextException;
                            // get the jacc policy singleton
                            Policy getPolicy();
                        

The jboss security provider extends the portal security provider, and adds access to the server configuration. This additional access allows a provider implementation to consider server configuration properties when making a decission about any of the policy context calls.

                            // get the portal server configuration
                            ServerConfig getServerConfig();
                        

The portal policy service is the root service from where one can get access to the portal policy. The default implementation of this service interface (org.jboss.portal.security.impl.jacc.PortalPolicyServiceImpl) is an mbean. It uses the implementation of the JBossSecurityProvider interface to get to the jacc policy singleton. The security provider interface is a wrapper of the jacc PolicyConfigurationFactory. It's implementation delegates all calls to the standard jacc PolicyConfigurationFactory.

The PortalPolicyService exposes only one method:

                            PortalPolicy getPolicy();
                        

The portal policy has only one method:

                            boolean implies(PortalSubject subject, PortalPermission permission);
                        

The default implementation of the portal policy, an inner class of the policy service implementation, (org.jboss.portal.security.impl.jacc.PortalPolicyServiceImpl$PortalPolicyImpl), uses the security provider to gain access to the portal policy implementation. It uses the JaccHelper class in the same package to determine the java.security.ProtectionDomain and the policy context id before calling the jacc policy to do the actual permission check.

As described above, the portal injects the org.jboss.portal.security.PortalSubject as a thread local property that is available throughout the portal request. The default implementation of this portal subject (org.jboss.portal.security.impl.jacc.JaccPortalSubject) wraps the jacc way of getting to the authenticated java.security.Subject, and reading the role memberships off of it. In other words: the mechanism of getting the subject and the subjects roles is identical to the way the application server id handling this security aspect.

As already mentioned above, the easiest way to get your own behavior for the portal authorization, you can provide your own implementation of the JACC policy. To do so, you'll need to create a class that extends java.security.Policy, and overwrites the implies method. Be aware that the portal goes beyond the JACC specification in that it allows new permission classes, other then the 5 predefined classes from the specification. All permissions used by the portal extend the abstract org.jboss.portal.security.PortalPermission class, which in turn extends java.security.Permission. The currently (as of 2.2) implemented permission classes are ComponentPermission, InstancePermission, and PortalObjectPermission. Your policy implementation can distinguish those permissions, and handle them differently if it so desires.

For an example on how to implement your own, take a look at the portal's default policy implementation. The class is org.jboss.portal.security.impl.jacc.PortalJaccPolicy. This policy is basically a copy of the application servers DelegatingPolicy class. The idea behind it is that the portal policy is stacked ontop of the J2SE policy, configured in the VM. The portal policy will handle authorization checks for all the allowed JACC permissions (for ejb and servlet/jsp calls), In addition to the basic J2SE permission types. It allows to configure external permissions that will be treated just like the basic JACC permissions. If the incoming permission to check is an instance of any of the five JACC permission classes, or one of the configured external permission classes, the policy will handle the implies check, otherwise it will delegate to the J2SE policy that was in place in the VM, before the portal policy was created. Remember that the java security model allows only one policy to be active in the VM at any given time. By stacking the policies there is a way to have several policies active with only one policy configured at the VM level.

It is up to your implementation if you want to copy this behavior of configurable external permissions and stacked policies or not. You could implement a flat policy that treats all permissions the same, but be aware that since your policy will take the place of the only policy in the system, that all policy decissions will be coming into your policy. So all security checks by the J2SE SecurityManager will have to be handled by your policy as well.

One strange anomalie that is currently built into the portal is the fact that your policy needs to adhere to a naming convention. There needs to be a method that is used by the policy service to pick up the policy instance. Your policy needs to provide a method with the following signature: (Note: the method signature is not enforced by any interface or abstract class, since the origin of this requirement is a workaround for an underlying problem with the policy configuration and redeployments of the portal sar):

                        public Policy getPolicyProxy()
                    

You can return 'this' , or any decorator class of your policy that would allow you to restrict the externally available functionality of the policy.

The policy implementation must be an mbean. It is injected into the policy service mbean to make it available to other interested parties. Take a look at the jboss-service.xml in the jboss-portal.sar (in the meta-inf folder). The mbean definition for the "portal:service=SecurityProvider" injects the "jboss.security:service=JaccPolicyProvider" via the PolicyName attribute. In other words: the service that is configured as "jboss.security:service=JaccPolicyProvider" needs to expose a method as described above, that returns an implementation of the java.security.Policy interface (public Policy getPolicyProxy(){...}). This method will be called by the SecurityProvider service at startup to read the configured policy from the mbean server. Here is the section defining the jacc policy from the jboss-service.xml:

                        
                        <mbean
                           code="org.jboss.portal.security.impl.jacc.PortalJaccPolicy"
                           name="jboss.security:service=JaccPolicyProvider"
                           xmbean-dd="org/jboss/portal/security/impl/jacc/PortalJaccPolicy.xml">
                           <attribute name="ExternalPermissionTypes">
                              org.jboss.portal.core.security.PortalObjectPermission,
                              org.jboss.portal.core.security.InstancePermission,
                              org.jboss.portal.core.security.ComponentPermission
                           </attribute>
                        </mbean>
                        
                    

And here is the section defining the jacc security provider service, and injecting the policy via the policy proxy attribute:

                        
                        <mbean
                           code="org.jboss.portal.security.impl.jacc.JBossSecurityProviderImpl"
                           name="portal:service=SecurityProvider"
                           xmbean-dd="">
                              <xmbean>
                                 ...more descriptor info here...
                              </xmbean>
                              <attribute name="PolicyName">jboss.security:service=JaccPolicyProvider</attribute>
                              <attribute name="PolicyAttributeName">PolicyProxy</attribute>
                        </mbean>
                        
                    

Note: If there is no policy mbean active for the defined PolicyName and PolicyAttributeName in the SecurityProvider mbean, the policy currently set in the VM will be used instead. The policy will be determined via:

                        import java.security.Policy;
                        Policy policy = Policy.getPolicy();
                    

If your policy extends PortalJaccPolicy a new instance will be created everytime the portal starts. This instance will not be set as the VM wide policy, leaving the original policy in place. In other words: Policy.getPolicy() will not return your policy. To get to your policy, you'll have to lookup the portal security provider, and get it from there.

                        JBossSecurityProvider provider = ....;
                        Policy policy = provider.getPolicy();
                    

You could of course go even further and replace the implementation of the security provider itself. That way, you can decide how to get to the policy in whatever way.

Note that the current implementation is more complex than it should be. This is due to problems in the application server's JACC policy implementation. Once those problems are fixed, the portal's implementation will be simplified. Effectively: the portal should be able to just get the current policy in the VM, (Policy p = Policy.getPolicy();) and use it. The policy would still have to be configured with the external permissions (PortalPermission classes) to treat them like JACC permissions, and not delegate the permission check to the underlying J2SE policy.

To start, you'll need to change the way the security constraint information is converted into permissions. Or perhaps you wouldn't even want to convert them, and use the PortalPolicyConfigService and the PortalPolicyConfig as your one and only store of permission information. If you decide to create your own system of storing and enforcing permissions, you'll have to implement the org.jboss.portal.security.config.ConfigListener interface, and register it with the PortalPolicyConfig(s) you are interested in. Look at the org.jboss.portal.security.impl.JBossPortalPolicyConfigStoreImpl as an example of how this can be done. This is an mbean that injects the ConfigListener via an attribute (depends optional-attribute-name="ConfigListener"). If you take a look at the jboss-service.xml you'll see that this mbean is used three times, and each time a config listener is injected. The three mbeans represent three different policy configurations, and the same service (portal:policy=JaccPortalPolicyConfigurator) registers with all three of them as a ConfigListener. You would have to replace the implementation of the policy configurator (portal:policy=JaccPortalPolicyConfigurator) and configure the three instances of JBossPortalPolicyConfigStoreImpl to register your config listener instead. Your config listener can do whatever you desire. Just keep in mind that the result needs to be accessible for the policy enforcement.

Policy enforcement is initiated via the PolicyEnforcementInterceptor in the server invocation stack. This interceptor uses the results of two other interceptors:

These two interceptors inject the PortalSubject and the PortalPolicy as thread local properties. The policy enforcement interceptor creates a permission based on the requested resource and action, and checks the portal policy to see if the permission implies for the determined portal subject.

You would probably keep the concept of the subject around since this is what the JAAS login module populates with the authentication information from the login process. The portal policy is what is more interesting. Your ConfigListener will populate some store with the constraint information, and that store needs to be made available to the policy enforcement side. The way to do this is via the portal policy from the PolicyAssociationInterceptor. To inject your own implementation of the PortalPolicy interface, you can provide your own version of the PortalPolicyService interface. The default implementation is an mbean that is injected into the PolicyAssociationInterceptor. Write your own version of the PortalPolicyService and configure it in the jboss-service.xml, replacing the default PortalPolicyServiceImpl. Of course you could go even further and replace the PolicyAssociationInterceptor itself no make it independent from the PortalPolicyService. The important thing is that your implementation of the PortalPolicy needs to utilize what your ConfigListener stored before.

For completeness sake, let's take a look at the SubjectAssociationInterceptor as well. It is responsible for injecting the PortalSubject. The PortalSubleject is a flagging interface (has no methods), and the default implementation (JaccPortalSubject) is simply newed up every time the SubjectAssociationInterceptor is invoked. The PortalSubject is later on used by the PortalPolicy to check if a given PortalPermission implies for the given PortalSubject.

Portals and pages can be configured to use a particular layout. The connection to the desired layout is made in the portal descriptor (YourNameHere-object.xml). Here is an example of such a portal descriptor:

                <portal>
                    <portal-name>default</portal-name>
                    <properties>
                       <!-- Set the layout for the default portal -->
                       <!-- see also portal-layouts.xml -->
                       <property>
                          <name>layout.id</name>
                          <value>phalanx</value>
                       </property>
                    </properties>
                    <pages>
                       <page>
                        <page-name>theme test</page-name>
                        <properties>
                           <!-- set a difference layout for this page -->
                           <property>
                              <name>layout.id</name>
                              <value>industrial</value>
                           </property>
                        </properties>
                       </page>
                    </pages>
                  </portal>

The name specified for the layout to use has to match one of the names defined in the portal-layouts.xml descriptor of one of the deployed applications.

As you can see, the portal or page property points to the layout to use via the name of the layout. The name has been given to the layout in the layout descriptor. It is in that layout descriptor where the name gets linked to the physical resource (the JSP or Servlet) that will actually render the layout.

To access a layout from code, you need to get a reference to the LayoutService interface. The layout service is an mbean that allows access to the PortalLayout interface for each layout that was defined in a portal layout descriptor. As a layout developer you should never have to deal with the layout service directly. Your layout hooks are the portal and page properties to configure the layout, and the layout strategy, where you can change the layout to use for the current request, before the actual render process begins.

The theme tag looks for the determined theme of the current request (see Portal Themes for more details). If no theme was determined, this tag allows an optional attribute 'themeName' that can be used to specifiy a default theme to use as a last resort. Based on the determined theme name, the ThemeService is called to lookup the theme with this name and to get the resources associated with this theme. The resulting style and link elements are injected, making sure that war context URLS are resolved appropriately.

This tags allows portlets to inject content into the header. More details about this function are mentioned in the 'other Theme Functions' section of this document.

The region tag renders all the portlets in the specified region of the current page, using the determined RenderSet to produce the markup that surrounds the individual portlet markup fragments. The regionName attribute functions as a query param into the current page. It determines from what page region the portlets will be rendered in this tag. The regionID attribute is what the RenderSet can use to generate a css selector for this particular region. In case of the divRenderer, a DIV tag with an id attribute corresponding to the provided value will be rendered for this region. This id in turn can be picked up by the CSS to style the region.