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&gt;roy(a)jboss.org&lt;/email&gt; </author> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + <email&gt;julien(a)jboss.org&lt;/email&gt; + </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