17.2. Identity configuration

In order to understand identity configuration you need to understand its architecture. Different identity services like UserModule, RoleModule and etc are just plain Java classes that are instantiated and exposed by the portal. So an *example* of UserModule service could be a plain Java bean object that would be:
  • Instantiated using reflection
  • Initialized/Started by invoking some methods
  • Registered/Exposed using JNDI and/or mbeans (JBoss Microkernel) services, so other services of the portal can use it
  • Managed in the matter of lifecycle - so it'll be stopped and unregistered during portal shutdown
As you see from this point of view, configuration just specifies what Java class will be used and how it should be used by portal as a service.

Note

We use JBoss Microcontainer internally to manage the sub system made of those components so if you are interested in implementing custom services - look on the methods that are used by this framework.
In JBoss Portal we provide a very flexible configuration. It is very easy to rearrange and customize services, provide alternative implementations, extend the existing ones or provide a custom identity model.
To grasp the full picture of the configuration of identity services let's start from its root component. Whole configuration and setup of identity components is done by the IdentityServiceController service. It brings to life and registers all other services such as UserModule, RoleModule, MembershipModule and UserProfileModule. IdentityServiceController is defined in jboss-portal.sar/META-INF/jboss-service.xml
<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>
   <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>
We can specify a few options here:
  • RegisterMBeans - defines if IdentityServiceController should register components which are instantiated as mbeans
  • ConfigFile - defines the location of the main identity services configuration file. It describes and configures all the components like UserModule, RoleModule... that need to be instantiated
  • DefaultConfigFile - defines the location of the configuration file containing the default values. For each component defined in ConfigFile, the IdentityServiceController will obtain a set of default options from this file. That helps to keep the main main configuration file simple, short and easy to read. Potentially it provides more powerful customizations.

17.2.1. Main configuration file architecture (identity-config.xml)

The file describing portal identity services contains three sections:
<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>
By default you can find it in jboss-portal.sar/conf/identity/identity-config.xml

17.2.1.1. Datasources

This section defines datasource components. They will be processed and instantiated before components in Module section, so they will be ready to serve them.

Note

This section isn't used with Database configuration as in JBoss Portal services exposing Hibernate are defined separately. It is used by LDAP configuration and we will use it as an example
<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>

Note

If you look into JBoss Portal configuration files you will find that <service-name/> and <class/> are specified in DefaultConfigFile and not in ConfigFile. So here is how it works: those two will be picked up from default configuration. The same rule is effective for the options - additional options will be picked up from default configuration. What is linking configuration in those two files is the <name> tag.

17.2.1.2. Modules

Modules are core service components like UserModule, RoleModule and etc.
<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 in the instantiated object-->
   <config>
      <option>
         <name>sessionFactoryJNDIName</name>
         <value>java:/portal/IdentitySessionFactory</value>
      </option>
      <option>
         <name>jNDIName</name>
         <value>java:/portal/UserModule</value>
      </option>
   </config>
</module>
  • implementation - defines the scope under which the configuration for different implementations of modules types resides. It enables to define the default options of the configuration of the different implementations of same module types in one configuration file.
  • type - 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 at runtime. Standard names are used (User, Role, Membership, UserProfile). Together with implementation will create unique pair within file with default configuration values.
  • service-name - will be used for the name when registered as an MBean.
  • class - Java class that will be use to instantiate the module.
  • config - contains options related to this module

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 standardidentity-config.xml, 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:
<module>
   <!--type used to correctly map in IdentityContext registry-->
   <type>User</type>
   <implementation>DB</implementation>
   <config/>
</module>
As you can see we specify only the type and the implementation - all the other values (service-name, class and set of options) are read from default configuration. But remember that you can still overwrite any of those values in the main config simply by overriding them.

17.2.1.3. Options

This section provides common options that are accessible by identity modules. We set options here that may need to be shared. They are grouped, and can have many values:
<options>
<!--Common options section-->
<option-group>
   <group-name>common</group-name>
   <option>
      <name>userCtxDN</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>roleCtxDN</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>

Note

In this section we use the same inheritance mechanism. When an option is not set, its value will be read from the default config file. But this also means that you may need to overwrite some values that are specific to your LDAP architecture. All the options will be described along with module implementations that use them.