Author: bdaw Date: 2007-03-03 11:37:49 -0500 (Sat, 03 Mar 2007) New Revision: 6499 Modified: docs/trunk/referenceGuide/en/master.xml docs/trunk/referenceGuide/en/modules/identity.xml Log: identity docs update Modified: docs/trunk/referenceGuide/en/master.xml =================================================================== --- docs/trunk/referenceGuide/en/master.xml 2007-03-03 14:44:29 UTC (rev 6498) +++ docs/trunk/referenceGuide/en/master.xml 2007-03-03 16:37:49 UTC (rev 6499) @@ -18,6 +18,7 @@ <!ENTITY themeandlayouts SYSTEM "modules/themeandlayouts.xml"> <!ENTITY identity SYSTEM "modules/identity.xml"> <!ENTITY authentication SYSTEM "modules/authentication.xml"> + <!ENTITY ldap SYSTEM "modules/ldap.xml"> <!ENTITY sso SYSTEM "modules/sso.xml"> <!ENTITY clustering SYSTEM "modules/clustering.xml"> <!ENTITY wsrp SYSTEM "modules/wsrp.xml"> @@ -67,7 +68,8 @@ <!-- theme/layout api --> &themeandlayouts; <!-- Identity --> &identity; <!-- Authentication --> &authentication; - <!-- SSO --> &sso; + <!-- LDAP --> &ldap; + <!-- SSO --> &sso; <!-- troubleshooting FAQ--> &troubleshooting; </book> Modified: docs/trunk/referenceGuide/en/modules/identity.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-03 14:44:29 UTC (rev 6498) +++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-03 16:37:49 UTC (rev 6499) @@ -370,145 +370,6 @@ </sect2> </sect1> <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. - 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> - <listitem> - <para>In - <emphasis role="bold">jboss-porta.sar/META-INF/jboss-service.xml</emphasis> - in section: - </para> - <programlisting><![CDATA[ -<mbean - code="org.jboss.portal.identity.IdentityServiceControllerImpl" - name="portal:service=Module,type=IdentityServiceController" - xmbean-dd="" - xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> - <xmbean/> - <depends>portal:service=Hibernate</depends> - <!--<depends>jboss.jca:service=DataSourceBinding,name=@portal.datasource.name@</depends>--> - <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> - <attribute name="RegisterMBeans">true</attribute> - <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> - <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> -</mbean>]]></programlisting> - <para> - change - <emphasis role="bold">identity-config.xml</emphasis> - to - <emphasis role="bold">ldap_identity-config.xml</emphasis> - </para> - </listitem> - <listitem> - <para>Swap the names or content of files in - <emphasis role="bold">jboss-porta.sar/conf/identity/identity-config.xml</emphasis> - and - <emphasis role="bold">jboss-porta.sar/conf/identity/ldap_identity-config.xml</emphasis> - - </para> - </listitem> - </itemizedlist> - <para> - After doing on of above changes you need to edit configuration file that you choose to - use (identity-config.xml or ldap_identity-config.xml) and configure LDAP connection options in section: - </para> - <programlisting><![CDATA[ -<datasource> - <name>LDAP</name> - <config> - <option> - <name>host</name> - <value>jboss.com</value> - </option> - <option> - <name>port</name> - <value>10389</value> - </option> - <option> - <name>adminDN</name> - <value>cn=Directory Manager</value> - </option> - <option> - <name>adminPassword</name> - <value>qpq123qpq</value> - </option> - </config> -</datasource>]]></programlisting> - <para> - You also need to specify options for your LDAP tree (described in configuration documentation) like those: - </para> - <programlisting><![CDATA[ -<option-group> - <group-name>common</group-name> - <option> - <name>userCtxDN</name> - <value>ou=People,dc=portal26,dc=jboss,dc=com</value> - </option> - <option> - <name>roleCtxDN</name> - <value>ou=Roles,dc=portal26,dc=jboss,dc=com</value> - </option> -</option-group>]]></programlisting> - - <note> - Under <emphasis role="bold">PORTAL_SOURCES/identity/src/resources/example/</emphasis> you can find a sample ldif that - you can use to populate LDAP server and quickly start playing with it. - </note> - - </sect1> - <sect1> - <title>Configuration of LDAP connection</title> - <sect2> - <title>SSL</title> - <para>The setup is very similar to the one described in LdapLoginModule <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule"&g... page</ulink></para> - <para>You need to modify your identity configuration file and add "protocol"</para> - <programlisting><![CDATA[ -<datasource> - <name>LDAP</name> - <config> - ... - <option> - <name>protocol</name> - <value>ssl</value> - </option> - ... - </config> -</datasource>]]></programlisting> - <para> - Then you need to have LDAP server certificate imported into your keystore. You can use following command: - <programlisting>keytool -import -file ldapcert.der -keystore ldap.truststore</programlisting> - </para> - <para> - Now you need to change the settings to use the alternative truststore. That can be done in the properties-service.xml in deploy directory: - <programlisting><![CDATA[ -<attribute name="Properties"> - javax.net.ssl.trustStore=../some/path/to/ldap.truststore - javax.net.ssl.trustStorePassword=somepw -</attribute>]]></programlisting> - </para> - </sect2> - <sect2> - <title>ExternalContext</title> - <para>Instead of configuring your own connection you can use JNDI context federation mechanism in JBoss Application Server. Configuration of - ExternalContext is described in <ulink url="http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_singl... Application Server documentation</ulink></para> - <para>When you have ExternalContext configured you can use it in JBoss Portal by providing proper JNDI name in the configuration: - <programlisting><![CDATA[ -<datasource> - <name>LDAP</name> - <config> - <option> - <name>externalContextJndiName</name> - <value>external/ldap/jboss</value> - </option> - </config> -</datasource>]]></programlisting> - <note>When using "externalContextJndiName" you don't need to specify any other option for this datasource</note> - </para> - </sect2> - </sect1> - <sect1> <title>Identity configuration</title> <para>At the beginning to understand identity configuration you need to understand how it is designed to work in portal. Different identity services like UserModule, RoleModule and etc are just plain java classes that are instantiated and exposed @@ -535,7 +396,7 @@ <emphasis role="bold">IdentityServiceController</emphasis>. It brings to life and registers all other components like UserModule, RoleModule, MembershipModule and UserProfileModule. <emphasis role="bold">IdentityServiceController</emphasis> is defined in - <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis> + <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis> </para> <programlisting><![CDATA[ @@ -604,6 +465,7 @@ ... </options> </identity-configuration>]]></programlisting> + <para>By default you can find it in <emphasis>jboss-portal.sar/conf/identity/identity-config.xml</emphasis></para> <sect3> <title>Datasources</title> <para>This section defines datasource components. They will be processed and instantiated before components in @@ -656,7 +518,7 @@ <service-name>portal:service=Module,type=User</service-name> <class>org.jboss.portal.identity.db.HibernateUserModuleImpl</class> - <!--set of options that are passed to a class constructor--> + <!--set of options that are in the instantiated object--> <config> <option> <name>sessionFactoryJNDIName</name> @@ -788,7 +650,130 @@ </sect1> <sect1> <title>User profile configuration</title> - <para>TODO:</para> + <para>UserProfileModule has additional configuration file that defines user properties. It is specified in configuration in:</para> + <programlisting> + <![CDATA[ + <module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + + (...) + + <config> + + (...) + + <option> + <name>profileConfigFile</name> + <value>conf/identity/profile-config.xml</value> + </option> + </config> + </module> + ]]> + </programlisting> + <para>This means that you can configure user profile in <emphasis>jboss-portal.sar/conf/identity/profile-config.xml</emphasis></para> + <para> + <programlisting> + <![CDATA[ +<profile> + + <property> + <name>user.name.nickName</name> + <type>java.lang.String</type> + <access-mode>read-only</access-mode> + <usage>mandatory</usage> + <display-name xml:lang="en">Name</display-name> + <description xml:lang="en">The user name</description> + <mapping> + <database> + <type>column</type> + <value>jbp_uname</value> + </database> + </mapping> + </property> + + <property> + <name>user.business-info.online.email</name> + <type>java.lang.String</type> + <access-mode>read-write</access-mode> + <usage>mandatory</usage> + <display-name xml:lang="en">Email</display-name> + <description xml:lang="en">The user real email</description> + <mapping> + <database> + <type>column</type> + <value>jbp_realemail</value> + </database> + <ldap> + <value>mail</value> + </ldap> + </mapping> + </property> + + <property> + <name>portal.user.location</name> + <type>java.lang.String</type> + <access-mode>read-write</access-mode> + <usage>optional</usage> + <display-name xml:lang="en">Location</display-name> + <description xml:lang="en">The user location</description> + <mapping> + <database> + <type>dynamic</type> + <value>portal.user.location</value> + </database> + </mapping> + </property> + + (...) + +</properties> + ]]> + </programlisting> + Configuration file contains properties definition that can be retreived using <emphasis role="bold">PropertyInfo</emphasis> interface. + Every property that will be used in portal need to be registered here. + <note>Some informations provided for property have big influence on the behaviour of UserProfileModule. For example + <emphasis>access-mode</emphasis> can made property read-only, and value provided in <emphasis>type</emphasis> will be checked + during <emphasis>setProperty()/getProperty()</emphasis> operations. On the other hand tags like <emphasis>usage</emphasis>, + <emphasis>description</emphasis> or <emphasis>display-name</emphasis> have mostly informational meaning at the moment</note> + <itemizedlist> + <listitem> + <emphasis role="bold">name</emphasis> - property name. This value will be used to refer to the property in <emphasis>UserProfileModule</emphasis> + </listitem> + <listitem> + <emphasis role="bold">type</emphasis> - java type of property. This type will be checked when in <emphasis>UserProfileModule</emphasis> + methods invocation. + </listitem> + <listitem> + <emphasis role="bold">access-mode</emphasis> - possible values are <emphasis>read-write</emphasis> and <emphasis>read-only</emphasis> + </listitem> + + <listitem> + <emphasis role="bold">usage</emphasis> - property usage can be <emphasis>mandatory</emphasis> or <emphasis>optional</emphasis>. + </listitem> + + <listitem> + <emphasis role="bold">display-name</emphasis> - property display name. + </listitem> + + <listitem> + <emphasis role="bold">description</emphasis> - description of property. + </listitem> + + <listitem> + <emphasis role="bold">mapping</emphasis> - defines how property is mapped in the underlaying storage mechanism. It can be mapped in <emphasis>database</emphasis> + either as a <emphasis>column</emphasis> or <emphasis>dynamic</emphasis> value. It can also be mapped as <emphasis>ldap</emphasis> attribute. + <note>In current implementation <emphasis>column</emphasis> and <emphasis>dynamic</emphasis> mappings have the same effect, as database mappings are defined + in hibernate configuration.</note> + <note>Property can have both <emphasis>ldap</emphasis> and <emphasis>database</emphasis> mappings. In such situation when LDAP support is enabled <emphasis>ldap</emphasis> mapping will take precedense. + Also even when using ldap some properties will be mapped to ldap and some to database. Its because LDAP schema doesn't support all attributes proper + to for portal properties. To solve this we have <emphasis role="bold">DelegatingUserProfileModuleImpl</emphasis> that will delegate method invocation to + <emphasis>ldap</emphasis> or <emphasis>database</emphasis> related <emphasis>UserProfile</emphasis> module. When <emphasis>LDAP</emphasis> support is enabled and + property need to be stored in database user will be synchronized into database when needed. This behaviour can be configured.</note> + </listitem> + </itemizedlist> + + </para> </sect1> <sect1> <title>Identity modules implementations</title> @@ -798,5 +783,5 @@ <title>Possible configuration scenarios with LDAP and RDBMS</title> <para>TODO:</para> </sect1> - + </chapter>