| Oracle® Fusion Middleware User Management Guide for Oracle WebLogic Portal 10g Release 3 (10.3.4) Part Number E14254-02 |
|
|
View PDF |
| Oracle® Fusion Middleware User Management Guide for Oracle WebLogic Portal 10g Release 3 (10.3.4) Part Number E14254-02 |
|
|
View PDF |
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 Oracle Enterprise Pack for Eclipse to create a UUP EJB, and then use Oracle Enterprise Pack for Eclipse 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:
During the Portal Application Development Phase – If you are in the portal development phase, use Oracle Enterprise Pack for Eclipse to create and configure the UUP. The UUP configurations are stored in the META-INF/p13n-profile-config.xml descriptor file and are packaged within the portal application. (A UUP you configure in the Administration Console overwrites Oracle Enterprise Pack for Eclipse UUP configurations from the p13n-profile-config.xml file and stores the settings separately from the portal application.)
During the Portal Runtime Phase – Use the Administration Console to configure the UUP at portal runtime (after the portal is deployed) and overwrite the configuration performed by Oracle Enterprise Pack for Eclipse. The Administration Console stores application descriptor changes (the 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.
Caution:
Configuring a UUP in Oracle Enterprise Pack for Eclipse or the 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 Oracle Enterprise Pack for Eclipse.The appendix includes the following sections:
Section A.1, "Creating and Configuring an EntityPropertyManager EJB"
Section A.2, "Retrieving User Profile Data from an LDAP Server"
You can use Oracle Enterprise Pack for Eclipse to create and configure the EntityPropertyManager EJB. The next step is to create a UUP in Oracle Enterprise Pack for Eclipse, and then configure the UUP in Oracle Enterprise Pack for Eclipse or the Administration Console.
This section contains the following topics:
You can use Oracle Enterprise Pack for Eclipse 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 Oracle Enterprise Pack for Eclipse. To find this topic, choose Help > Help Contents, expand Oracle Workshop for WebLogic User's Guide, and select Enterprise Java Beans.Use the following guidelines to create your new EJB:
Your custom 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:
The getDynamicProperties() method
The getEntityNames() method
The getHomeName() method
The getPropertyLocator() method
The getUniqueId() method
If you want 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. The method 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:
The 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.
The setProperty() method – Use caching.
The 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.
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 Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.)
If the external system contains read-only data, any methods that modify profile data must throw a 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.
To avoid class loader dependency issues, verify 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).
Follow the steps in the next section to configure and deploy your EJB.
You can use Oracle Enterprise Pack for Eclipse or the Administration Console to configure the new EntityPropertyManager EJB.
To configure and deploy the new EntityPropertyManager EJB:
If you have already deployed the application on a WebLogic Portal instance, stop the server.
In the Merged Projects View in Oracle Enterprise Pack for Eclipse, locate the p13n-profile-config.xml file.
Right-click the 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 Section A.2.2.2, "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.Deploy the EntityPropertyManager EJB.
You can also access the Administration Console and add or change lines in the 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 Section A.2.1, "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 Oracle Fusion Middleware Security Guide for Oracle WebLogic Portal.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:
If you have already deployed the application on a WebLogic Portal instance, stop the server.
In the Merged Project View in Oracle Enterprise Pack for Eclipse, deploy the sample ldap_uup.jar file as an EJB component of your portal application. To deploy the file, locate the ldap_uup.jar file in the <WLPORTAL_HOME>/p13n/lib directory and copy it to your EARContent directory in your EAR Project folder.
Locate the 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.
Copy the 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.In your Portal EAR directory, open your /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 Section A.2.2.2, "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.Save and close the file.
Create an LDAP cache. The name of the cache is specified by the adapter property 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 Oracle Fusion Middleware Cache Management Guide for Oracle WebLogic Portal.
If you want the properties from your LDAP server to appear in the Administration Console (so you can define rules for personalization, delegated administration, and visitor entitlement), create a user profile property set (a .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.Start the server and redeploy the application. The properties from your LDAP server are now accessible through the WebLogic Portal API, JSP Tags, and Controls.
If your LDAP server requires a user name and password during connection, set them up by launching the Administration Console and choosing Configuration & Monitoring > Service Administration. Select Unified User Profile in the Resource tree and then select your LDAP UUP. Enter the user name and password that are mapped to the credential alias adapter property. Re-deploy the application again. Verify the change by logging in as an existing LDAP user.
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 user name and password. If you do not want your LDAP server to require a user name 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 Chapter 5, "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.
In the Merged Projects View in Oracle Enterprise Pack for Eclipse, locate the p13n-profile-config.xml file.
Right-click the p13n-profile-config.xml file and select Copy to Project. The file will be copied to the /META-INF directory in your EAR project folder.
To edit the configuration file:
Open the configuration file and uncomment the <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.Edit the configuration properties as described in Table A-1 and Table A-2.
Table A-1 UUP Configuration Properties
| Property Name | Description |
|---|---|
|
<property-mapping> |
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. Note: The value of this property must match the name of the user profile (.usr) file. For example, if the value of this property is myLdap, the corresponding user profile must be named myLdap.usr. If these names do not match, the LDAP properties will not appear in the WLP Administration Console. Default: newLdap |
|
<ejb-jndi> |
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 Section A.1.1, "Creating the EJB." For example, MyUUPManager.jar#MyUUPEntityPropertyManager. Alternatively, you can specify the JNDI lookup name of the EJB. For example: ejb.MyUUPEntityPropertyManagerHome Default: ldap_uup.jar#LdapPropertyManager |
|
<credential-alias> |
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 user name and password. If you do not want your LDAP server to require a user name and password, remove the credential-alias line from the configuration file. |
Table A-2 <adapter-property> Elements
| Element Name | Description |
|---|---|
|
serverHosts |
This <adapter-property> element can be serverURL or serverHosts. If both are present, serverHosts takes precedence. serverHosts – A space separated LDAP server host:port string list. Sample value: SunOneLdapServerHost:1234 199.234.1.2 ads.mycompany.com:5678 serverURL – Your LDAP server URL. Example: ldap://server.company.com:389 |
|
ConnectTimeout |
(Optional) Specifies the connection timeout (in seconds) to failover to the next configured LDAP server. Default: 30 |
|
userDN |
Specifies the location of users in your LDAP directory. You can have one or more userDN entries, named as follows: userDN userDN-1 userDN-2 userDN-n The entries are searched in that order. If there is only one entry, it must be userDN. Typical values: ou=People, dc=mycompany, dc=com |
|
groupDN |
Specifies the location of groups in your LDAP directory. You can have one or more groupDN entries, named as follows: groupDN groupDN-1 groupDN-2 groupDN-n The entries are searched in that order. If there is only one entry, it must be groupDN. Typical values: ou=Groups, dc=mycompany, dc=com |
|
objectPropertySubtreeScope |
(Boolean) Specifies whether to enable 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 and users that are in both ou=PeopleA, ou=People, dc=mycompany, dc=com and in ou=PeopleB, ou=People, dc=mycompany, dc=com could be used. 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. Default: false |
|
usernameAttribute |
Specifies the user attribute to map to a user name. If there is only one, then it is applied to all userDNs. If there is more than one, then they are applied, in order, to the userDNs. If there is more than one, then the number must match the number of userDNs. The entries are named as follows: usernameAttribute usernameAttribute-1 usernameAttribute-2 usernameAttribute-n The entries are used in that order. If there is only one, then it must be usernameAttribute. Default: uid |
|
groupnameAttribute |
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: groupnameAttribute groupnameAttribute-1 groupnameAttribute-2 groupnameAttribute-n The entries are used in that order. If there is only one, then it must be groupnameAttribute. Default: cn |
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:
Administration Console – During portal runtime, you can configure these optional settings according to the instructions in Section 6.2, "Configuring a UUP in the Administration Console."
Oracle Enterprise Pack for Eclipse – During the development phase, you can configure these optional settings according to the instructions in Section 6.3, "Configuring a UUP in Oracle Enterprise Pack for Eclipse."
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:
Stop the server.
Set the Boolean objectPropertySubtreeScope adapter-property-value to true in the adapter-property-name element in the p13n-profile-config.xml file for the LDAP UUP adapter.
Set the 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.
Save and close the file.
Start the server and redeploy the application.
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.
Tip:
If you modified settings in your p13n_ejb.jar file and you want to preserve them, you must use Oracle Enterprise Pack for Eclipse 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 or later versions:
Start Oracle Enterprise Pack for Eclipse and create a new Workspace.
Create a new portal domain. Do not create a Portal EAR Project. For instructions on creating a new domain, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Import your Portal 8.1 UUP application into your new environment by choosing File > Import.
In the Select dialog, click the Open folder and select Workshop 8.1 Application and click Next.
In the Application Import dialog, click Browse and locate your 8.1 UUP application. Select the .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.
Figure A-1 Locate the 8.1 UUP Application
In the Source Upgrade dialog, click NetUI Project Upgrader options and select the Use WebLogic J2EE Shared Libraries check box. You can also click JSP File Migrator options and select the Replace BEANetUI tags with Apache Beehive tags check box (if desired) and click Finish.
After the upgrade finishes, verify that the following actions occurred:
The p13n-ejb.jar file was removed from the EARContent directory of the UUP application.
The UUP EJB JAR file (for example, UUPExample.jar) exists in the EARContent directory of the UUP application.
The UUP EJB JAR file is referenced in a module entry in the application.xml file in the <UUPApplication>/EARContent/META-INF/ directory.
As an example, the cache entry below was added to the p13n-cache-config.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>
Verify that the User Profile file (for example, UUPExample.usr) file exists in the data/src/userprofiles/ directory (or where your Datasync folder exists).
Associate your UUP application with your WebLogic Server by selecting the server in the Servers tab, right-clicking the server, and choosing Add and Remove Projects. Select the UUP application from the Available Projects section, click Add, and then click Finish.
Build and publish your application. Verify the application by starting the WebLogic Server Administration Console and clicking Deployments. Verify that the UUP application is active. Then open the UUP application by expanding the tree and verifying that the UUP JAR file appears as an EJB.
For more information about upgrading other non-portal applications from WebLogic Portal 8.1, see the Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Portal.
|
 Copyright © 2010, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|