# Setting up Unified User Profiles

This topic provides guidelines and instructions on creating a unified user profile to access user/group properties from an external user store. (See Unified User Profiles Overview for overview information.)

To create a UUP to retrieve user data from external sources, complete the following tasks:

Create an EntityPropertyManager EJB to Represent External Data

Deploy a ProfileManager That Can Use the New EntityPropertyManager

If you have an LDAP server for which you want to create a unified user profile, WebLogic Portal provides a default unified user profile you can modify. See Retrieving User Profile Data from LDAP.

### Create an EntityPropertyManager EJB to Represent External Data

To incorporate data from an external source, you must first create a stateless session bean that implements the methods of the com.bea.p13n.property.EntityPropertyManager remote interface. EntityPropertyManager is the remote interface for a session bean that handles the persistence of property data and the creation and deletion of profile records. By default, EntityPropertyManager provides read-only access to external properties.

In addition, the stateless session bean should include a home interface and an implementation class. For example:

    MyEntityPropertyManager
    extends com.bea.p13n.property.EntityPropertyManager

    MyEntityPropertyManagerHome
    extends javax.ejb.EJBHome

Your implementation class can extend the EntityPropertyManagerImpl class. However the only requirement is that your implementation class is a valid implementation of the MyEntityPropertyManager remote interface. For example:

    MyEntityPropertyManagerImpl extends
    com.bea.p13n.property.internal.EntityPropertyManagerImpl

or

    MyEntityPropertyManagerImpl extends
    javax.ejb.SessionBean

#### Recommended EJB Guidelines

We recommend the following guidelines for your new EJB:

- Your custom EntityPropertyManager is not a default EntityPropertyManager. A default EntityPropertyManager is used to get/set/remove properties in the Portal schema. Your custom EntityPropertyManager does not have to support the following methods. It can throw java.lang.UsupportedOperationException instead:
  - getDynamicProperties()
  - getEntityNames()
  - getHomeName()
  - getPropertyLocator()
  - getUniqueId()
- If you want to be able to use the portal framework and tools to create and remove users in your external data store, you must support the createUniqueId() and removeEntity() methods. However, your custom EntityPropertyManager is not the default EntityPropertyManager so your createUniqueId() method does not have to return a unique number. It must create the user entity in your external data store and then it can return any number, such as -1.
- The following recommendations apply to the EntityPropertyManager() methods that you must support:
  - getProperty() - Use caching. You should support the getProperties() method to retrieve all properties for a user at once, caching them at the same time. Your getProperty() method should use getProperties().
  - setProperty() - Use caching.
  - removeProperties(), removeProperty() - After these methods are called, a call to getProperty() should return null for the property. Remove properties from the cache, too.
- Your implementations of the getProperty(), setProperty(), removeProperty(), and removeProperties() methods must include any logic necessary to connect to the external system.
- If you want to cache property data, the methods must be able to cache profile data appropriately for that system. (See the com.bea.p13n.cache package in the WebLogic Portal Javadoc.)
- If the external system contains read-only data, any methods that modify profile data must throw a java.lang.UnsupportedOperationException. Additionally, if the external data source contains users that are created and deleted by something other than your WebLogic Portal createUniqueId() and removeEntity() methods can simply throw an UnsupportedOperationException.
- To avoid class loader dependency issues, make sure that your EJB resides in its own package.
- For ease of maintenance, place the compiled classes of your custom EntityPropertyManager bean in your own JAR file (instead of modifying an existing WebLogic Portal JAR file).

Before you deploy your JAR file, follow the steps in the next section.

### Deploy a ProfileManager That Can Use the New EntityPropertyManager

A "user type" is a mapping of a ProfileType name to a particular ProfileManager. This mapping is done in the UserManager EJB deployment descriptor.

To access the data in your new EntityPropertyManager EJB, you must do one of the following:

