10:37 a.m.
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>