Author: bdaw
Date: 2007-03-15 16:07:47 -0400 (Thu, 15 Mar 2007)
New Revision: 6695
Modified:
docs/trunk/referenceGuide/en/master.xml
docs/trunk/referenceGuide/en/modules/authentication.xml
docs/trunk/referenceGuide/en/modules/identity.xml
docs/trunk/referenceGuide/en/modules/ldap.xml
Log:
doc update
Modified: docs/trunk/referenceGuide/en/master.xml
===================================================================
--- docs/trunk/referenceGuide/en/master.xml 2007-03-15 19:58:37 UTC (rev 6694)
+++ docs/trunk/referenceGuide/en/master.xml 2007-03-15 20:07:47 UTC (rev 6695)
@@ -63,13 +63,13 @@
<!-- clustering configuration --> &clustering;
<!-- WSRP --> &wsrp;
<!-- security administration --> &security;
- <!-- CMS --> &CMS;
- <!-- NavTabs --> &navtabs;
- <!-- theme/layout api --> &themeandlayouts;
<!-- Identity --> &identity;
<!-- Authentication --> &authentication;
<!-- LDAP --> &ldap;
<!-- SSO --> &sso;
+ <!-- CMS --> &CMS;
+ <!-- NavTabs --> &navtabs;
+ <!-- theme/layout api --> &themeandlayouts;
<!-- troubleshooting FAQ--> &troubleshooting;
</book>
Modified: docs/trunk/referenceGuide/en/modules/authentication.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-15 19:58:37 UTC (rev
6694)
+++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-15 20:07:47 UTC (rev
6695)
@@ -6,16 +6,32 @@
<email>boleslaw dot dawidowicz at redhat dot com</email>
</author>
</chapterinfo>
- <title>Authentication</title>
+ <title>Authentication and Authorization</title>
<para>This chapter describes authentication mechanisms in JBoss
Portal</para>
<sect1 id="authentication_in_portal">
<title>Authentication in JBoss Portal</title>
- <para>TODO</para>
- <para>To understand authentication mechanisms in JBoss Portal better please
refer to <link
linkend="security.security_authentication">Security</link>
chapter</para>
+ <para>JBoss Portal is heavily standard based so it leverages
<emphasis>Java Authentication and Authorization Service (JAAS)</emphasis>
+ in JBoss Application Server. Because of this it can be very flexibly configured,
and other
+ authentication solutions can be plugged in really easily.
+ To better understand authentication mechanisms in JBoss Portal please refer to
+ <link
linkend="security.security_authentication">Security</link> chapter.
+ To learn more about JAAS look for proper documentation on
+ <ulink
url="http://java.sun.com/javase/6/docs/technotes/guides/security/&qu...
security</ulink> website.
+ To learn more about security in JBoss Application Server please read
+ <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossSX">JBoss...
documentation.
+ </para>
<sect2 id="configuration">
<title>Configuration</title>
- <para>You can configure JAAS authentication stack in
<emphasis>jboss-portal.sar/conf/login-config.xml</emphasis></para>
- <para>TODO</para>
+ <para>You can configure JAAS authentication stack in
<emphasis>jboss-portal.sar/conf/login-config.xml</emphasis>.
+ What is very important to remember is that authorisation in portal starts in
JAAS level -
+ configured <emphasis>LoginModule</emphasis>s apply proper
<emphasis>Principal</emphasis> objects representing
+ roles to authenticated user. Like you can see in
<emphasis>jboss-portal.sar/portal-server.war/WEB-INF/web.xml</emphasis>
portal
+ servlet is secured with specified role
("<emphasis>Authenticated</emphasis>"). In default portal
configuration
+ this role is dynamically added by
<emphasis>IdentityLoginModule</emphasis>. If you reconfigure default JAAS
authentication
+ chain with other <emphasis>LoginModule</emphasis>
implementations, please remember you must fit in this
+ security constraints to be able to access portal. For example if you place only
one <emphasis>LoginModule</emphasis>
+ that will authenticate users against LDAP server you may consider adding all
users in your LDAP tree to such role.
+ </para>
</sect2>
</sect1>
<sect1 id="portal_login_modules">
@@ -170,9 +186,9 @@
<module-option
name="java.naming.security.authentication">simple</module-option>
<module-option name="bindDN">cn=Directory
Manager</module-option>
<module-option
name="bindCredential">secret</module-option>
- <module-option
name="baseCtxDN">ou=People,o=test,dc=portal,dc=qa,dc=atl,dc=jboss,dc=com</module-option>
+ <module-option
name="baseCtxDN">ou=People,dc=example,dc=com</module-option>
<module-option
name="baseFilter">(uid={0})</module-option>
- <module-option
name="rolesCtxDN">ou=Roles,o=test,dc=portal,dc=qa,dc=atl,dc=jboss,dc=com</module-option>
+ <module-option
name="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option>
<module-option
name="roleFilter">(member={1})</module-option>
<module-option
name="roleAttributeID">cn</module-option>
<module-option name="roleRecursion">-1</module-option>
@@ -228,6 +244,7 @@
portal role with such name to the authenticated user. If such role
doesn't exist in portal, module will try to create it.
</listitem>
</itemizedlist>
+ <note>Example of usage in LDAP authentication can be found in <link
linkend="ldap.synchronizing">next</link> chapter.</note>
</para>
</sect2>
</sect1>
Modified: docs/trunk/referenceGuide/en/modules/identity.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-15 19:58:37 UTC (rev 6694)
+++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-15 20:07:47 UTC (rev 6695)
@@ -818,7 +818,7 @@
<para>Delegating UserProfileModule implementation has very specific role.
When we use storage mechanism like LDAP we may not be able to map all
user properties into LDAP attributes because of schema limitations. To solve
this problem we use database to store such not mapped properties.
Delegating user profile module will recognize if property is mapped as
<emphasis role="bold">ldap</emphasis> or <emphasis
role="bold">database</emphasis>
- end delegate <emphasis>setProperty()/getProperty()</emphasis> method
invocation to proper module implementation. This is implemented in
+ and delegate <emphasis>setProperty()/getProperty()</emphasis> method
invocation to proper module implementation. This is implemented in
<emphasis
role="bold">org.jboss.portal.identity.DelegatingUserProfileModuleImpl</emphasis>.
If property is mapped either as
<emphasis role="bold">ldap</emphasis> and <emphasis
role="bold">database</emphasis> the <emphasis
role="bold">ldap</emphasis> mapping will
have higher priority.
Modified: docs/trunk/referenceGuide/en/modules/ldap.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-15 19:58:37 UTC (rev 6694)
+++ docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-15 20:07:47 UTC (rev 6695)
@@ -12,7 +12,7 @@
<link linkend="authentication">Authentication</link> chapters
before</note>
<sect1>
<title>How to enable LDAP usage in JBoss Portal</title>
- <para>We'll describe here the simple steps that you'll need to enable
LDAP support in JBoss Portal.
+ <para>We'll describe here the simple steps that you'll need to
perform to enable LDAP support in JBoss Portal.
For additional information you need to study more about configuration of
identity and specific implementations of identity modules</para>
<para>There are two ways to achieve this:</para>
<itemizedlist>
@@ -494,7 +494,7 @@
]]>
</programlisting>
Pagination support is not widely implemented in LDAP servers. Because
<emphasis>UserModule</emphasis>
- implementations rely on JNDI and are targetted to be LDAP server agnostic
those methods are very effecient.
+ implementations rely on JNDI and are targetted to be LDAP server agnostic
those methods aren't very effecient.
As long as you don't rely on portal user management and use dedicated
tools for user provisioning it
shouldn't bother you. Otherwise you should consider extending the
implementation and providing
solution dedicated to your LDAP server.
@@ -668,18 +668,20 @@
<title>LDAP server tree shapes</title>
<para>JBoss Portal supports full user/role management for simple LDAP tree
shapes. Some more flexible
trees can be supported by <emphasis>LdapExtUserModuleImpl</emphasis>
and <emphasis>LdapExtRoleModuleImpl</emphasis>
- - but without user/role creation, removal capabilities.
+ - but without user/role creation and removal capabilities.
However if you have complex LDAP tree you should consider using
<link
linkend="authentication.synchronizing_login_module">SynchronizingLoginModule</link>
described in
<link linkend="authentication">Authentication</link>
chapter along with dedicated tools for user
provisioning provided with LDAP server.</para>
<para>
- In following subsections we will describe two base LDAP tree shapes along with
example ldifs and portal
- identity modules configurations.
+ In following subsections we will describe two base LDAP tree shapes along with
example LDIFs and portal
+ identity modules configurations. Those two examples differ only by using
different <emphasis>MembershipModule</emphasis>
+ implementations and describe only tree shapes with supported user/role creation
and removal capabilities.
</para>
<sect2>
<title>Keeping users membership in role entries</title>
- <para>TODO:</para>
+ <para>In this example, information about users/roles assignment is stored
in roles entries using LDAP
+ "<emphasis>member</emphasis>". Of course any other
attribute that comes with schema can be used for this.</para>
<para>Example tree shape in LDAP browser
<mediaobject>
<imageobject>
@@ -857,13 +859,8 @@
</sect2>
<sect2>
<title>Keeping users membership in user entries</title>
- <!--<para>Tree:
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle"
fileref="images/ldap/tree2-1.png"/>
- </imageobject>
- </mediaobject>
- </para>-->
+ <para>In this example, information about users/roles assignment is stored
in user entries using LDAP
+ "<emphasis>memberOf</emphasis>". Of course any other
attribute that comes with schema can be used for this.</para>
<para>Example tree shape in LDAP browser
<mediaobject>
<imageobject>
@@ -1046,19 +1043,95 @@
</programlisting>
</para>
</sect3>
-
-
</sect2>
</sect1>
- <sect1>
+ <sect1 id="ldap.synchronizing">
<title>Synchronizing LDAP configuration</title>
<para>
- TODO:
+ Like it was described in previous section, you can meet some limitations in
identity modules support for more
+ complex LDAP tree shapes. To workaround this you can use identity
synchronization on JAAS level. JBoss Portal comes with
+ <link
linkend="authentication.synchronizing_login_module">SynchronizingLoginModule</link>
that can be easily
+ configured with other authentication solutions that support JAAS framework. Here
we want to provide a simple
+ example on how it can be integrated with
+ <emphasis><ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule&quo...
+ from <emphasis>JBossSX</emphasis> framework.</emphasis>
</para>
+ <para>
+ First of all portal identity modules should be configured to work with portal
database - default configuration.
+ This is important as we will leverage them, and we want to synchronize users
identity into default portal storage
+ mechanism. So lets look at simple configuration that should take place in
+ <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis>
+ <programlisting>
+ <![CDATA[
+<policy>
+ <!-- For the JCR CMS -->
+ <application-policy name="cms">
+ <authentication>
+ <login-module
code="org.apache.jackrabbit.core.security.SimpleLoginModule"
flag="required"/>
+ </authentication>
+ </application-policy>
+
+ <application-policy name="portal">
+ <authentication>
+
+ <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule"
flag="required">
+ <module-option
name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</module-option>
+ <module-option
name="java.naming.provider.url">ldap://example.com:10389/</module-option>
+ <module-option
name="java.naming.security.authentication">simple</module-option>
+ <module-option name="bindDN">cn=Directory
Manager</module-option>
+ <module-option
name="bindCredential">lolo</module-option>
+ <module-option
name="baseCtxDN">ou=People,dc=example,dc=com</module-option>
+ <module-option
name="baseFilter">(uid={0})</module-option>
+ <module-option
name="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option>
+ <module-option
name="roleFilter">(member={1})</module-option>
+ <module-option
name="roleAttributeID">cn</module-option>
+ <module-option name="roleRecursion">-1</module-option>
+ <module-option
name="searchTimeLimit">10000</module-option>
+ <module-option
name="searchScope">SUBTREE_SCOPE</module-option>
+ <module-option
name="allowEmptyPasswords">false</module-option>
+ </login-module>
+
+ <login-module
code="org.jboss.portal.identity.auth.SynchronizingLoginModule"
flag="optional">
+ <module-option
name="synchronizeIdentity">true</module-option>
+ <module-option
name="synchronizeRoles">true</module-option>
+ <module-option
name="additionalRole">Authenticated</module-option>
+ <module-option
name="defaultAssignedRole">User</module-option>
+ <module-option
name="userModuleJNDIName">java:/portal/UserModule</module-option>
+ <module-option
name="roleModuleJNDIName">java:/portal/RoleModule</module-option>
+ <module-option
name="membershipModuleJNDIName">java:/portal/MembershipModule</module-option>
+ <module-option
name="userProfileModuleJNDIName">java:/portal/UserProfileModule</module-option>
+ </login-module>
+
+ </authentication>
+ </application-policy>
+</policy>
+ ]]>
+ </programlisting>
+ </para>
+ <para>
+ Few things are important in this configuration:
+ <itemizedlist>
+ <listitem><emphasis>LdapExtLoginModule</emphasis> has
<emphasis>flag="required"</emphasis> set
+ which means that if this single <emphasis>LoginModule</emphasis>
return <emphasis>fail</emphasis>
+ from authentication request whole process will fail.
<emphasis>SynchronizingLoginModule</emphasis>
+ has <emphasis>flag="optional"</emphasis>. Such
combination is critical as
+ <emphasis>SynchronizingLoginModule</emphasis> always
authenticates user sucessfully no matter what
+ credentials were provided. You always must have at least one
<emphasis>LoginModule</emphasis> that you
+ will rely on.
+ </listitem>
+ <listitem>
+ <emphasis>SynchronizingLoginModule</emphasis> is always the
<emphasis>last</emphasis> one in whole
+ authentication chain. This is because in
<emphasis>commit</emphasis> phase it will take users
+ <emphasis>Subject</emphasis> and its
<emphasis>Principals</emphasis> (roles) assigned by previous
+ <emphasis>LoginModule</emphasis>s and try to synchronize them.
Roles assigned to authenticated user by
+ <emphasis>LoginModule</emphasis>s after it won't be
handled.
+ </listitem>
+ </itemizedlist>
+ </para>
</sect1>
<sect1>
<title>Supported LDAP servers</title>
- <para>LDAP servers support depends on few conditions. In most cases thy
differ in schema support - various objectClass
+ <para>LDAP servers support depends on few conditions. In most cases they
differ in schema support - various objectClass
objects are not present by default in server schema. Sometimes it can be
workarounded by manually
extending schema.</para>
<para>