- Modifying the Existing ProfileManager Deployment Configuration - In most cases you will be able to use the default deployment of ProfileManager, the UserProfileManager. You will modify the UserProfileManager's deployment descriptor to map a property set and/or properties to your custom EntityPropertyManager. If you support the createUniqueId() and removeEntity() methods in your custom EntityPropertyManager, you can use WebLogic Administration Portal to create a user of type "User" with a profile that can get/set properties using your custom EntityPropertyManager.
- Configuring and Deploying a New ProfileManager - In some cases you may want to deploy a newly configured ProfileManager that will be used instead of the UserProfileManager. This new ProfileManager is mapped to a ProfileType in the deployment descriptor for the UserManager. If you support the createUniqueId() and removeEntity() methods in your custom EntityPropertyManager, you can use the WebLogic Administration Portal (or API) to create a user of type "MyUser" (or anything else you name it) that can get/set properties using the customized deployment of the ProfileManager that is, in turn, configured to use your custom EntityPropertyManager.

ProfileManager is a stateless session bean that manages access to the profile values that the EntityPropertyManager EJB retrieves. It relies on a set of mapping statements in its deployment descriptor to find data. For example, the ProfileManager receives a request for the value of the "DateOfBirth" property, which is located in the "PersonalData" property set. ProfileManager uses the mapping statements in its deployment descriptor to determine which EntityPropertyManager EJB contains the data.

#### Modifying the Existing ProfileManager Deployment Configuration

If you use the existing UserProfileManager deployment to manage your user profiles, perform the following steps to modify the deployment configuration.

Under most circumstances, this is the method you should use to deploy your UUP. An example of this method is the deployment of the custom EntityPropertyManager for LDAP property retrieval, the LdapPropertyManager. The classes for the LdapPropertyManager are packaged in p13n_ejb.jar. The deployment descriptor for the UserProfileManager EJB is configured to map the "ldap" property set to the LdapPropertyManager. The UserProfileManager is deployed in p13n_ejb.jar.

1. Back up the p13n_ejb.jar file in your enterprise application root directory.
2. From p13n_ejb.jar, extract META-INF/ejb-jar.xml and open it for editing.
3. In ejb-jar.xml, find the <env-entry> element, as shown in the following example:

       <!-- map all properties in property set ldap to ldap server -->
       <env-entry>
           <env-entry-name>PropertyMapping/ldap</env-entry-name>
           <env-entry-type>java.lang.String</env-entry-type>
           <env-entry-value>LdapPropertyManager</env-entry-value>
       </env-entry>

   and add an <env-entry> element after this to map a property set to your custom EntityPropertyManager, a shown in the following example:

       <!-- map all properties in UUPExample property set to MyEntityPropertyManager -->
       <env-entry>
           <env-entry-name>PropertyMapping/UUPExample</env-entry-name>
           <env-entry-type>java.lang.String</env-entry-type>
           <env-entry-value>MyEntityPropertyManager</env-entry-value>
       </env-entry>

4. In ejb-jar.xml, find the <ejb-ref> element shown in the following example:

       <!-- an ldap property manager -->
       <ejb-ref>
           <ejb-ref-name>ejb/LdapPropertyManager</ejb-ref-name>
           <ejb-ref-type>Session</ejb-ref-type>
           <home>com.bea.p13n.property.EntityPropertyManagerHome</home>
           <remote>com.bea.p13n.property.EntityPropertyManager</remote>
       </ejb-ref>

   and add an <ejb-ref> element after this to map a reference to an EJB that matches the name from the previous step with ejb/ prepended as shown in the following example:

       <!-- an example property manager -->
       <ejb-ref>
           <ejb-ref-name>ejb/MyEntityPropertyManager</ejb-ref-name>
           <ejb-ref-type>Session</ejb-ref-type>
           <home>examples.usermgmt.MyEntityPropertyManagerHome</home>
           <remote>examples.usermgmt.MyEntityPropertyManager</remote>
       </ejb-ref>

   The home and remote class names match the classes from your EJB JAR file for your custom EntityPropertyManager.
