6:11 p.m.
Author: julien(a)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(a)jboss.org</email>
</author>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien(a)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