|Oracle® Application Server Upgrade and Compatibility Guide
10g (10.1.4.0.1) for Microsoft Windows
Part Number B28235-01
If you are upgrading distributed OracleAS Identity Management components that were configured to use SSL, you must re-enable SSL for the OracleAS Single Sign-On and Oracle Delegated Administration Services after the upgrade. For more information, see the following sections:
There is no need to enable SSL for Oracle Internet Directory, since the upgrade procedure automatically re-enables SSL for Oracle Internet Directory in the destination Oracle home if you were using SSL with Oracle Internet Directory in the source Oracle home.
To enable SSL for OracleAS Single Sign-On, use the procedure described in the section "Enabling SSL" chapter of the Oracle Application Server Single Sign-On Administrator's Guide.
In particular, you must perform the following steps as described in that section of the Oracle Application Server Single Sign-On Administrator's Guide:
Enable SSL on the Single Sign-On middle tier, which involves editing the
opmn.xml configuration file to enable SSL.
Change Single Sign-On URLs by running the
For more detailed information about this step in the SSL configuration process, see Section 126.96.36.199, "Enabling Monitoring of OracleAS Single Sign-On and Oracle Delegated Administration Services in Application Server Control".
Protect Single Sign-On URLs.
Restart the Oracle HTTP Server and the Single Sign-On Middle Tier (the OC4J_Security OC4J instance).
targets.xml Application Server Control configuration file to be sure that Application Server Control can connect to the required OracleAS Single Sign-On and Oracle Delegated Administration Services URLs:
Locate and open the
targets.xml file with a text editor.
The file is located in the destination Oracle home:
targets.xml file, locate the Oracle Delegated Administration Services element:
oracle_das_server element, update the properties shown in Table 9-1 with the recommended values shown for each property.
Table 9-1 OracleAS Single Sign-On and Oracle Delegated Administration Services Properties to Modify in the targets.xml Configuration File
|Property||Description and Required Value|
The protocol used by the Oracle HTTP Server. The value can be either HTTP or HTTPS (for secure SSL connections).
The physical port used to monitor the Oracle Delegated Administration Services on the host. This is often the default Oracle HTTP Server port.
The physical port used to monitor Oracle Delegated Administration Services on the host. This is often the default Oracle HTTP Server port.
The complete Oracle Delegated Administration Services URL, including the protocol, physical host name, and port. In high availability environments, do not use the load balancer virtual host and port.
The complete URL used by Application Server Control to monitor the Oracle Delegated Administration Services, including the protocol, physical host name, and port. In high availability environments, do not use the load balancer virtual host and port.
Locate the OracleAS Single Sign-On element within the targets.xml file:
Edit the values for the
HTTPProtocol properties within the
Be sure to enter the port and protocol for the physical OracleAS Single Sign-On host; do not use the port and protocol used to connect to the load balancer.
Save your changes and close the
To be sure Application Server Control can monitor OracleAS Single Sign-On and Oracle Delegated Administration Services over the SSL connection, verify that Application Server Control has access to the proper security certificate.
If you do not perform this step, Application Server Control will indicate that OracleAS Single Sign-On and Oracle Delegated Administration Services are down or unavailable even though it is up and running.
To correct this problem you must allow the Application Server Control to recognize the Certificate Authority that was used to support HTTPS. You must add the Certificate of that Certificate Authority to the list of Certificate Authorities recognized by the Application Server Control.To configure Application Server Control to recognize the Certificate Authority:
Obtain the Certificate of the Web Site's Certificate Authority, as follows:
In Microsoft Internet Explorer, connect to the HTTPS URL of the application server you are attempting to monitor.
Double-click the lock icon at the bottom of the browser screen, which indicates that you have connected to a secure Web site.
The browser displays the Certificate dialog box, which describes the Certificate used for this Web site. Other browsers offer a similar mechanism to view the Certificate detail of a Web Site.
Click the Certificate Path tab and select the first entry in the list of certificates.
Click View Certificate to display a second Certificate dialog box.
Click the Details tab on the Certificate window.
Click Copy to File to display the Certificate Manager Export wizard.
In the Certificate Manager Export wizard, select Base64 encoded X.509 (.CER) as the format you want to export and save the certificate to a text file with an easily-identifiable name, such as
Open the certificate file using your favorite text editor.
The content of the certificate file will look similar to the content shown in Example 9-1.
Update the list of Certificate Authorities, as follows:
This file contains a list of Base64 Certificates.
b64InternetCertificate.txt file and add the contents of the Certificate file you just exported to the end of the file, taking care to include all the Base64 text of the Certificate including the BEGIN and END lines.
Copy the text file that contains the certificate (for example, the file you named
sso_certificate.cer earlier in this procedure) to the OracleAS Portal middle tier.
orapki utility to update the
monwallet Oracle wallet by using the following command:
DESTINATION_ORACLE_HOME\bin\orapki wallet add -wallet ORACLE_HOME\sysman\config\monwallet -trusted_cert -cert certificate_location
When you are prompted for a password, enter the password for the
monwallet wallet. The default password is "welcome".
In the example, replace certificate_location with the full path to the text file that contains the certificate you saved earlier in this procedure and that you copied to the OracleAS Portal middle tier. For example:
Restart the Application Server Control.
After you restart the Application Server Control, Enterprise Manager detects your addition to the list of Certificate Authorities and you can successfully monitor the OracleAS Portal metrics using the secure Application Server Control Console.
If you have also configured Oracle Delegated Administration Services in the upgraded Oracle home, you must reconfigure the Oracle Delegated Administration Services URL.
To reconfigure the Oracle Delegated Administration Services URL:
oidadmin tool is located in the following directory in the destination Oracle home:
In the System Objects Navigator, navigate to the
cn=OperationURLs entry as follows:
Entry Management -> cn=OracleContext -> cn=Products -> cn=DAS -> cn=OperationURLs
After you select the
cn=OperationURLs entry, locate the orcldasurl attribute on the Properties tab in the right pane of the Oracle Directory Manager window.
See Also:"Using Oracle Directory Manager" in the Oracle Internet Directory Administrator's Guide
To complete the Oracle Internet Directory Upgrade, you must perform the following tasks:
Starting with release 10.1.2, a certificate hash value can be used to bind to Oracle Internet Directory. The introduction of this hash value requires that user certificates issued before release 10.1.2 be updated in the directory.
As a result, if you are upgrading from a release prior to 10g Release 2 (10.1.2), and if you if user certificates are provisioned in the directory, you must perform this additional post-upgrade step.
Note that this step is not required if you are upgrading from Oracle Internet Directory 10g Release 2 (10.1.2).
Complete instructions for running the Certificate Upgrade Tool (
upgradecert.pl) to perform this task are available in Appendix A, "Syntax for LDIF and Command-Line Tools," in the Oracle Internet Directory Administrator's Guide.
During the Oracle Internet Directory upgrade, LDAP objects within the directory are modified or added to the Oracle Internet Directory. These updates often include access control information.
In a production environment, customized access control policies are often enforced in the directory. For this reason, the upgrade process leaves certain entries in the directory untouched intentionally to retain any customized behavior you may have implemented in the directory.
Further, in some cases, the default, out-of-the-box access control settings are required for Oracle components to function properly. As a result, after the Oracle Internet Directory upgrade, you should analyze the differences between the default, out-of-the-box access control policies and any custom policies you have implemented. The result of this task should be a new set of customized access control policies that will meet the requirements of Oracle components, as well as the access control polices of your organization.
Even if you have not implemented any customized access control polices, Oracle strongly recommends that you manually update the ACLs with the new default values after an upgrade.
The following example uses "dc=acme, dc=com" as a default realm DN. In this example, consider the following when analyzing the ACL policy for your directory:
Realm DN (eg. dc=acme, dc=com)
Parent of the Realm DN. This is also known as the Realm Search Base, for example, "dc=com".
Realm User container. This is also known as the Realm User Search Base, for example, "cn=Users, dc=acme, dc=com". Depending on the deployment requirement, this can be customized.
Realm Group container. This is also known as the Realm Group Search Base, for example, "cn=Groups, dc=acme, dc=com". Depending on the deployment requirement, this can be customized.
The out-of-the-box access control policies is available in the following files:
Policies for the Parent of Realm DN can be found in the following file:
Policies for the Realm DN, Realm User container, and Realm Group container can be found in:
The default ACL policy is described in the Oracle Internet Directory Administrator's Guide, in Chapter 17, in the section on "Default Privileges for Reading Common Group Attributes".
If you upgrade a 9.0.x node to 10g (10.1.4.0.1) and then try to set up replication for this node, the replication server will fail to come up and the replication setup itself may fail. For information on changing and resetting the replication wallet password, see Section A.4.1, "Changing the Replication DN Password in the Oracle Internet Directory Wallet for Each Replica".
If you had an older version (9.0.2 or 9.0.4) of the Directory Integration Platform operating in a different Oracle home, on a different computer, and using the Oracle Internet Directory you are currently upgrading, and you want to continue using the Oracle Directory Integration Platform, you must re-register the Oracle Directory Integration Platform server.
See Also:Oracle Identity Management Integration Guide for instructions on registering the DIP server.
After you upgrade Oracle Internet Directory from 10g (9.0.4) to 10g (10.1.4.0.1), you could observe some degradation in the performance of some LDAP queries.
To remedy this issue, perform the following procedure, which updates some database statistics in the Oracle Database 10g database that hosts the Oracle Internet Directory server:
In the newly upgraded Oracle Internet Directory Oracle home, execute the following SQL script by connecting to the OID database as the ODS database user:
sqlplus ods/<passwd> @%ORACLE_HOME%/ldap/admin/oidstats.sql
Restart the Oracle Internet Directory server as follows:
Run the following command to stop the Oracle Internet Directory server:
opmnctl stopproc ias-component=OID
Wait a few seconds for the Oracle Internet Directory server to shut down completely.
Run the following command to start the Oracle Internet Directory server:
opmnctl startproc ias-component=OID
Similarly, if you are running in an environment where the database that hosts the Oracle Internet Directory is upgraded before you upgrade the Oracle Internet Directory, you should gather the database statistics immediately after the database upgrade by running the following SQL command on the database:
When you upgrade Oracle Internet Directory from 10g (9.0.4) to 10g (10.1.4.0.1), all attributes in the DSA Configuration entry are reset to their default values. For example:
cn=dsaconfig,cn=configsets,cn=oracle internet directory
As a result, if any attributes in this entry were modified before the upgrade, you must reconfigure them to their values before the upgrade.
When you upgrade Oracle Internet Directory from 10g (9.0.4) to 10g (10.1.4.0.1), some indexes are recreated automatically by the upgrade procedure. For example, the
EI_attrstore index is recreated automatically during the upgrade.
As a result, if you recreated the
EI_attrstore index before the upgrade, then the index will have to be recreated again after the upgrade. Note that recreating the
EI_attrstore index is part of the performance recommendation for large group entry lookups described in section "21.8.1 Optimizing Searches for Large Group Entries" of the Oracle Internet Directory Administrator's Guide. If you performed this procedure prior to the upgrade to 10g (10.1.4.0.1), you will need to perform this task again after the upgrade.
The Oracle Internet Directory database account ODSSM is used to access server manageability information from the database. During upgrade to 10g (10.1.4.0.1), this account is created and given a randomly-generated password.
The credentials for this account, including the randomized password are stored in the Oracle Internet Directory snippet in the Enterprise Manager file
The only way you can change this account's password is to use SQLPLUS. There is no support in the
oidpasswd tool for changing this password. Also, its password is not stored in a wallet. After altering this password in the database, you must also change it in the file
targets.xml. You do this either by setting the new values in the user and password fields or by running the tool
To complete the OracleAS Single Sign-On upgrade, depending on the configuration upgraded, you may need to perform the tasks described in the following sections:
If the 10g (9.0.4) or 10g Release 2 (10.1.2) middle tier for the Single Sign-On server had custom configurations (for example, Oracle HTTP Server configured for SSL, or the Oracle Application Server Single Sign-On server Database Access Descriptor had any custom configuration), then you must re-configure the upgraded 10g (10.1.4.0.1) middle tier in a like manner.
See Also:Oracle Application Server Single Sign-On Administrator's Guide for instructions on configuring the middle tier.
If you are using OracleAS Portal and you reconfigure the 10g Release 2 (10.1.2) middle tier for SSL, the URL used for Oracle Delegated Administration Services might not be up-to-date. To remedy this problem, force a refresh of the portal cache, which holds the relevant Oracle Internet Directory information:
Logon to OracleAS Portal as a user with administrator privileges.
Go to the Builder.
Click the Administration tab.
From the Portal tab, open Global Settings and navigate to the SSO/OID tab.
Scroll to the bottom of the page.
Check Refresh Cache for the Oracle Internet Directory parameters.
The page should refresh with the appropriate value in the DAS Host Name field.
See Also:Oracle Application Server Portal Configuration Guide
If the 10g (9.0.4) or 10g Release 2 (10.1.2) middle tier was configured to authenticate with a user certificate or third party authentication mechanism, then you must re-configure the 10g (10.1.4.0.1) OracleAS Single Sign-On server in a like manner.
See Also:Oracle Application Server Single Sign-On Administrator's Guide, Chapter 13, for instructions on configuring the middle tier.
If you have customized the login, password and the sign-off pages in the 10g (9.0.4) or 10g Release 2 (10.1.2) Single Sign-On server, then you must update those pages with 10g (10.1.4.0.1) specifications. This is also applicable if you have enabled support for Application Service Providers and updated the deployment login page to enable the company field.
See Also:Oracle Application Server Single Sign-On Administrator's Guide, Chapter 12, for instructions on configuring the middle tier.
If you are using Oracle Internet Directory replication and want to also use OracleAS Single Sign-On replication, add the upgraded 10g (10.1.4.0.1) tables in the replication group along with 9.0.4 Oracle Internet Directory. Follow the steps below to add OracleAS Single Sign-On tables for replication:
Stop the Oracle Internet Directory replication server on all replicas of the Directory Replication Group.
On the Master Directory replica, in
$ORACLE_HOME/ldap/admin, issue the following command:
Start the Oracle Internet Directory replication server on all replicas of the Directory Replication Group.
See Also:Oracle Internet Directory Administrator's Guide, Chapter 25, "Managing Directory Replication", for instructions.
If the 10g (9.0.4) or 10g Release 2 (10.1.2) OracleAS Single Sign-On server was using a middle tier other than the default mid-tier installation along with the OracleAS Single Sign-On server, then you must configure that middle tier to point to the upgraded OracleAS Single Sign-On server.
For example, if there was a reverse proxy configured in the 10g (9.0.4) or 10g Release 2 (10.1.2) OracleAS Single Sign-On server middle tier, then you must configure it on the 10g (10.1.4.0.1) OracleAS Single Sign-On server middle tier.
If you want to use wireless voice authentication with the 10g (10.1.4.0.1) OracleAS Single Sign-On server, and it doesn't work, verify that the OracleAS Single Sign-On server entry is a member of the Verifier Services Group in Oracle Internet Directory (
cn=verifierServices,cn=Groups,cn=OracleContext). This is a requirement for the wireless voice authentication feature. Follow the steps below to verify membership:
Issue the following command:
ldapsearch -h host -p port -D "cn=orcladmin" -w password -b "cn=verifierServices, cn=Groups, cn=OracleContext" "objectclass=*"
The OracleAS Single Sign-On server is a member of the Verifier Services Group if it is listed as a
uniquemember in the entry, as shown in Example 9-2.
If you did not select any languages during the OracleAS Single Sign-On upgrade, or you want to install additional languages after the upgrade, you can install the necessary languages by following the steps below.
Copy the necessary language files from the Repository Creation Assistant CD-ROM to the OracleAS Single Sign-On server Oracle home:
copy repCA_CD\portal\admin\plsql\nlsres\ctl\lang\*.* DESTINATION_ORACLE_HOME\sso\nlsres\ctl\lang
In this example,
lang is the language code. For example, the language code for Japanese is
Load the languages into the server.
See Also:Oracle Application Server Single Sign-On Administrator's Guide, Chapter 2, "Configuring Globalization Support" section, for instructions on loading the languages.
After the upgrade, you will notice additional and obsolete partner applications on the OracleAS Single Sign-On Partner Application administration page.
For example, you will notice two Oracle Application Server Certificate Authority (OCA) partner applications and two OracleAS Wireless partner applications.
You can safely remove the 10g (9.0.4) OCA partner application that uses port 4400.
See Also:Section 10.2, "Task 2: Decommission the OracleAS Identity Management Source Oracle Home" for specific instructions about removing source components from the list of partner applications
As for the OracleAS Wireless partner applications, the 10g Release 2 (10.1.2) Oracle HTTP Server configuration is changed after during the upgrade to use the 10g (9.0.4) HTTP Server port; this partner application is not valid and can be removed. The valid OracleAS Wirelesspartner application is the upgraded partner application, which existed in the 10g (9.0.4) environment.
Review the list of partner applications for any other obsolete or already upgraded components or applications.
See Also:Section 10.2, "Task 2: Decommission the OracleAS Identity Management Source Oracle Home" for information about removing the partner applications that represent the OracleAS Identity Management installations you have upgraded
The following sections describe how to complete the upgrade of the OracleAS Portal schema.
Note:The procedures described in this section must be performed only if you run the 10g (10.1.4.0.1) Metadata Repository Upgrade Assistant (MRUA) and MRUA reports that the PORTAL schema was upgraded to 10g Release 2 (10.1.2.0.2).
If the MRUA output indicates that the PORTAL schema was already upgraded, then there is no need to perform the steps listed in this section.
After the script has executed successfully, start each middle tier that is using the upgraded Portal instance by performing these steps:
Start OPMN and its managed processes by starting the Process Manager service in the Services control panel.
Start the Application Server Control service in the Services control panel.
By default, the portlet repository is upgraded in-place in the OracleAS Portal schema. The existing pages, templates, items, and so on, in the portlet repository are upgraded, and the new portlets are added into the repository. Since the old settings are preserved, the pages look very similar to the way they did before the upgrade was run.
Note:If your starting version is Oracle9iAS Portal 9.0.2 and you had rendered the Portlet Repository as grouped by Provider names, then after the upgrade, the folders in the repository will be grouped by category, because the Group by Provider Name option has been deprecated since OracleAS 10g (9.0.4).
To create a similar organization, assign the portlet names to categories representing the Provider names.
If you want the repository to have the appearance of a newly installed instance, a script is available to re-create the upgraded portlet repository. The script removes the existing portlet repository and re-creates it. Use the script only if you do not wish to preserve customizations, settings, styles, banners, and so on in the portlet repository.
To re-create the portlet repository, follow these steps after starting the middle tiers as described in Section 9.4.1, "Starting all Middle Tiers That Use The Upgraded Portal Instance":
Perform a backup of the database, since the script overwrites the repository and is not reversible.
Navigate to the following directory on the OracleAS Metadata Repository Upgrade Assistant and Utilities CD–ROM, which contains the
Log in to the OracleAS Metadata Repository database as Portal schema user from SQL*Plus.
If there were no errors in the OracleAS Portal Repository upgrade, you can access your upgraded Portal. Open a browser and navigate to the following URL:
Missing Oracle Text indexes are created during the OracleAS Portal upgrade process, but they are not populated, as this can be very time consuming. The new indexes are populated once the upgrade is complete, when the next synchronization job is scheduled.
If you need to shut down the database after the upgrade (to back up) and the Oracle Text index synchronization job has started, consider the impact of the following shutdown commands on the synchronization process:
Shutdown Immediate or Abort
The indexing job stops immediately and is rolled back.
Entire indexing job finishes before the database shuts down.
Synchronization of the current index is allowed to finish before the database shuts down. If one or more indexes still need to be synchronized, synchronization of the next index is not started.
There were two options provided for resolution of this issue:
Setting up of a common-domain by running the script secjsdom.sql
Deploying DAS on the middle tier.
In OracleAS Portal 10g Release 2 (10.1.2), the implementation of the LOVs has been modified to support a callback method, removing the cross-domain issue and the need for the configuration steps above. However, this callback mechanism requires a corresponding patch to the DAS environment to support the use of LOVs across domains.
Support for the callback method has been included in DAS versions 188.8.131.52 and later. Conversely, if you are using DAS version 184.108.40.206 you can apply patch 3278638 to enable callback support.
If you have installed the appropriate DAS version in your environment, and have not previously implemented the configuration options mentioned above, then no subsequent configuration steps are required in OracleAS Portal to support the LOVs on a separate host. However, if you used the configuration options mentioned above, it is required to remove these steps. This can be done as follows:
If a common domain was defined, reset it by executing the secjsdom.sql script as follows:
From your operating system command prompt, go to the following directory:
Using SQL*Plus, connect to the OracleAS Portal Repository as the schema owner and run the following commands:
@secjsdom '' commit;
If OracleAS Portal has been configured to use a locally deployed DAS servlet, reconfigure it to point to the Infrastructure tier by running the secdaslc.sql script as follows:
From the operating system prompt, go to the following directory:
Using SQL*Plus, connect to the OracleAS Portal Repository as the schema owner and run the following commands:
@secdaslc N commit;
If you have customized the login portlet, you must update it to work in this release. In prior releases, user credentials were posted to OracleAS Portal's
wwptl_login.login_url procedure. In this release, the user credentials must be passed to OracleAS Single Sign-On's
wwsso_app_admin.ls_login procedure instead. Follow the steps outlined in OracleMetaLink note
290445.1 to update your customized login portlet to use
Note:You do not have to perform any additional steps at this time if you followed the instructions provided in the patch documentation after applying Oracle Application Server 10g (9.0.4) Patch Set 1 (220.127.116.11), or any of the following one-off patches:
To generate performance reports for OracleAS Portal, you must use a set of SQL scripts. These scripts are used to load OracleAS Portal log files into a database table and create reports based on that information. The scripts are located in the following directory:
If you are already using the performance reporting scripts, then after upgrading to OracleAS Portal 10.1.2.0.2, you must run the new copy of the following file:
This is to accommodate the new URL format for Repository requests and to enable collection of new data. If this is not done, then the scripts will not work.
For details about how you can use the scripts to monitor OracleAS Portal performance, refer to the following file in the scripts subdirectory:
The following sections describe the tasks you must perform in order to complete the Oracle Application Server Wireless upgrade:
In 10g (10.1.4.0.1), Oracle Internet Directory does not automatically set unique constraints on any user attributes. Wireless voice authentication will not function properly unless a unique constraint is set on the
orclWirelessAccountNumber attribute of the
orclUserV2 object class.
Set the unique constraint by performing the steps below after the middle tier and infrastructure upgrades are complete.
The script takes one argument, the full path to the Oracle home. For example:
Restart the Oracle Internet Directory server.
In Oracle Application Server 10g (10.1.4.0.1), by default, the OracleAS Wireless application entity does not have the privileges to change the user password. Consequently, upon installation, users cannot change the password to the OracleAS Wireless server. However, you can enable functionality to change passwords by assigning the
UserSecurityAdmins privilege to the OracleAS Wireless application entity.
To do this, execute the following script:
The syntax is:
assignUserSecurityAdminsPrivilege.bat oid_super_user_dn user_password
In this example:
oid_super user_dn is the Distinguished Name of the Oracle Internet Directory super user. This user should have privileges to grant UserSecurityAdmins privileges to application entities.
user_password is the password of the Oracle Internet Directory super user.
assignUserSecurityAdminsPrivilege.bat "cn=orcladmin" welcome1
See Also:"Resetting the Password" in Oracle Application Server Wireless Administrator's Guide
When you use the HTTP adapter to build Wireless services, one of the service parameters that you must specify is the URL to a back-end application. In some cases, you may send some query parameters to the back-end application. There are two ways to do this from OracleAS Wireless, shown in Example 9-3 and Example 9-4. In Example 9-3, the parameter name is
fn and the value is
The query parameter is sent only in the request for the first page of that service. If there is a link from the first page to some other pages, then the parameter is not added to the request for those pages.
Instead of modifying the URL, you add an extra service parameter with name
fn and value
Joe. The the parameter is sent to all pages, not just the first one. The parameter is also sent with all HTTP redirect requests. However, this method also sends extra URL parameters to the OracleAS Single Sign-On server, which causes the server to return an error.
The error occurs when the back-end application is protected by mod_osso. In that case, the request to that application is intercepted and redirected to the Oracle SSO server for user authentication. The OracleAS Single Sign-On server has restrictive rules concerning query parameters that can be sent to it. Consequently, for back-end applications protected by mod_osso, you must change the Wireless service and add the query parameter to the URL as shown in Example 9-3.