5. If your EntityPropertyManager implementation handles creating and removing profile records, you must also add Creator and Remover entries. For example:

       <env-entry>
           <env-entry-name>Creator/Creator1</env-entry-name>
           <env-entry-type>java.lang.String</env-entry-type>
           <env-entry-value>MyEntityPropertyManager</env-entry-value>
       </env-entry>

       <env-entry>
           <env-entry-name>Remover/Remover1</env-entry-name>
           <env-entry-type>java.lang.String</env-entry-type>
           <env-entry-value>MyEntityPropertyManager</env-entry-value>
       </env-entry>

   This instructs the UserProfileManager to call your custom EntityPropertyManager when creating or deleting user profile records. The names "Creator1" and "Remover1" are arbitrary. All Creators and Removers will be iterated through when the UserProfileManager creates or removes a user profile. The value for the Creator and Remover matches the ejb-ref-name for your custom EntityPropertyManager without the ejb/ prefix.
6. From p13n_ejb.jar, extract META-INF/weblogic-ejb-jar.xml and open it for editing.
7. In weblogic-ejb-jar.xml, find the elements shown in the following example:

       <weblogic-enterprise-bean>
           <ejb-name>UserProfileManager</ejb-name>
           <reference-descriptor>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. EntityPropertyManager</jndi-name>
               </ejb-reference-description>

   and add an ejb-reference-description to map the ejb-ref for your custom EntityPropertyManager to the JNDI name. This JNDI name must match the name you assigned in weblogic-ejb-jar.xml in the JAR file for your customer EntityPropertyManager. It should look like the following example:

       <weblogic-enterprise-bean>
           <ejb-name>UserProfileManager</ejb-name>
           <reference-descriptor>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. EntityPropertyManager</jndi-name>
               </ejb-reference-description>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/MyEntityPropertyManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. MyEntityPropertyManager</jndi-name>
               </ejb-reference-description>

   Note the ${APPNAME} string substitution variable. The WebLogic EJB container automatically substitutes the enterprise application name to scope the JNDI name to the application.
8. Update p13n_ejb.jar for your new deployment descriptors. You can use the jar uf command to update the modified META-INF/ deployment descriptors.
9. Edit your application's META-INF/application.xml to add an entry for your custom EntityPropertyManager EJB module as shown in the following example:

       <module>
           <ejb>UUPExample.jar</ejb>
       </module>

10. If you are using an application-wide cache, you can manage it from the WebLogic Administration Console if you add a <Cache> tag for your cache to the META-INF/application-config.xml deployment descriptor for your enterprise application like this:

        <Cache Name="UUPExampleCache" TimeToLive="60000"/>

11. Verify the modified p13n_ejb.jar and your custom EntityPropertyManager EJB JAR archive are in the root directory of your enterprise application and start WebLogic Server.
12. Use the WebLogic Server Administration Console to verify your EJB module is deployed to the enterprise application and then use the console to add your server as a target for the EJB module. You need to select a target to have your domain's config.xml file updated to deploy your EJB module to the server.
13. Use the WebLogic Workshop Property Set Designer to create a User Profile (property set) that matches the name of the property set that you mapped to your custom EntityPropertyManager in ejb-jar.xml for the UserProfileManager (in p13n_ejb.jar). You could also map specific property names in a property set to your custom EntityPropertyManager, which would allow you to surface the properties and their values in the WebLogic Administration Portal for use in creating rules for personalization, delegated administration, and visitor entitlements.

Your new Unified User Profile type is ready to use. You can use the WebLogic Administration Portal to create a user, and it will use your UUP implementation when the "UUPExample" property set is being modified. When you call createUser("bob", "password") or createUser("bob", "password", null) on the UserManager, several things will happen:

- A user named "bob" is created in the security realm.
- A WebLogic Portal Server profile record is created for "bob" in the user store.
- If you set up the Creator mapping, the UserManager will call the default ProfileManager deployment (UserProfileManager) which will call your custom EntityPropertyManager to create a record for Bob in your data source.
- Retrieving Bob's profile will use the default ProfileManager deployment (UserProfileManager), and when you request a property belonging to the "UUPExample" property set, the request will be routed to your custom EntityPropertyManager implementation.

#### Configuring and Deploying a New ProfileManager

If you are going to deploy a newly configured ProfileManager instead of using the default ProfileManager (UserProfileManager) to manage your user profiles, perform the following steps to modify the deployment configuration. In most cases, you will not have to use this method of deployment. Use this method only if you need to support multiple types of users that require different ProfileManager deployments—deployments that allow a property set to be mapped to different custom EntityPropertyManagers based on ProfileType.

