[portal-commits] JBoss Portal SVN: r6539 - docs/trunk/referenceGuide/en/modules.

Author: bdaw Date: 2007-03-05 08:40:33 -0500 (Mon, 05 Mar 2007) New Revision: 6539 Modified: docs/trunk/referenceGuide/en/modules/ldap.xml Log: anorther part of ldap chapter Modified: docs/trunk/referenceGuide/en/modules/ldap.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-05 13:22:46 UTC (rev 6538) +++ docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-05 13:40:33 UTC (rev 6539) @@ -153,33 +153,162 @@ <title>LDAP Identity Modules</title> <para>TODO:</para> <sect2> + <title>Common settings</title> + <para>For all modules you can set two config options: + <itemizedlist> + <listitem> + <emphasis role="bold">jndiName</emphasis> - JNDI name under which this module will be registered + </listitem> + <listitem> + <emphasis role="bold">connectionJNDIName</emphasis> - JNDI name under which LDAP datasource is registered + </listitem> + </itemizedlist> + <note>Most configuration of LDAP identity modules is done in <emphasis>options</emphasis> section by adding module specific options + in <emphasis>"common"</emphasis> option-group or in other module specific groups.</note> + </para> + </sect2> + <sect2> <title>UserModule</title> <sect3> <title>LDAPUserModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl options: + <para>This is the base implementation of LDAP <emphasis>UserModule</emphasis>. It supports user creation, but will retreive users and create them + in strictly specified place in LDAP tree.</para> + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">userCtxDN</emphasis> - DN that will be used as context for user searches + </listitem> + <listitem> + <emphasis role="bold">uidAttributeID</emphasis> - attribute name under which user name is specified. Default value is "uid" + </listitem> + <listitem> + <emphasis role="bold">passwordAttributeID</emphasis> - attribute name under which user password is specified. Default value is "userPassword" + </listitem> + <listitem> + <emphasis role="bold">principalDNPrefix</emphasis> and <emphasis role="bold">principalDNSuffix</emphasis> + </listitem> + <listitem> + <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the user searches. Defaults to 10000 (10 seconds). + </listitem> + </itemizedlist> </listitem> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">userCreateAttibutes</emphasis>: This option-group defines a set of ldap attributes that will be set on user entry creation. + Option name will be used as attribute name, and option values as attribute values. This enables to fulfill LDAP schema requirements. </listitem> </itemizedlist> + Example configuration: + <programlisting> + <![CDATA[ + <option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,o=portal,dc=my-domain,dc=com</value> + </option> + <option> + <name>uidAttributeID</name> + <value>uid</value> + </option> + <option> + <name>passwordAttributeID</name> + <value>userPassword</value> + </option> + </option-group> + <option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <!--This objectclasses should work with Red Hat Directory--> + <value>top</value> + <value>person</value> + <value>inetOrgPerson</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> + </option-group> + ]]> + </programlisting> + </para> </sect3> <sect3> <title>LDAPExtUserModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPExtUserModuleImpl options: + <para>This module doesn't support user creation and removal</para> + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPExtUserModuleImpl</class> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPExtUserModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">userCtxDN</emphasis> - DN that will be used as context for user searches + </listitem> + <listitem> + <emphasis role="bold">userSearchFilter</emphasis> - ldap filter to search users with. {0} will be substitute with user name. Example filter can look like this: + "(uid={0})". This substituion behavior comes from the standard <emphasis>DirContext.search(Name, String, Object, SearchControls cons)</emphasis> method + </listitem> + <listitem> + <emphasis role="bold">uidAttributeID</emphasis> - attribute name under which user name is specified. Default value is "uid" + </listitem> + <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. + <itemizedlist> + <listitem> + <emphasis role="bold">OBJECT_SCOPE</emphasis> - only search the named users context. + </listitem> + <listitem> + <emphasis role="bold">ONELEVEL_SCOPE</emphasis> - search directly under the named users context. + </listitem> + <listitem> + <emphasis role="bold">SUBTREE_SCOPE</emphasis> - If the users context is not a <emphasis>DirContext</emphasis>, search only the object. + 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> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> + </para> </sect3> </sect2> @@ -188,28 +317,94 @@ <sect3> <title>LDAPRoleModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPRoleModuleImpl options: + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>Role</type> + <implementation>LDAP</implementation> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPRoleModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">roleCtxDN</emphasis> - DN that will be used as context for role searches. + </listitem> + <listitem> + <emphasis role="bold">ridAttributeID</emphasis> - attribute name under which role name is specified. Default value is "cn". + </listitem> + <listitem> + <emphasis role="bold">roleDisplayNameAttributeID</emphasis> - attribute name under which role display name is specified. Default value is "cn". + </listitem> + <listitem> + <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the roles searches. Defaults to 10000 (10 seconds). + </listitem> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> </para> </sect3> <sect3> <title>LDAPExtRoleModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPExtRoleModuleImpl options: + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>Role</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPExtRoleModuleImpl</class> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPExtRoleModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">roleCtxDN</emphasis> - DN that will be used as context for role searches + </listitem> + <listitem> + <emphasis role="bold">roleSearchFilter</emphasis> - ldap filter to search roles with. {0} will be substitute with role name. Example filter can look like this: + "(cn={0})". This substituion behavior comes from the standard <emphasis>DirContext.search(Name, String, Object, SearchControls cons)</emphasis> method. + </listitem> + <listitem> + <emphasis role="bold">ridAttributeID</emphasis> - attribute name under which role name is specified. Default value is "cn". + </listitem> + <listitem> + <emphasis role="bold">roleDisplayNameAttributeID</emphasis> - attribute name under which role display name is specified. Default value is "cn". + </listitem> + <listitem> + <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the roles 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. + <itemizedlist> + <listitem> + <emphasis role="bold">OBJECT_SCOPE</emphasis> - only search the named roles context. + </listitem> + <listitem> + <emphasis role="bold">ONELEVEL_SCOPE</emphasis> - search directly under the named roles context. + </listitem> + <listitem> + <emphasis role="bold">SUBTREE_SCOPE</emphasis> - If the roles context is not a <emphasis>DirContext</emphasis>, search only the object. + If the roles context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself. + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> </para> </sect3> @@ -217,30 +412,71 @@ <sect2> <title>MembershipModule</title> <sect3> - <title>LDAPStaticRoleMembershipModuleImpl</title> + <title>LDAPStaticGroupMembershipModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl options: + <para>This module support tree shape where role entries keep information about users that are their members.</para> + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>Membership</type> + <implementation>LDAP</implementation> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPStaticGroupMembershipModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">membershipAttributeID</emphasis> - LDAP attribute that defines member users ids. This will be used to retreived users from role + entry. + </listitem> + <listitem> + <emphasis role="bold">membershipAttributeIsDN</emphasis> - defines if values of attribute defined in <emphasis>membershipAttributeID</emphasis> are fully qualified + LDAP DNs. + </listitem> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> </para> </sect3> <sect3> - <title>LDAPStaticGroupMembershipModuleImpl</title> + <title>LDAPStaticRoleMembershipModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPStaticGroupMembershipModuleImpl options: + <para>This module support tree shape where user entries keep information about roles that they belong to.</para> + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>Membership</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl</class> + <config/> + </module> + ]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">membershipAttributeID</emphasis> - LDAP attribute that defines role ids that user belongs to. This will be used to retreived roles + from user entry. + </listitem> + <listitem> + <emphasis role="bold">membershipAttributeIsDN</emphasis> - defines if values of attribute defined in <emphasis>membershipAttributeID</emphasis> are fully qualified + LDAP DNs. + </listitem> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> </para> </sect3> @@ -250,14 +486,49 @@ <sect3> <title>LDAPUserProfileModuleImpl</title> <para>TODO:</para> - <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl options: + <para>To enable it in your configuration you should have: + <programlisting> + <![CDATA[ + <module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + <config> + <option> + <name>ldapModuleJNDIName</name> + <value>java:/portal/LDAPUserProfileModule</value> + </option> + </config> + </module> + <module> + <type>DBDelegateUserProfile</type> + <implementation>DB</implementation> + <config> + <option> + <name>randomSynchronizePassword</name> + <value>true</value> + </option> + </config> + </module> + <module> + <type>LDAPDelegateUserProfile</type> + <implementation>LDAP</implementation> + <config/> + </module> + ]]> + </programlisting> + <note>Using such configuration you will have LDAP MembershipModule along with DB MembershipModule and Delegating MembershipModule</note> + </para> + <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl configuration option-groups options: <itemizedlist> <listitem> - <emphasis role="bold"></emphasis> - + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <emphasis role="bold">profileConfigFile</emphasis> - file with user profile configuration. If this option is not set, and we use delegating UserProfileModule, + profile configuration will be obtained from it. + </listitem> + </itemizedlist> </listitem> - <listitem> - <emphasis role="bold"></emphasis> - - </listitem> </itemizedlist> </para> </sect3> @@ -265,6 +536,7 @@ </sect1> <sect1> <title>LDAP server tree shapes</title> + <para>TODO:</para> </sect1> <sect1> <title>Supported LDAP servers</title>