[portal-commits] JBoss Portal SVN: r5934 - docs/trunk/referenceGuide/en/modules
portal-commits at lists.jboss.org
portal-commits at lists.jboss.org
Mon Dec 25 19:11:21 EST 2006
Author: julien at jboss.com
Date: 2006-12-25 19:11:17 -0500 (Mon, 25 Dec 2006)
New Revision: 5934
Modified:
docs/trunk/referenceGuide/en/modules/security.xml
Log:
added some security documentation in 2.6 docs
Modified: docs/trunk/referenceGuide/en/modules/security.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/security.xml 2006-12-23 12:45:48 UTC (rev 5933)
+++ docs/trunk/referenceGuide/en/modules/security.xml 2006-12-26 00:11:17 UTC (rev 5934)
@@ -6,6 +6,11 @@
<surname>Russo</surname>
<email>roy at jboss.org</email>
</author>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien at jboss.org</email>
+ </author>
</chapterinfo>
<title>Security</title>
<sect1 id="securing_objects">
@@ -104,4 +109,180 @@
<xref linkend="desc_example_portal"/>
</para>
</sect1>
+
+ <sect1 id="security_authentication">
+ <title>Authentication with JBoss Portal</title>
+ <para>JBoss Portal relies on Java EE for the authentication of users. The Java EE authentication has its advantages
+ and drawbacks. The main motivation for using Java EE security is the integration with the application server and the
+ operational environment in which the portal is deployed. The servlet layer provides already the authentication functionnality
+ and obviously it is not a responsibility of the portal. Whenever a user is authenticated by the servlet layer
+ its security identity is propagated throughout the call stack in the different layers of the Java EE stack. The weaknesses
+ are the lack of an explicit logout mechanism and the lack of dynamicity in the mapping of URL as security resources. However
+ JBoss Portal improves that behavior when it is possible to do so.</para>
+ <sect2>
+ <title>Authentication configuration</title>
+ <para>JBoss Portal can be seen before all as a web application and therefore inherits all the configuration mechanisms
+ related to web applications. The main entry point of the whole portal is the <emphasis>jboss-portal.sar/portal-server.war</emphasis>
+ deployment which is the web application that defines and maps the portal servlet. Here you can configure various things
+ <itemizedlist>
+ <listitem>In the <emphasis>WEB-INF/web.xml</emphasis> you can change the authentication mode. The default
+ authentication mechanism uses the form based authentication, however you can change it to any of the
+ mechanism provided by the servlet specification.</listitem>
+ <listitem>In the <emphasis>WEB-INF/jboss-web.xml</emphasis> you can change the security domain used by the portal.
+ The default security domain used by the portal is <emphasis>java:/jaas/portal</emphasis>. That setting is specific
+ to the JBoss Application Server and how it binds the Java EE security to the operational environment. A security domain
+ is a scope defined at the Application Server Level and defines usually a JAAS authentication stack. The portal
+ security domain authentication stack is defined in the <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis>
+ and is dynamically deployed with the portal. The JBoss Application Server documentation is certainly the best
+ reference for that topic.
+ </listitem>
+ <listitem>The files <emphasis>login.jsp</emphasis> and <emphasis>error.jsp</emphasis> provide the pages used
+ the form based authentication process. More information can be found in any good servlet documentation.</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ <title>The portal servlet</title>
+ <para>The portal defines a single servlet to take care of all portal requests. The class name of that servlet is
+ <emphasis>org.jboss.portal.server.servlet.PortalServlet</emphasis>. That servlet needs to be declared two times with different
+ configurations otherwise the portal would not be able to know about some request details which are importants.
+ <itemizedlist>
+ <listitem><emphasis>PortalServletWithPathMapping</emphasis> is used for path mapping mappings.</listitem>
+ <listitem><emphasis>PortalServletWithDefaultServletMapping</emphasis> is used for the default servlet mapping.</listitem>
+ </itemizedlist>
+ The portal servlet is mapped for times with different semantics, the differences between the semantics are related to the transport layer.
+ Each one of those for mappings will have the same request meaning for the portal beside the transport aspect. By default
+ those mappings are
+ <itemizedlist>
+ <listitem><emphasis>/*</emphasis> : the default access, does not define any security constraint. This is the default
+ access that everybody uses.</listitem>
+ <listitem><emphasis>/sec/*</emphasis> : the secured access, requires https usage. It is triggered when
+ a portlet is defined as secure or when a secure portlet link is created. It requires the configuration
+ of the https connector in JBoss Web. The JBoss Application Server documentation provides more information
+ about it.</listitem>
+ <listitem><emphasis>/auth/*</emphasis> : the authenticated access, requires the user to be authenticated
+ to be used.</listitem>
+ <listitem>/authsec/*<emphasis></emphasis> : combine thet two previous options into a single one.</listitem>
+ </itemizedlist>
+ Usually ones should not care much about those mappings as the portal will by itself switch to the most appropriate mapping.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="security_authorization">
+ <title>Authorization with JBoss Portal</title>
+ <para>JBoss Portal defines a framework for authorization. The default implementation of that framework is based on
+ the Java Authorization Contract for Containers (JACC) which is implemented by J2EE 1.4 Application Servers. This section of
+ the documentation focuses on defining the framework and its usage and is not an attempt to define what authorization
+ is or is not because it is out of scope of this context. Instead we will try to straightforwardly describe the
+ framework and how it is used. No specific knowledge is expected about JACC although it is a recommanded read.</para>
+ <sect2>
+ <title>The portal permission</title>
+ <para>The <emphasis>org.jboss.portal.security.PortalPermission</emphasis> object is used to describe a permission for the portal. It extends the <emphasis>java.security.Permission</emphasis>
+ class and any permission checked in the portal should extend the <emphasis>PortalPermission</emphasis> as well. That permission
+ adds two fields to the <emphasis>Permission</emphasis> class
+ <itemizedlist>
+ <listitem>uri : is a string which represents an URI of the resource described by the permission.</listitem>
+ <listitem>collection : an object of class <emphasis>org.jboss.portal.security.PortalPermissionCollection</emphasis> which
+ is used when the permission act as a container for other permissions. If that object exists then the uri field should be null
+ as a portal permission represents an uri or acts as a container in an exclusive manner.</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ <title>The authorization provider</title>
+ <para>
+ The <emphasis>org.jboss.portal.security.spi.provider.AuthorizationDomain</emphasis> is an interface which provides access to several services.
+ <programlisting>
+ public interface AuthorizationDomain
+ {
+ String getType();
+ DomainConfigurator getConfigurator();
+ PermissionRepository getPermissionRepository();
+ PermissionFactory getPermissionFactory();
+ }
+ </programlisting>
+ <itemizedlist>
+ <listitem><emphasis>org.jboss.portal.security.spi.provider.DomainConfigurator</emphasis> provides configuration access
+ to an authorization domain. The authorization schema is very simple as it consists of bindings between URI, roles and permissions.</listitem>
+ <listitem><emphasis>org.jboss.portal.security.spi.provider.PermissionRepository</emphasis> provides runtime access to the authorization
+ domain. Usually it is used to retrieves the permissions for a specific role and URI. It is used at runtime by the framework
+ to take security decisions.</listitem>
+ <listitem><emphasis>org.jboss.portal.security.spi.provider.PermissionFactory</emphasis> is a factory to instantiate permissions
+ for the specific domain. It is used at runtime to create permissions objects of the appropriate type by the security framework.</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ </sect2>
+ <sect2>
+ <title>Making a programmatic security check</title>
+ <para>Making a security check is an easy thing as it consists in created a permission of the appropriate type and
+ make a check against the <emphasis>org.jboss.portal.spi.auth.PortalAuthorizationManager</emphasis> service. That
+ service is used by the portal to make security checks. It is connected to the different authorization providers
+ in order to take decisions at runtime based on the type of the permission. Access to that service is done
+ through the <emphasis>org.jboss.portal.spi.auth.PortalAuthorizationManagerFactory</emphasis>. The factory
+ is a portal service which is usually injected in other services like that</para>
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<server>
+ ...
+ <mbean
+ code='MyService"
+ name="portal:service=MyService">
+ <depends
+ optional-attribute-name="PortalAuthorizationManagerFactory"
+ proxy-type="attribute">portal:service=PortalAuthorizationManagerFactory</depends>
+ ...
+ </mbean>
+ ...
+</server>]]>
+ </programlisting>
+ <para>It be injected in the servlet context of a war file in the file <emphasis>WEB-INF/jboss-portlet.xml</emphasis></para>
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<portlet-app>
+ ...
+ <service>
+ <service-name>PortalAuthorizationManagerFactory</service-name>
+ <service-class>org.jboss.portal.security.spi.auth.PortalAuthorizationManagerFactory</service-class>
+ <service-ref>:service=PortalAuthorizationManagerFactory</service-ref>
+ </service>
+ ...
+</portlet-app>]]>
+ </programlisting>
+ <para>Here is an example of how a security check is made for a specific page</para>
+ <programlisting>
+PortalAuthorizationManager pam = factory.getManager();
+PortalObjectId id = page.getId();
+PortalObjectPermission perm = new PortalObjectPermission(id, PortalObjectPermission.VIEW_MASK);
+if (pam.checkPermission(perm) == false)
+{
+ System.out.println("Current is not authorization to view page " + id);
+}
+ </programlisting>
+ </sect2>
+ <sect2>
+ <title>Configuring an authorization domain</title>
+ <para>Configuring a domain can be done through the <emphasis>DomainConfigurator</emphasis> interface</para>
+ <programlisting>
+ public interface DomainConfigurator
+ {
+ Set getSecurityBindings(String uri);
+ void setSecurityBindings(String uri, Set securityBindings) throws SecurityConfigurationException;
+ void removeSecurityBindings(String uri) throws SecurityConfigurationException;
+ }
+ </programlisting>
+ <para>The various methods of that interface allows to configure security bindings for a given resource where
+ a resource is naturally identified by an URI. The <emphasis>org.jboss.portal.security.RoleSecurityBinding</emphasis>
+ object is an object which encapsulate a role name and a set of actions bound to this role.
+ </para>
+ <programlisting>
+RoleSecurityBinding binding1 = new RoleSecurityBinding(Collections.singleton("view"), "Admin");
+RoleSecurityBinding binding2 = new RoleSecurityBinding(Collections.singleton("view"), "User");
+Set bindings = new HashSet();
+bindings.add(binding1);
+bindings.add(binding2);
+configurator.setSecurityBinding(pageURI, bindings);
+ </programlisting>
+ </sect2>
+ </sect1>
</chapter>
\ No newline at end of file
More information about the portal-commits
mailing list