An example of this method is the deployment of the custom CustomerProfileManager in customer.jar. The CustomerProfileManager is configured to use the custom EntityPropertyManager (CustomerPropertyManager) for properties in the "CustomerProperties" property set. The UserManager EJB in p13n_ejb.jar is configured to map the "WLCS_Customer" ProfileType to the custom deployment of the ProfileManager, CustomerProfileManager.

To configure and deploy a new ProfileManager, use this procedure.

1. Back up the p13n_ejb.jar file in your enterprise application root directory.
2. From p13n_ejb.jar, extract META-INF/ejb-jar.xml, and open it for editing.
3. In ejb-jar.xml, copy the entire <session> tag for the UserProfileManager, and configure it to use your custom implementation class for your new deployment of ProfileManager.
   In addition, you could extend the UserProfileManager home and remote interfaces with your own interfaces if you want to repackage them to correspond to your packaging (for example., examples.usermgmt.MyProfileManagerHome, examples.usermgmt.MyProfileManager).
   However, it is sufficient to replace the bean implementation class:
   You must create an <env-entry> element to map a property set to your custom EntityPropertyManager. You must also create a <ejb-ref> element to map a reference to an EJB that matches the name from the PropertyMapping with ejb/ prepended. The home and remote class names for your custom EntityPropertyManager match the classes from your EJB JAR file for your custom EntityPropertyManager.
   Also, if your EntityPropertyManager implementation handles creating and removing profile records, you must also add Creator and Remover entries. This instructs your new ProfileManager to call your custom EntityPropertyManager when creating or deleting user profile records.
   Note: The name suffixes for the Creator and Remover, "Creator1" and "Remover1", are arbitrary. All Creators and Removers will be iterated through when your ProfileManager creates or removes a user profile. The value for the Creator and Remover matches the <ejb-ref-name> for your custom EntityPropertyManager without the ejb/ prefix.
4. In ejb-jar.xml, you must add an <ejb-ref> to the UserManager EJB section to map your ProfileType to your new deployment of the ProfileManager, as shown in the following example:

       <ejb-ref>
           <ejb-ref-name>ejb/ProfileType/UUPExampleUser</ejb-ref-name>
           <ejb-ref-type>Session</ejb-ref-type>
           <home>com.bea.p13n.usermgmt.profile.ProfileManagerHome</home>
           <remote>com.bea.p13n.usermgmt.profile.ProfileManager</remote>
       </ejb-ref>

   The <ejb-ref-name> must start with ejb/ProfileType/ and must end with the name that you want to use as the profile type as an argument in the createUser() method of UserManager.
5. From p13n_ejb.jar, extract META-INF/weblogic-ejb-jar.xml and open it for editing.
6. In weblogic-ejb-jar.xml, copy the <weblogic-enterprise-bean> tag, shown in the following example, for the UserProfileManager and configure it for your new ProfileManager deployment:

       <weblogic-enterprise-bean>
           <ejb-name>MyProfileManager</ejb-name>
           <reference-descriptor>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. EntityPropertyManager</jndi-name>
               </ejb-reference-description>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/PropertySetManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. PropertySetManager</jndi-name>
               </ejb-reference-description>
               <ejb-reference-description>
                   <ejb-ref-name>ejb/MyEntityPropertyManager</ejb-ref-name>
                   <jndi-name>${APPNAME}.BEA_personalization. MyEnitityPropertyManager</jndi-name>
               </ejb-reference-description>
           </reference-descriptor>
           <jndi-name>${APPNAME}.BEA_personalization. MyProfileManager</jndi-name>
       </weblogic-enterprise-bean>

   You must create an <ejb-reference-description> to map the <ejb-ref> for your custom EntityPropertyManager to the JNDI name. This JNDI name must match the name you assigned in weblogic-ejb-jar.xml in the JAR file for your custom EntityPropertyManager.
   Note the ${APPNAME} string substitution variable. The WebLogic Server EJB container automatically substitutes the enterprise application name to scope the JNDI name to the application.
