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.
-
Back up the p13n_ejb.jar file in your
enterprise application root directory.
-
From p13n_ejb.jar, extract META-INF/ejb-jar.xml
and open it for editing.
-
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>
-
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.
-
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.
- From p13n_ejb.jar, extract META-INF/weblogic-ejb-jar.xml
and open it for editing.
-
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.
-
Update p13n_ejb.jar for your new deployment
descriptors. You can use the jar uf command
to update the modified META-INF/ deployment
descriptors.
-
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>
-
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"/>
-
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.
-
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.
-
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.
-
Back up the p13n_ejb.jar file in your
enterprise application root directory.
-
From p13n_ejb.jar, extract META-INF/ejb-jar.xml,
and open it for editing.
-
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.
-
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.
-
From p13n_ejb.jar, extract META-INF/weblogic-ejb-jar.xml
and open it for editing.
-
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.
-
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>
-
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.
-
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>
-
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.
-
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.
-
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:
-
If you have already deployed the application on a WebLogic Portal instance,
stop the server.
-
Extract p13n_ejb.jar from your application
root to a temporary directory.
- 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:
- 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.
-->
- 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. |
- 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.
- In the <method-permission> and
<container-transaction> sections,
find and uncomment the following:
<!--
<method>
<ejb-name>LdapPropertyManager</ejb-name>
<method-name>*</method-name>
</method>
-->
- Check to see that you have uncommented all Ldap configurations by doing
a search for "Ldap" in the file.
- Save and close the file.
- In the temporary directory, open META-INF/weblogic-ejb-jar.xml
and perform the following modifications:
- 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>
- In the "Security configuration" section of the file, uncomment
the LdapPropertyManager method:
<method>
<ejb-name>LdapPropertyManager</ejb-name>
<method-name>*</method-name>
</method>
- Check to see that you have uncommented all Ldap configurations by doing
a search for "Ldap" in the file.
- Save and close the file.
- Replace the original p13n_ejb.jar with the
modified version.
- Rename the original p13n_ejb.jar to use
it as a backup. For example, rename it to p13n_ejb.jar.backup.
- JAR the temporary version of p13n_ejb.jar
to which you made changes. Name it p13n_ejb.jar.
- Copy the new JAR to your application's root directory.
- Start the server and re-deploy the application.
- 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:
-
Stop the server.
-
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.
- Save and close the file.
- Replace the original p13n_ejb.jar with the modified version:
- Rename the original p13n_ejb.jar to
use it as a backup. For example, rename it to p13n_ejb.jar.backup.
- JAR the temporary version of p13n_ejb.jar
to which you made changes. Name it p13n_ejb.jar.
- Copy the new JAR to your application's root directory.
-
Start the server and re-deploy the application.