Author: bdaw
Date: 2007-03-14 09:41:46 -0400 (Wed, 14 Mar 2007)
New Revision: 6664
Modified:
docs/trunk/referenceGuide/en/modules/authentication.xml
docs/trunk/referenceGuide/en/modules/identity.xml
docs/trunk/referenceGuide/en/modules/ldap.xml
Log:
ldap docs update
Modified: docs/trunk/referenceGuide/en/modules/authentication.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-14 12:21:56 UTC (rev
6663)
+++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-14 13:41:46 UTC (rev
6664)
@@ -183,7 +183,7 @@
</mbean>]]>
</programlisting>
</sect2>
- <sect2>
+ <sect2 id="authentication.synchronizing_login_module">
<title>org.jboss.portal.identity.auth.SynchronizingLoginModule</title>
<para>
This module is designed to provide synchronization support for any other
LoginModule placed in the authentication stack.
Modified: docs/trunk/referenceGuide/en/modules/identity.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-14 12:21:56 UTC (rev 6663)
+++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-14 13:41:46 UTC (rev 6664)
@@ -813,7 +813,7 @@
</itemizedlist>
</para>
</sect2>
- <sect2>
+ <sect2 id="identity.management_api">
<title>Delegating UserProfile module</title>
<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.
Modified: docs/trunk/referenceGuide/en/modules/ldap.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-14 12:21:56 UTC (rev 6663)
+++ docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-14 13:41:46 UTC (rev 6664)
@@ -169,6 +169,43 @@
</sect2>
<sect2>
<title>UserModule</title>
+ <para>
+ <table frame="all">
+ <title>Comparision of UserModule implementations</title>
+ <tgroup cols="3" align="left" colsep="1"
rowset="1">
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry align="center"
morerows="1">Features</entry>
+ <entry align="center" namest="c2"
nameend="c3">UserModule</entry>
+ </row>
+ <row>
+ <entry
align="center">LDAPUserModuleImpl</entry>
+ <entry
align="center">LDAPExtUserModuleImpl</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>User creation</entry>
+ <entry align="center">X</entry>
+ <entry align="center">-</entry>
+ </row>
+ <row>
+ <entry>User removal</entry>
+ <entry align="center">X</entry>
+ <entry align="center">-</entry>
+ </row>
+ <row>
+ <entry>User search</entry>
+ <entry align="center">Flat - one level
scope</entry>
+ <entry align="center">Flexible filter - sub tree
scope</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
<sect3>
<title>LDAPUserModuleImpl</title>
<para>TODO:</para>
@@ -290,8 +327,8 @@
<listitem>
<emphasis
role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds
for the user searches. Defaults to 10000 (10 seconds).
</listitem>
- <listitem>
- <emphasis
role="bold">searchScope</emphasis> - Sets the search scope to one of
the strings. The default is SUBTREE_SCOPE.
+ <!--<listitem>
+ <emphasis
role="bold">searchScope</emphasis> - Sets the search scope to one of
the strings. The default is SUBTREE_SCOPE.
<itemizedlist>
<listitem>
<emphasis
role="bold">OBJECT_SCOPE</emphasis> - only search the named users
context.
@@ -304,7 +341,7 @@
If the users context is a
<emphasis>DirContext</emphasis>, search the subtree rooted at the named
object, including the named object itself.
</listitem>
</itemizedlist>
- </listitem>
+ </listitem>-->
</itemizedlist>
</listitem>
</itemizedlist>
@@ -314,9 +351,47 @@
</sect2>
<sect2>
<title>RoleModule</title>
+ <para>
+ <table frame="all">
+ <title>Comparision of RoleModule implementations</title>
+ <tgroup cols="3" align="left" colsep="1"
rowset="1">
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry align="center"
morerows="1">Features</entry>
+ <entry align="center" namest="c2"
nameend="c3">RoleModule</entry>
+ </row>
+ <row>
+ <entry
align="center">LDAPRoleModuleImpl</entry>
+ <entry
align="center">LDAPExtRoleModuleImpl</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Role creation</entry>
+ <entry align="center">X</entry>
+ <entry align="center">-</entry>
+ </row>
+ <row>
+ <entry>Role removal</entry>
+ <entry align="center">X</entry>
+ <entry align="center">-</entry>
+ </row>
+ <row>
+ <entry>Role search</entry>
+ <entry align="center">Flat - one level
scope</entry>
+ <entry align="center">Flexible filter - sub tree
scope</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
<sect3>
<title>LDAPRoleModuleImpl</title>
<para>TODO:</para>
+ <para>This module doesn't support role creation and
removal</para>
<para>To enable it in your configuration you should have:
<programlisting>
<![CDATA[
@@ -408,9 +483,62 @@
</itemizedlist>
</para>
</sect3>
+ <note>In <emphasis>UserModule</emphasis> there are two methods
that handle offset/limit (pagination) behaviour.
+ <programlisting>
+ <![CDATA[
+ /** Get a range of users.*/
+ Set findUsers(int offset, int limit) throws IdentityException,
IllegalArgumentException;
+
+ /** Get a range of users.*/
+ Set findUsersFilteredByUserName(String filter, int offset, int limit)
throws IdentityException, IllegalArgumentException;
+ ]]>
+ </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.
+ 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.
+ </note>
</sect2>
<sect2>
<title>MembershipModule</title>
+ <para>
+ <table frame="all">
+ <title>Comparision of MembershipModule
implementations</title>
+ <tgroup cols="3" align="left" colsep="1"
rowset="1">
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry align="center"
morerows="1">Features</entry>
+ <entry align="center" namest="c2"
nameend="c3">MembershipModule</entry>
+ </row>
+ <row>
+ <entry
align="center">LDAPStaticGroupMembershipModuleImpl</entry>
+ <entry
align="center">LDAPStaticRoleMembershipModuleImpl</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Role assignment stored in LDAP role
entry</entry>
+ <entry align="center">X</entry>
+ <entry align="center">-</entry>
+ </row>
+ <row>
+ <entry>Role assignment stored in LDAP user
entry</entry>
+ <entry align="center">-</entry>
+ <entry align="center">X</entry>
+ </row>
+ <row>
+ <entry>User/Role relationship creation</entry>
+ <entry align="center">X</entry>
+ <entry align="center">X</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
<sect3>
<title>LDAPStaticGroupMembershipModuleImpl</title>
<para>TODO:</para>
@@ -516,7 +644,9 @@
</module>
]]>
</programlisting>
- <note>Using such configuration you will have LDAP MembershipModule
along with DB MembershipModule and Delegating MembershipModule</note>
+ <note>Using such configuration you will have LDAP MembershipModule
along with DB MembershipModule and Delegating MembershipModule. Please read
+ <link
linkend="identity.management_api">Identity</link> chapter to see why
this is important.
+ </note>
</para>
<para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl configuration
option-groups options:
<itemizedlist>
@@ -536,46 +666,171 @@
</sect1>
<sect1>
<title>LDAP server tree shapes</title>
- <para>TODO:</para>
- <para>Tree:
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle"
fileref="images/ldap/tree1-1.png"/>
- </imageobject>
- </mediaobject>
+ <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.
+ 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.
</para>
- <para>Tree:
+ <sect2>
+ <title>Keeping users membership in role entries</title>
+ <para>TODO></para>
+ <para>Tree:
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/ldap/tree1-1.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Tree:
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/ldap/tree1-2.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Example LDIF:
+ <programlisting>
+ <![CDATA[
+dn: dc=example,dc=com
+objectclass: top
+objectclass: dcObject
+objectclass: organization
+dc: example
+o: example
+
+dn: ou=People,dc=example,dc=com
+objectclass: top
+objectclass: organizationalUnit
+ou: People
+
+dn: uid=user,ou=People,dc=example,dc=com
+objectclass: top
+objectclass: inetOrgPerson
+objectclass: person
+uid: user
+cn: JBoss Portal user
+sn: user
+userPassword: user
+mail: email(a)email.com
+
+dn: ou=Roles,dc=example,dc=com
+objectclass: top
+objectclass: organizationalUnit
+ou: Roles
+
+dn: cn=User,ou=Roles,dc=example,dc=com
+objectClass: top
+objectClass: groupOfNames
+cn: User
+description: the JBoss Portal user group
+member: uid=user,ou=People,dc=example,dc=com
+ ]]>
+ </programlisting>
+ </para>
+ <para>Example identity configuration:
+ <programlisting>
+ <![CDATA[
+
+ ]]>
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Keeping users membership in user entries</title>
+ <!--<para>Tree:
<mediaobject>
<imageobject>
- <imagedata align="center" valign="middle"
fileref="images/ldap/tree1-2.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <!--<para>Tree:
- <mediaobject>
- <imageobject>
<imagedata align="center" valign="middle"
fileref="images/ldap/tree2-1.png"/>
</imageobject>
</mediaobject>
</para>-->
- <para>Tree:
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle"
fileref="images/ldap/tree2-3.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>Tree:
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle"
fileref="images/ldap/tree2-4.png"/>
- </imageobject>
- </mediaobject>
- </para>
+ <para>Tree:
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/ldap/tree2-3.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Tree:
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/ldap/tree2-4.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Example LDIF:
+ <programlisting>
+ <![CDATA[
+dn: dc=example,dc=com
+objectclass: top
+objectclass: dcObject
+objectclass: organization
+dc: example
+o: example
+
+dn: o=example2,dc=example,dc=com
+objectclass: top
+objectclass: organization
+o: example2
+
+dn: ou=People,o=example2,dc=example,dc=com
+objectclass: top
+objectclass: organizationalUnit
+ou: People
+
+dn: uid=admin,ou=People,o=example2,dc=example,dc=com
+objectclass: top
+objectclass: inetOrgPerson
+objectclass: inetUser
+uid: admin
+cn: JBoss Portal admin
+sn: admin
+userPassword: admin
+mail: email(a)email.com
+memberOf: cn=Admin,ou=Roles,o=example2,dc=example,dc=com
+
+dn: ou=Roles,o=example2,dc=example,dc=com
+objectclass: top
+objectclass: organizationalUnit
+ou: Roles
+
+dn: cn=Admin,ou=Roles,o=example2,dc=example,dc=com
+objectClass: top
+objectClass: organizationalRole
+cn: Echo
+description: the JBossAdmin group
+ ]]>
+ </programlisting>
+ </para>
+ <para>Example identity configuration:
+ <programlisting>
+ <![CDATA[
+
+ ]]>
+ </programlisting>
+ </para>
+ </sect2>
</sect1>
<sect1>
<title>Supported LDAP servers</title>
- <para></para>
+ <para>LDAP servers support depends on few conditions. In most cases thy
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>
+ Servers can be
+ <itemizedlist>
+ <listitem><emphasis>Supported</emphasis></listitem>
+ <listitem><emphasis>Not
Supported</emphasis></listitem>
+ <listitem><emphasis>Experimental</emphasis> -
implementation can work with such server but it's not well tested so
+ shouldn't be considered for production.</listitem>
+ </itemizedlist>
+ </para>
<table frame="all">
<title>Support of identity modules with different LDAP
servers</title>
<tgroup cols="8" align="left" colsep="1"
rowset="1">
@@ -608,33 +863,33 @@
<tbody>
<row>
<entry>Red Hat Directory Server</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
</row>
<row>
<entry>OpenDS</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">-</entry>
- <entry align="center">X</entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry align="center"><emphasis>Not
Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
</row>
<row>
<entry>OpenLDAP</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">X</entry>
- <entry align="center">-</entry>
- <entry align="center">X</entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
+ <entry align="center"><emphasis>Not
Supported</emphasis></entry>
+ <entry
align="center"><emphasis>Supported</emphasis></entry>
</row>
<row>
<entry>Microsoft Active Directory</entry>