7. In weblogic-ejb-jar.xml, copy the <transaction-isolation> tag for the UserProfileManager, shown in the following example, and configure it for your new ProfileManager deployment:

       <transaction-isolation>
           <isolation-level>TRANSACTION_READ_COMMITTED</isolation-level>
           <method>
               <ejb-name>MyProfileManager</ejb-name>
               <method-name>*</method-name>
           </method>
       </transaction-isolation>

8. Create a temporary p13n_ejb.jar for your new deployment descriptors and your new ProfileManager bean implementation class. This temporary EJB JAR archive should not have any container classes in it. Run ejbc to generate new container classes.
9. Edit your application's META-INF/application.xml to add an entry for your custom EntityPropertyManager EJB module, as shown in the following example:

       <module>
           <ejb>UUPExample.jar</ejb>
       </module>

10. If you are using an application-wide cache, you can manage it from the WebLogic Server Administration Console if you add a <Cache> tag for your cache to the META-INF/application-config.xml deployment descriptor for your enterprise application as shown in the following example:

        <Cache Name="UUPExampleCache" TimeToLive="60000"/>

    Verify the modified p13n_ejb.jar and your custom EntityPropertyManager EJB JAR archive are in the root directory of your enterprise application and start your server.
11. Use the WebLogic Server Administration Console to verify your EJB module is deployed to the enterprise application and add your server as a target for the EJB module. You must select a target to have your domain's config.xml file updated to deploy your EJB module to the server.
12. Use the WebLogic Workshop Property Set Designer to create a User Profile (property set) that matches the name of the property set that you mapped to your custom EntityPropertyManager in ejb-jar.xml for the UserProfileManager (in p13n_ejb.jar). You could also map specific property names in a property set to your custom EntityPropertyManager, which would allow you to surface the properties and their values in the WebLogic Administration Portal for use in creating rules for personalization, delegated administration, and visitor entitlements.

Your new Unified User Profile type is ready to use. You can use the WebLogic Administration Portal to create a user, and it will use your UUP implementation when the "UUPExample" property set is being modified. That is because you mapped the ProfileType using an <ejb-ref> in your UserManager deployment descriptor, ejb/ProfileType/UUPExampleUser.

Now, when you call createUser("bob", "password", "UUPExampleUser") on the UserManager, several things will happen:

- A user named "bob" is created in the security realm.
- A WebLogic Portal Server profile record is created for "bob" in the WebLogic Portal RDBMS repository.
- If you set up the Creator mapping, the UserManager will call your new ProfileManager deployment, which will call your custom EntityPropertyManager to create a record for Bob in your data source.
- Retrieving Bob's profile will use your new ProfileManager deployment, and when you request a property belonging to the "UUPExample" property set, the request will be routed to your custom EntityPropertyManager implementation.

### Retrieving User Profile Data from LDAP

WebLogic Portal provides a default unified user profile for retrieving properties from an LDAP server. Use this procedure to implement the LDAP unified user profile for retrieving properties from your LDAP server.

The LdapRealm security realm and the LdapPropertyManager unified user profile (UUP) for retrieving user properties from LDAP are independent of each other. They do not share configuration information and there is no requirement to use either one in conjunction with the other. A security realm has nothing to do with a user profile. A security realm provides user/password data, user/group associations, and group/group associations. A user profile provides user and group properties. A password is not a property.

In order to successfully retrieve the user profile from the LDAP server, ensure that you've done the following:

