Author: bdaw
Date: 2007-01-31 18:48:33 -0500 (Wed, 31 Jan 2007)
New Revision: 6134
Modified:
docs/trunk/referenceGuide/en/modules/identity.xml
Log:
some more stuff about identity
Modified: docs/trunk/referenceGuide/en/modules/identity.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-31 15:51:38 UTC (rev 6133)
+++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-31 23:48:33 UTC (rev 6134)
@@ -1,29 +1,29 @@
<chapter id="identity">
- <chapterinfo>
- <author>
- <firstname>Boleslaw</firstname>
- <surname>Dawidowicz</surname>
- <email>boleslaw.dawidowicz at jboss dot com</email>
- </author>
- </chapterinfo>
- <title>JBoss Portal Identity management</title>
- <para>This chapter addresses identity management in JBoss Portal
2.6</para>
- <sect1 id="management_api">
- <title>Identity management API</title>
- <para>Since JBoss Portal 2.6 there are 4 identity services and 2 identity
related interfaces. The goal of
- having such a fine grained API is to enable flexible implementations based on
different
- identity storage like relational databases or LDAP servers. The Membership
service takes care of managing the relationship
- between user objects and role objects. The User Profile service is
responsible for managing the profile of a user,
- it has database and LDAP implementations as well as a mode that combines data
from both.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <emphasis
role="bold">org.jboss.portal.identity.User</emphasis>
- interface represents a user and exposes the following operations:
- </para>
- <programlisting>
- <![CDATA[
+ <chapterinfo>
+ <author>
+ <firstname>Boleslaw</firstname>
+ <surname>Dawidowicz</surname>
+ <email>boleslaw.dawidowicz at jboss dot com</email>
+ </author>
+ </chapterinfo>
+ <title>JBoss Portal Identity management</title>
+ <para>This chapter addresses identity management in JBoss Portal
2.6</para>
+ <sect1 id="management_api">
+ <title>Identity management API</title>
+ <para>Since JBoss Portal 2.6 there are 4 identity services and 2 identity
related interfaces. The goal of
+ having such a fine grained API is to enable flexible implementations based on
different
+ identity storage like relational databases or LDAP servers. The Membership
service takes care of managing the relationship
+ between user objects and role objects. The User Profile service is responsible
for managing the profile of a user,
+ it has database and LDAP implementations as well as a mode that combines data
from both.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">org.jboss.portal.identity.User</emphasis>
+ interface represents a user and exposes the following operations:
+ </para>
+ <programlisting>
+ <![CDATA[
/** The user identifier. */
public Object getId();
@@ -36,11 +36,11 @@
/** Return true if the password is valid. */
public boolean validatePassword(String password);
]]>
- </programlisting>
- <warning>
- Important Note! The proper usage of getId() method is:
- <programlisting>
- <![CDATA[
+ </programlisting>
+ <warning>
+ Important Note! The proper usage of getId() method is:
+ <programlisting>
+ <![CDATA[
// Always use it like this:
user.getId().toString();
@@ -52,19 +52,19 @@
// We would get a String with an LDAP server
(String)user.getId();
]]>
- </programlisting>
- This is because the ID value depends on the User implementation.
It'll probably be String object with the LDAP
- implementation and a Long object with the database implementation but
it could be something else
- if one has chosen to make its own implementation.
- </warning>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">org.jboss.portal.identity.Role</emphasis> interface
represents a Role
- and exposes the following operations:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ This is because the ID value depends on the User implementation. It'll
probably be String object with the LDAP
+ implementation and a Long object with the database implementation but it
could be something else
+ if one has chosen to make its own implementation.
+ </warning>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">org.jboss.portal.identity.Role</emphasis> interface
represents a Role
+ and exposes the following operations:
+ </para>
+ <programlisting>
+ <![CDATA[
/** The role identifier. */
public Object getId();
@@ -77,15 +77,15 @@
/** */
public void setDisplayName(String name);
]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">org.jboss.portal.identity.UserModule</emphasis>
- interface exposes operations for users management:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">org.jboss.portal.identity.UserModule</emphasis>
+ interface exposes operations for users management:
+ </para>
+ <programlisting>
+ <![CDATA[
/**Retrieve a user by its name.*/
User findUserByUserName(String userName) throws IdentityException,
IllegalArgumentException, NoSuchUserException;
@@ -110,15 +110,15 @@
/**Returns the number of users.*/
int getUserCount() throws IdentityException, IllegalArgumentException;
]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">org.jboss.portal.identity.RoleModule</emphasis>
- interface exposes operations for roles management:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">org.jboss.portal.identity.RoleModule</emphasis>
+ interface exposes operations for roles management:
+ </para>
+ <programlisting>
+ <![CDATA[
/** Retrieves a role by its name*/
Role findRoleByName(String name) throws IdentityException,
IllegalArgumentException;
@@ -165,19 +165,19 @@
/** Get all the roles */
Set findRoles() throws IdentityException;
]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">MembershipModule</emphasis>
- interface exposes operations for obtaining or managing relationships
beetween users and roles.
- The role of this service is to decouple relationship information from
user and roles.
- Indeed while user role relationship is pretty straightforward with a
relational database (using
- a many to many relationship with an intermediary table), with an LDAP
server there a different
- ways to define relationships between users and roles.
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">MembershipModule</emphasis>
+ interface exposes operations for obtaining or managing relationships
beetween users and roles.
+ The role of this service is to decouple relationship information from user
and roles.
+ Indeed while user role relationship is pretty straightforward with a
relational database (using
+ a many to many relationship with an intermediary table), with an LDAP
server there a different
+ ways to define relationships between users and roles.
+ </para>
+ <programlisting>
+ <![CDATA[
/** Return the set of role objects that a given user has.*/
Set getRoles(User user) throws IdentityException,
IllegalArgumentException;
@@ -192,15 +192,15 @@
/** Returns role members based on rolename - depreciated method ethod here
only for compatibility with old RoleModule interface */
Set findRoleMembers(String roleName, int offset, int limit, String
userNameFilter) throws IdentityException, IllegalArgumentException;
]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">UserProfileModule</emphasis>
- interface exposes operations to access and manage informations stored
in User profile:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis
role="bold">UserProfileModule</emphasis>
+ interface exposes operations to access and manage informations stored in
User profile:
+ </para>
+ <programlisting>
+ <![CDATA[
public Object getProperty(User user, String propertyName) throws
IdentityException, IllegalArgumentException;
public void setProperty(User user, String name, Object property) throws
IdentityException, IllegalArgumentException;
@@ -209,36 +209,36 @@
public ProfileInfo getProfileInfo() throws IdentityException;
]]>
- </programlisting>
- <warning>
- UserProfileModule.getProperty() method returns an Object.
- In most cases with DB backend it will always be String object. But
normally you should check what
- object will be retreived using getProfileInfo() method.
- </warning>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">ProfileInfo</emphasis>
- interface can be obtained using the
- <emphasis
role="bold">UserProfileModule</emphasis>
- and exposes meta information of a profile:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ <warning>
+ UserProfileModule.getProperty() method returns an Object.
+ In most cases with DB backend it will always be String object. But
normally you should check what
+ object will be retreived using getProfileInfo() method.
+ </warning>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis role="bold">ProfileInfo</emphasis>
+ interface can be obtained using the
+ <emphasis role="bold">UserProfileModule</emphasis>
+ and exposes meta information of a profile:
+ </para>
+ <programlisting>
+ <![CDATA[
/** Returns a Map o PropertyInfo objects describing profile properties
*/
public Map getPropertiesInfo();
public PropertyInfo getPropertyInfo(String name);
]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">PropertyInfo</emphasis>
- interface expose methods to obtain information about accessible
property in User profile
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">PropertyInfo</emphasis>
+ interface expose methods to obtain information about accessible property
in User profile
+ </para>
+ <programlisting>
+ <![CDATA[
public static final String ACCESS_MODE_READ_ONLY =
"read-only";
public static final String ACCESS_MODE_READ_WRITE =
"read-write";
public static final String USAGE_MANDATORY = "mandatory";
@@ -268,73 +268,73 @@
public boolean isMappedLDAP();
]]>
- </programlisting>
- </listitem>
+ </programlisting>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <sect2>
- <title>Ways to access identity modules</title>
- <para>
- The best way to access identity modules is by using JNDI:
- </para>
- <programlisting>
- import org.jboss.portal.identity.UserModule;
- import org.jboss.portal.identity.RoleModule;
- import org.jboss.portal.identity.MembershipModule;
- import org.jboss.portal.identity.UserProfileModule;
+ <sect2>
+ <title>Ways to access identity modules</title>
+ <para>
+ The best way to access identity modules is by using JNDI:
+ </para>
+ <programlisting>
+ import org.jboss.portal.identity.UserModule;
+ import org.jboss.portal.identity.RoleModule;
+ import org.jboss.portal.identity.MembershipModule;
+ import org.jboss.portal.identity.UserProfileModule;
- [...]
+ [...]
- (UserModule)new
InitialContext().lookup("java:portal/UserModule");
- (RoleModule)new
InitialContext().lookup("java:portal/RoleModule");
- (MembershipModule)new
InitialContext().lookup("java:portal/MembershipModule");
- (UserProfileModule)new
InitialContext().lookup("java:portal/UserProfileModule");
+ (UserModule)new InitialContext().lookup("java:portal/UserModule");
+ (RoleModule)new InitialContext().lookup("java:portal/RoleModule");
+ (MembershipModule)new
InitialContext().lookup("java:portal/MembershipModule");
+ (UserProfileModule)new
InitialContext().lookup("java:portal/UserProfileModule");
- </programlisting>
- <para>
- Another way to do this is, if you are fimiliar with JBoss Mikrokernel
architecture is to
- get the <emphasis
role="bold">IdentityServiceController</emphasis>
- mbean. You may want to inject it into your services like this:
- </para>
- <programlisting>
- <![CDATA[<depends
optional-attribute-name="IdentityServiceController"
proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]>
- </programlisting>
- <para>
- or simply obtain in your code by doing a lookup using
- the <emphasis
role="bold">portal:service=Module,type=IdentityServiceController</emphasis>
- name. Please refer to the JBoss Application Server documentation if you
want to learn more
- about service MBeans. Once you obtained the object you can use it:
- </para>
+ </programlisting>
+ <para>
+ Another way to do this is, if you are fimiliar with JBoss Mikrokernel
architecture is to
+ get the <emphasis
role="bold">IdentityServiceController</emphasis>
+ mbean. You may want to inject it into your services like this:
+ </para>
+ <programlisting>
+ <![CDATA[<depends
optional-attribute-name="IdentityServiceController"
proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]>
+ </programlisting>
+ <para>
+ or simply obtain in your code by doing a lookup using
+ the <emphasis
role="bold">portal:service=Module,type=IdentityServiceController</emphasis>
+ name. Please refer to the JBoss Application Server documentation if you want
to learn more
+ about service MBeans. Once you obtained the object you can use it:
+ </para>
- <programlisting>
-
(UserModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_MODULE);
-
(RoleModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_ROLE_MODULE);
-
(MembershipModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);
-
(UserProfileModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);
- </programlisting>
+ <programlisting>
+
(UserModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_MODULE);
+
(RoleModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_ROLE_MODULE);
+
(MembershipModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);
+
(UserProfileModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);
+ </programlisting>
- </sect2>
- <sect2>
- <title>API changes since 2.4</title>
- <para>Because in JBoss Portal 2.4 there were only
- <emphasis role="bold">UserModule</emphasis>
- ,
- <emphasis role="bold">RoleModule</emphasis>
- ,
- <emphasis role="bold">User</emphasis>
- and
- <emphasis role="bold">Role</emphasis>
- interfaces some API usages changed. Here are the most important changes
you will need to aply to your
- code while migrating your aplication to 2.6:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- For the <emphasis
role="bold">User</emphasis> interface:
- </para>
- <programlisting>
- <![CDATA[
+ </sect2>
+ <sect2>
+ <title>API changes since 2.4</title>
+ <para>Because in JBoss Portal 2.4 there were only
+ <emphasis role="bold">UserModule</emphasis>
+ ,
+ <emphasis role="bold">RoleModule</emphasis>
+ ,
+ <emphasis role="bold">User</emphasis>
+ and
+ <emphasis role="bold">Role</emphasis>
+ interfaces some API usages changed. Here are the most important changes you
will need to aply to your
+ code while migrating your aplication to 2.6:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ For the <emphasis role="bold">User</emphasis>
interface:
+ </para>
+ <programlisting>
+ <![CDATA[
// Instead of: user.getEnabled()
userProfileModule.getProperty(user, User.INFO_USER_ENABLED);
@@ -372,14 +372,14 @@
// Instead of: user.getLastVisitDate()
userProfileModule.getProperty(user,
User.INFO_USER_LAST_LOGIN_DATE);]]>
- </programlisting>
- </listitem>
- <listitem>
- <para>
- The <emphasis
role="bold">RoleModule</emphasis> interface:
- </para>
- <programlisting>
- <![CDATA[
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis role="bold">RoleModule</emphasis>
interface:
+ </para>
+ <programlisting>
+ <![CDATA[
// Instead of
// RoleModule.findRoleMembers(String roleName, int offset, int limit,
String userNameFilter) throws IdentityException;
membershipModule.findRoleMembers(String roleName, int offset, int
limit, String userNameFilter)
@@ -391,24 +391,24 @@
// Instead of
// RoleModule.getRoles(User user) throws IdentityException;
membershipModule.getRoles(User user)]]>
- </programlisting>
- </listitem>
- </itemizedlist>
- </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[
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </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"
@@ -423,29 +423,29 @@
<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>
+ </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[
+ </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>
@@ -468,12 +468,12 @@
</config>
</datasource>
]]>
- </programlisting>
- <para>
- You also need to specify options for your LDAP tree (described in
configuration documentation) like those:
- </para>
- <programlisting>
- <![CDATA[
+ </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>
@@ -486,21 +486,313 @@
</option>
</option-group>
]]>
- </programlisting>
+ </programlisting>
- </sect1>
- <sect1>
- <title>Identity configuration</title>
- <para>TODO: About the format and architecture of identity configuration
files</para>
+ </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
+ by portal. So *example* UserModule service could be plain java bean object tha
will be:
+ <itemizedlist>
+ <listitem><emphasis
role="bold">Instantiated</emphasis> using relfection</listitem>
+ <listitem><emphasis
role="bold">Initialized/Started</emphasis> by invoking some
methods</listitem>
+ <listitem><emphasis
role="bold">Registered/Exposed</emphasis> using JNDI and/or mbeans
(JBoss Mikrokernel) services, so
+ other citizens of the portal can use it</listitem>
+ <listitem><emphasis
role="bold">Managed</emphasis> in the matter of lifecycle - so
it'll be stopped and unregistered during
+ portal shutdown</listitem>
+ </itemizedlist>
+ As you see from this standpoint configuration just specifies which java class
and how should be used by portal as a service.
+ <note>We use JBoss Microcontainer to manage state of those components so
if you are interested in implementation of
+ custom ones - look on the methods that are leveraged by this
framework.</note>
+ </para>
+ <para>
+ In JBoss Portal we provide very flexible configuration. It's very easy to
rearange and customize services,
+ provide and plug in own implementations, extend current ones or extend identity
model with own solutions using
+ provided configuration service.
+ </para>
+ <para>To have the complete picture of the configuration of identity services
let's start from it's root
+ component. Whole configuration and setup of identity components is made by
+ <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>
+ </para>
- </sect1>
- <sect1>
- <title>Identity modules implementations</title>
- <para>TODO:</para>
- </sect1>
- <sect1>
- <title>Possible configuration scenarios with LDAP and RDBMS</title>
- <para>TODO:</para>
- </sect1>
+ <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>
+ We can specify few options here:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">RegisterMBeans</emphasis> -
defines if IdentityServiceController should
+ register components which are instantiated as mbeans
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">ConfigFile</emphasis> -
defines location of main identity services configuration
+ file. It describes and configures all the components like UserModule,
RoleModule... that need to be
+ instantiated
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis
role="bold">DefaultConfigFile</emphasis> - defines location of
configuration file containing
+ default values. For each component defined in <emphasis
role="bold">ConfigFile</emphasis> IdentityServiceController
+ will look into this location to grab set of default options. This
simply makes the main configuration file
+ simpler and shorter while still enabling more powerfull customization.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <sect2>
+ <title>Main configuration file architecture
(identity-config.xml)</title>
+ <para>
+ The file describing portal identity services contains three sections:
+ </para>
+ <programlisting>
+ <![CDATA[
+ <identity-configuration>
+ <datasources>
+ <!-- Datasources section -->
+ <datasource> ... </datasource>
+ <datasource> ... </datasource>
+ ...
+ </datasources>
+ <modules>
+ <!-- Modules section -->
+ <module> ... </module>
+ <module> ... </module>
+ ...
+ </modules>
+ <options>
+ <!-- Options section -->
+ <option-group> ... </option-group>
+ <option-group> ... </option-group>
+ ...
+ </options>
+ </identity-configuration>
+ ]]>
+ </programlisting>
+ <sect3>
+ <title>Datasources</title>
+ <para>This section defines datasource components. They will be
processed and instantiated before components in
+ <emphasis role="bold">Module</emphasis> section, so
they will be ready to serve them.</para>
+ <note>This section isn't used whith Database configuration as in
JBoss Portal services exposing Hibernate
+ are defined separately. It's used by LDAP configuration and we'll use
it as an example</note>
+ <programlisting>
+ <![CDATA[
+ <datasource>
+ <name>LDAP</name>
+
<service-name>portal:service=Module,type=LDAPConnectionContext</service-name>
+
<class>org.jboss.portal.identity.ldap.LDAPConnectionContext</class>
+ <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>xxxxx</value>
+ </option>
+
+ <!-- Other options here.... -->
+
+ </config>
+ </datasource>
+ ]]>
+ </programlisting>
+ <note>If you look into JBoss Portal configuration files you will find
that <![CDATA[<service-name/> and <class/>]]>
+ are specified in <emphasis
role="bold">DefaultConfigFile</emphasis> and not in <emphasis
role="bold">ConfigFile</emphasis>.
+ So this is how it works. Those two will be picked up from default
configuration. The same rule takes place
+ for options - additional will be picked up from default configuration. Whats
linking configuration in those two files
+ is the <emphasis
role="bold"><![CDATA[<name>]]></emphasis>
tag.</note>
+ </sect3>
+ <sect3>
+ <title>Modules</title>
+ <para>Modules are core service components like UserModule, RoleModule
and etc. </para>
+ <programlisting>
+ <![CDATA[
+ <module>
+ <!--type used to correctly map in IdentityContext registry-->
+ <type>User</type>
+ <implementation>DB</implementation>
+
+ <!--name of service and class for creating mbean-->
+
<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-->
+ <config>
+ <option>
+ <name>sessionFactoryJNDIName</name>
+ <value>java:/portal/IdentitySessionFactory</value>
+ </option>
+ <option>
+ <name>jndiName</name>
+ <value>java:/portal/UserModule</value>
+ </option>
+ </config>
+ </module>
+ ]]>
+ </programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis
role="bold">implementation</emphasis> - defines the scope under which
+ configuration for different implementations of modules <emphasis
role="bold">type</emphasis>s are kept.
+ It enables to keep configurations of different implementations of
same module types in one configuration file
+ with default options.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">type</emphasis> - must
be unique name across all modules defined in the main
+ configuration file. This is important as module will be stored with
such name within IdentityContext
+ registry on runtime. Standard names are used (User, Role,
Membership, UserProfile). Together with
+ <emphasis
role="bold">implementation</emphasis> will create unique pair within
file with default configuration values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">service-name</emphasis>
- will be used for registration as an MBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">class</emphasis> - java
class that will be use to instantiate the module.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">config</emphasis> -
contains options related to this module
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>Here you can easily see the whole idea about having two config
files - main one and the one with default values.
+ The above code snippet with User module comes from <emphasis
role="bold">standardidentity-config.xml</emphasis>, so the file
+ that defines default configuration values. Because of this in the main
configuration file the definition of
+ User module will be as short as:
+ <programlisting>
+ <![CDATA[
+ <module>
+ <!--type used to correctly map in IdentityContext
registry-->
+ <type>User</type>
+ <implementation>DB</implementation>
+ <config/>
+ </module>
+ ]]>
+ </programlisting>
+ As you see we specify only type and implementation - all the other values
(service-name, class and set of options)
+ will be taken from default configuration. But remember that still you can
overwrite any of those values in the
+ main config simply by specifying them.
+ </note>
+
+ </sect3>
+ <sect3>
+ <title>Options</title>
+ <para>This section provides common options that are accessible by
identity modules. We put here options
+ that may need to be shared. They are groupped, and can have many
values:</para>
+ <programlisting>
+ <![CDATA[
+ <options>
+ <!--Common options section-->
+ <option-group>
+ <group-name>common</group-name>
+ <option>
+ <name>userContainerDN</name>
+ <value>ou=People,dc=example,dc=com</value>
+ </option>
+ <option>
+ <name>uidAttributeID</name>
+ <value>uid</value>
+ </option>
+ <option>
+ <name>passwordAttributeID</name>
+ <value>userPassword</value>
+ </option>
+ <option>
+ <name>roleContainerDN</name>
+ <value>ou=Roles,dc=example,dc=com</value>
+ </option>
+ <option>
+ <name>ridAttributeId</name>
+ <value>cn</value>
+ </option>
+ <option>
+ <name>roleDisplayNameAttributeID</name>
+ <value>cn</value>
+ </option>
+ <option>
+ <name>membershipAttributeID</name>
+ <value>member</value>
+ </option>
+ <option>
+ <name>membershipAttributeIsDN</name>
+ <value>true</value>
+ </option>
+ </option-group>
+ <option-group>
+ <group-name>userCreateAttibutes</group-name>
+ <option>
+ <name>objectClass</name>
+ <value>top</value>
+ <value>uidObject</value>
+ <value>person</value>
+ <value>inetUser</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>
+ <note>In this section we use the same inheritance mechanism. When
option is not set, it's value will be taken
+ from the default config file. But this also means that you need to overwrite
some values that
+ are specific for your LDAP architecture. All the options will be described
along with module implementations
+ that use them.</note>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Identity modules implementations</title>
+ <para>TODO:</para>
+ </sect1>
+ <sect1>
+ <title>Possible configuration scenarios with LDAP and RDBMS</title>
+ <para>TODO:</para>
+ </sect1>
+
</chapter>