|
|
WebLogic Portal includes a UUP service that lets you add and manage user properties in a single logical location—even if the user data is stored in external systems, such as an LDAP server. You can add this additional user data to a user’s profile.
You can use WorkSpace Studio to create a UUP EJB, and then use WorkSpace Studio or the Administration Console to configure the UUP. (In WebLogic Portal 8.1, you could configure a UUP manually, but that method is no longer supported). You must choose one method or the other; the methods are not interchangeable.
The method you choose depends where you are in your portal development process:
META-INF/p13n-profile-config.xml descriptor file and are packaged within the portal application. (A UUP you configure in the Administration Console overwrites WorkSpace Studio UUP configurations from the p13n-profile-config.xml file and stores the settings separately from the portal application.)p13n-profile-config.xml file is one of application descriptors) in the deployment plan, separate from the portal application. See the WebLogic Server documentation for more information about the relationship between the descriptor and the deployment plan.
The Administration Console overwrites UUP configurations from the p13n-profile-config.xml file, and stores changes in the deployment plan, separate from the portal application.
| WARNING: | Configuring a UUP in WorkSpace Studio or Administration Console takes precedence over existing UUPs that you configured manually in previous versions of WebLogic Portal. Existing UUPs that you created manually can coexist with new UUPs that you configure in the Administration Console or in WorkSpace Studio. |
The appendix includes the following sections:
You can use WorkSpace Studio to create and configure the EntityPropertyManager EJB. The next step is to create a UUP in WorkSpace Studio, and then configure the UUP in WorkSpace Studio or the Administration Console.
This section contains the following topics:
You can use WorkSpace Studio or another development tool to create a stateless session bean EJB that implements the methods of the EntityPropertyManager interface.
To incorporate data from an external source, you must 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 creates and deletes profile records. By default, EntityPropertyManager provides read-only access to external properties.
| Tip: | To learn how to create a stateless session bean EJB component that is scoped to the application, see the instructions in WorkSpace Studio. To find this topic, choose Help > Help Contents, expand BEA Workshop User’s Guide, and select Enterprise Java Beans. |
Use the following guidelines to create your new EJB:
EntityPropertyManager is not the default EntityPropertyManager (supplied out-of-the-box). The default EntityPropertyManager is used to get, set, or remove properties in the portal schema. Your custom EntityPropertyManager can throw a java.lang.UsupportedOperationException message if it does not support the following methods: 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. The method must create the user entity in your external data store and then it can return any number, such as -1. EntityPropertyManager() methods that you must support:getProperty() method – 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 the getProperties() method.setProperty() method – Use caching.removeProperties() and removeProperty() methods – After these methods are called, a call to getProperty() should return null for the property. You should also remove properties from the cache.getProperty(), setProperty(), removeProperty(), and removeProperties() methods must include any logic necessary to connect to the external system. com.bea.p13n.cache package in the
Javadoc.) java.lang.UnsupportedOperationException message. Additionally, if the external data source contains users that are created and deleted by something other than your WebLogic Portal createUniqueId() and removeEntity() methods, you can throw an UnsupportedOperationException message. EntityPropertyManager bean in your own JAR file (instead of modifying an existing WebLogic Portal JAR file). Follow the steps in the next section to configure and deploy your EJB.
You can use WorkSpace Studio or the Administration Console to configure the new EntityPropertyManager EJB.
To configure and deploy the new EntityPropertyManager EJB:
p13n-profile-config.xml file.p13n-profile-config.xml file and copy it into the /META-INF directory in your EAR project folder. Uncomment or edit the applicable lines in the p13n-profile-config.xml file and save the file. For details on this file, see Editing the Configuration File. | Note: | The value of the <ejb-jndi> element must match the name of the EJB project containing your custom EJB and the name of the EJB class. The format of this value is <UUP JAR file name>#<EJB name>. For example, UUPExample.jar#MyEntityPropertyManager. |
EntityPropertyManager EJB.p13n-profile-config.xml file. Choose Configuration & Monitoring > Service Administration, and select Unified User Profiles and your UUP in the Resource Tree. After you make changes to the p13n-profile-config.xml file in the Administration Console, redeploy the application.
WebLogic Portal ships with a default UUP that retrieves properties from an LDAP server. An LDAP can be any directory server that supports the LDAP protocol, such as Sun Directory Server, Microsoft Active Directory, or OpenLDAP.
WebLogic Portal supports transparent failover, to move from one LDAP server to another LDAP server that contains identical information. You can specify single LDAP PropertyManagers to point to LDAP servers that contain the same user and group information. The order of LDAP servers specified in the configuration determines the order of failover from the previous LDAP server. If the primary server is unavailable, the property retrieval request rolls to the secondary server, and so on. If you do not set up transparent failover and an LDAP server fails, the transaction fails.
See Configuring an LDAP UUP and Transparent Failover for configuration instructions on transparent failover.
| Note: | For instructions on connecting to other user stores with UUP, see the Security Guide. |
The LdapRealm Security realm and the LdapPropertyManager UUP that retrieve user properties from LDAP are independent of each other. They do not share configuration information, and there is no requirement to use one with the other. A Security realm has nothing to do with a user profile. A Security realm provides user and password data, and user and group associations. A user profile provides user and group properties. A password is not a property.
To implement the LDAP UUP to retrieve properties from your LDAP server or to set up transparent failover:
ldap_uup.jar file as an EJB component of your portal application. To deploy the file, locate the ldap_uup.jar file in the <WEBLOGIC_HOME>/common/p13n/lib directory and copy it to your EARContent directory in your EAR Project folder. application.xml file in the /META-INF directory in your EARContent directory and add the following information to the <module> section: <module>
<ejb>ldap_uup.jar</ejb>
</module>
Save the application.xml file.
p13n-profile-config.xml file from the p13n-app-lib.ear file into the /META-INF directory of your EAR project, and uncomment the <property-adapter> section named LdapUUPAdapter.| Tip: | If you already have an existing p13n-profile-config.xml file, open it and copy the updated sections into the p13n-profile-config.xml file in your /META-INF directory in your Portal EAR directory. |
/META-INF/p13n-profile-config.xml file. (If you have not already copied this file from the library module, copy it now.) The file contains a commented <property-adapter> block called LdapUUPAdapter. Uncomment and reconfigure this section using guidelines discussed in Editing the Configuration File. | Note: | The value of the <ejb-jndi> element must match the name of the EJB project containing your custom EJB and the name of the EJB class. Unless you changed the default deployment ldap_uup deployment descriptor ejb-jar.xml, you do not need to modify this value. The format of this value is <UUP JAR file name>#<EJB name>. For example, UUPExample.jar#MyEntityPropertyManager. |
| Note: | If you are configuring transparent failover, use the serverHosts instead of the serverURL adapter property to configure multiple LDAP servers. The serverURL adapter property supports only single LDAP server configuration for backwards compatibility. |
ldapPropertyCacheName in the p13n-profile-config.xml file. The default value for the cache’s name is ldapPropertyCache. To learn how to create a cache in the Administration Console, see
Cache Reference Guide. .usr file), and create properties in the property set that exactly match the actual LDAP properties in the LDAP server. Place the .usr file in your datasync project directory. The datasync project must reside in your portal EAR project.| Note: | The value of the <property-mapping> element in the p13n-profile-conf.xml file must match the name of the user profile property file. For example, if you called the user profile property file myUser.usr, the value of this element must be myUser. |
To verify this step, go to the Administration Console and choose Users, Groups, & Roles > User Management to see if a particular user's LDAP properties are shown in the user's profile.
| Tip: | A credential alias requires a username and password. If you do not want your LDAP server to require a username and password, remove the credential-alias line in the p13n-profile-config.xml file. |
This section discusses how to configure the p13n-profile-config.xml file. This file specifies configurations for UUP adapters. Each <property-adapter> element (if deployed) is mapped to a User Profile property set or property. For information on creating User Profiles, see Creating and Updating User Profiles.
A <property-adapter> element consists of a collection of <adapter-property> elements, which you must configure as explained in this section.
Before you can edit the configuration file, you must copy it to your workspace.
<property-adapter> section named LdapUUPAdapter. | Note: | If you are configuring a custom adapter, just copy the LdapUUPAdapter section and use it as a template and configure the name, property-mapping, and ejb-jndi fields. |
If you want the properties from your LDAP server to appear in the WLP Administration Console (so you can define rules for personalization, delegated administration, and visitor entitlement), create a user profile property set and create properties in the property set that exactly match the LDAP properties you want to appear. Create the user profile (.usr) file in your datasync project directory. The datasync project must be associated with your portal EAR project.
|
|||
This attribute specifies the name of your EJB project module and the name of your EntityPropertyManager EJB. The EJB name must match the name of your EntityPropertyManager EJB. See Creating the EJB.
|
|||
Specifies the credential alias that can be used to log into your LDAP server. This value can be set in the WLP Administration Console. A credential alias requires a username and password. If you do not want your LDAP server to require a username and password, remove the credential-alias line from the configuration file.
|
|||
(Boolean) Specifies whether to enbable or disable SUBTREE_SCOPE searches for user/group properties below the userDN(s) and groupDN(s).
For example, if this property is true, then you could specify the userDN entry as: ou=People, dc=mycompany, dc=com
A getProperty() call will return a value for the first user found in the specified userDN or in any branch below it. This boolean also affects searches for group properties. If multiple userDNs (or groupDNs) are specified then this SUBTREE_SCOPE will apply to searches starting in all of those specified DNs.
|
|||
Specifies the group attribute to map to a group name. If there is only one, then it is applied to all groupDNs. If there is more than one, then they are applied, in order, to the groupDNs. If there is more than one, then the number must match the number of groupDNs. The entries are named as follows:
|
|||
If your users are located in separate branches with a common root in your LDAP server, you must enable the subtree scope feature. The LdapPropertyManager EJB in the ldap_uup.jar file allows the LDAP schema to be inspected to determine multi-valued versus single-value (or flat) LDAP attributes, allow for multiple userDN and groupDN, and allow SUBTREE_SCOPE searches for users and groups in the LDAP server.
Determining multi-value versus single-value LDAP attributes specifies that the LDAP schema should be used to determine if a property is single- or multi-value. Consult your LDAP Server schema for instructions.
In your portal, you can configure these optional settings in the <adapter-property> setting to specify the LDAP schema using one of the following methods:
The p13n-profile-config.xml file provides sample settings as a commented block.
This feature also implements changes that allow you to use SUBTREE_SCOPE searches for users and groups. It also allows you to specify multiple base userDN and groupDN. You can use the multiple base DN 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 user name or group name.
Do not use true for detectSingleValueFromSchema in the p13-profile-config.xml file unless you plan to write rules that use multi-valued LDAP attributes that have a single value. Using /detectSingleValueFromSchema = true adds the overhead of checking the LDAP schema for each attribute instead of the default behavior (/detectSingleValueFromSchema = false), which only stores an attribute as multi-valued (in a collection) if it has more than one value.
Perform the following steps to manually enable SUBTREE-SCOPE for users and groups:
objectPropertySubtreeScope adapter-property-value to true in the adapter-property-name element in the p13n-profile-config.xml file for the LDAP UUP adapter.userDN and groupDN adapter-property-values in the p13n-profile-config.xml file to be equal to the base DNs where you want your SUBTREE_SCOPE searches to begin.
For example, if you have users in ou=PeopleA, ou=People, dc=mycompany, dc=com, and ou=PeopleB, ou=People, dc=mycompany, and dc=com, you could set 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 ou=People and work its way down the branches (ou=“PeopleA” and ou=“PeopleB”).
Do 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 PeopleA and your PeopleB branches. The LdapPropertyManager in the ldap_uup.jar.jar file returns property values for the first userA that it finds.
| Note: | Do not enable this change (by setting 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) is to configure multiple base DNs and leave 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 cycles from one base DN to the next until it finds the first matching user or group.
The new p13n-profile-config.xml file is fully commented to explain how to set multiple DNs, multiple usernameAttributes (or groupnameAttributes), and how to set the objectPropertySubtreeScope flag.
When you upgrade a UUP from WebLogic Portal 8.1, the p13n_ejb.jar file is deleted and replaced with a new WebLogic Portal version of this file. The new p13n_ejb.jar file is packaged in the library modules that ship with WebLogic Portal 10.0.
| Tip: | If you modified settings in your p13n_ejb.jar file and you want to preserve them, you must use WorkSpace Studio to create a p13n-profile-config.xml file. Add your existing settings to that XML file and deploy it. |
To upgrade a UUP created in WebLogic Portal 8.1 to WebLogic Portal 10.0:
.work file and click Open. Verify that the check boxes for the UUP application are selected and click Next, as shown in Figure A-1.
p13n-ejb.jar file was removed from the EARContent directory of the UUP application.UUPExample.jar) exists in the EARContent directory of the UUP application.application.xml file in the <UUPApplication>/EARContent/META-INF/ directory.<p13n:cache>
<p13n:name>UUPExampleCache</p13n:name>
<p13n:description>Cache for UUP Example</p13n:description>
<p13n:time-to-live>60000</p13n:time-to-live>
<p13n:max-entries>100</p13n:max-entries>
</p13n:cache>UUPExample.usr) file exists in the data/src/userprofiles/ directory (or where your Datasync folder exists).For more information about upgrading other non-portal applications from WebLogic Portal 8.1, see the Upgrade Guide.
|