1. If you have already deployed the application on a WebLogic Portal instance, stop the server.
2. Extract p13n_ejb.jar from your application root to a temporary directory.
3. In the temporary directory, open META-INF/ejb-jar.xml, which contains a commented block called "Ldap Property Manager." Uncomment and reconfigure this section using the following steps:
   1. Remove the closing comment mark (-->) from the end of the "Ldap Property Manager" block, just before the "Property Set Web Service EJB" block, and add it to the end of the first paragraph of the Ldap Property Manager block, like this:

      >     <!-- Ldap Property Manager
      >          To use this, uncomment it here as well as in weblogic-ejb-jar.xml.
      >          Configure the LDAP connection and settings using the env-entry values (see descriptions below).
      >          Do not forget to uncomment the ejb-link and method-permission tags for the LdapPropertyManager.
      >          An easy way to ensure you don't miss anything is to search for "ldap" (case-insensitive) here AND in
      >          weblogic-ejb-jar.xml. Search from the beginning to the end of the file.
      >     -->

   2. In the "Ldap Property Manager" block, look for the following default settings and replace them with your own:

      > ldap://server.company.com:389 | Change this to the value of your LDAP server URL.
      > uid=admin, ou=Administrators, ou=TopologyManagement, o=NetscapeRoot | Change this to the value of your LDAP server's principal.
      > <env-entry-value>weblogic</env-entry-value> | Change "weblogic" to your LDAP server's principalCredential.
      > ou=People,o=company.com | Change this to your LDAP server's UserDN.
      > ou=Groups,o=company.com | Change this to your LDAP server's GroupDN.
      > <env-entry-value>uid</env-entry-value> | Change "uid" to your LDAP server's usernameAttribute setting.
      > <env-entry-value>cn</env-entry-value> | Change "cn" to your LDAP server's groupnameAttribute setting.

   3. In the "User Profile Manager" and "Group Profile Manager" sections, find the following lines:

      >     <!-- <ejb-link>LdapPropertyManager</ejb-link> -->
      >     <ejb-link>EntityPropertyManager</ejb-link>

      Uncomment the LdapPropertyManager line and delete the EntityPropertyManager line in both sections.

   4. In the <method-permission> and <container-transaction> sections, find and uncomment the following:

      >     <!--
      >     <method>
      >         <ejb-name>LdapPropertyManager</ejb-name>
      >         <method-name>*</method-name>
      >     </method>
      >     -->

   5. Check to see that you have uncommented all Ldap configurations by doing a search for "Ldap" in the file.
   6. Save and close the file.
4. In the temporary directory, open META-INF/weblogic-ejb-jar.xml and perform the following modifications:

1. Uncomment the "LdapPropertyManager" block:

   >     LdapPropertyManager
   >     <weblogic-enterprise-bean>
   >         <ejb-name>LdapPropertyManager</ejb-name>
   >         <enable-call-by-reference>True</enable-call-by-reference>
   >         <jndi-name>${APPNAME}.BEA_personalization.LdapPropertyManager</jndi-name>
   >     </weblogic-enterprise-bean>

2. In the "Security configuration" section of the file, uncomment the LdapPropertyManager method:

   >     <method>
   >         <ejb-name>LdapPropertyManager</ejb-name>
   >         <method-name>*</method-name>
   >     </method>

3. Check to see that you have uncommented all Ldap configurations by doing a search for "Ldap" in the file.
4. Save and close the file.

5. Replace the original p13n_ejb.jar with the modified version.

1. Rename the original p13n_ejb.jar to use it as a backup. For example, rename it to p13n_ejb.jar.backup.
2. JAR the temporary version of p13n_ejb.jar to which you made changes. Name it p13n_ejb.jar.
3. Copy the new JAR to your application's root directory.

6. Start the server and re-deploy the application.
7. The properties from your LDAP server are now accessible through the WebLogic Portal API, JSP tags, and controls.
   If you want to surface the properties from your LDAP server in the WebLogic Administration Portal (for use in defining rules for personalization, delegated administration, and visitor entitlements), create a user profile property set called ldap.usr, and create properties in the property set that exactly match the names of the LDAP properties you want to surface.

#### Enabling SUBTREE_SCOPE Searches for Users and Groups

The LdapPropertyManager EJB in p13n_ejb.jar allows for the inspection of the LDAP schema to determine multi-valued versus single-value LDAP attributes, to allow for multiple userDN/groupDN, and to allow for SUBTREE_SCOPE searches for users and groups in the LDAP server. Following are more detailed explanations:

The determination of multi-value versus single-value LDAP attributes allows a developer to configure the ejb-jar.xml deployment descriptor for the LdapPropertyManager EJB to specify that the LDAP schema be used to determine if a property is single- or multi-value.

To enable SUBTREE-SCOPE for users and groups:

1. Stop the server.
2. Extract p13n_ejb.jar from your application root directory to a temporary directory and edit the temporary META-INF/ejb-jar.xml by setting the following env-entries.

       <!-- Flag to specify if LDAP attributes will be determined to be single value
       or multi-value via the schema obtained from the attribute. If false,
       then the attribute is stored as multi-valued (a Collection) only if it has
       more than one value. Leave false unless you intend to use multi-valued LDAP
       attributes that may have only one value. Using true adds overhead to check
       the LDAP schema. Also, if you use true beware that most LDAP attributes are
       multi-value. For example, iPlanet Directory Server 5.x uses multi-value for
       givenName, which you may not expect unless you are familiar with LDAP schemas.
       This flag will apply to property searches for all userDNs and all groupDNs. -->

       <env-entry>
           <env-entry-name>config/detectSingleValueFromSchema</env-entry-name>
           <env-entry-type>java.lang.Boolean</env-entry-type>
           <env-entry-value>true</env-entry-value>
       </env-entry>

       <!-- Value of the name of the attribute in the LDAP schema that is used
       to determine single value or multi-value (RFC2252 uses SINGLE-VALUE).
       This attribute in the schema should be true for single value and false
       or absent from the schema otherwise. The value only matters if
       config/detectSingleValueFromSchema is true. -->

       <env-entry>
           <env-entry-name>config/singleValueSchemaAttribute</env-entry-name>
           <env-entry-type>java.lang.String</env-entry-type>
           <env-entry-value>SINGLE-VALUE</env-entry-value>
       </env-entry>

   It is not recommended that true be used for config/detectSingleValueFromSchema unless you are going to write rules that use multi-valued LDAP attributes that have a single value. Using config/detectSingleValueFromSchema = true adds the overhead of checking the LDAP schema for each attribute instead of the default behavior (config/detectSingleValueFromSchema = false), which only stores an attribute as multi-valued (in a Collection) if it has more than one value.
   This feature also implements changes that allow you to use SUBTREE_SCOPE searches for users and groups. It also allows multiple base userDN and groupDN to be specified. The multiple base DN can be used with SUBTREE_SCOPE searches enabled or disabled.
   A SUBTREE_SCOPE search begins at a base userDN (or groupDN) and works down the branches of that base DN until the first user (or group) is found that matches the username (or group name).
   To enable SUBTREE_SCOPE searches you must set the Boolean config/objectPropertySubtreeScope env-entry in the ejb-jar.xml for p13n_ejb.jar.jar to true and then you must set the config/userDN and config/groupDN env-entry values to be equal to the base DNs from which you want your SUBTREE_SCOPE searches to begin.
   For example, if you have users in ou=PeopleA,ou=People,dc=mycompany,dc=com and in ou=PeopleB,ou=People,dc=mycompany,dc=com then you could set config/userDN to ou=People,dc=mycompany,dc=com and properties for these users would be retrieved from your LDAP server because the user search would start at the "People" ou and work its way down the branches (ou="PeopleA" and ou="PeopleB").
   You should not create duplicate users in branches below your base userDN (or duplicate groups below your base groupDN) in your LDAP server. For example, your LDAP server will allow you to create a user with the uid="userA" under both your PeopleA and your PeopleB branches. The LdapPropertyManager in p13n_ejb.jar.jar will return property values for the first userA that it finds.
   It is recommended that you do not enable this change (by setting config/objectPropertySubtreeScope to true) unless you need the flexibility offered by SUBTREE_SCOPE searches.
   An alternative to SUBTREE_SCOPE searches (with or without multiple base DNs) would be to configure multiple base DNs and leave config/objectPropertySubtreeScope set to false. Each base DN would have to be the DN that contains the users (or groups) because searches would not go any lower than the base DN branches. The search would cycle from one base DN to the next until the first matching user (or group) is found.
   The new ejb-jar.xml deployment descriptor is fully commented to explain how to set multiple DNs, multiple usernameAttributes (or groupnameAttributes), and how to set the objectPropertySubtreeScope flag.
3. Save and close the file.
4. Replace the original p13n_ejb.jar with the modified version:
   1. Rename the original p13n_ejb.jar to use it as a backup. For example, rename it to p13n_ejb.jar.backup.
   2. JAR the temporary version of p13n_ejb.jar to which you made changes. Name it p13n_ejb.jar.
   3. Copy the new JAR to your application's root directory.
5. Start the server and re-deploy the application.

Related Topics

Using Multiple Authentication Providers in Portal Development