| Oracle® Access Manager Upgrade Guide 10g (10.1.4.0.1) Part Number B25354-01 |
|
|
View PDF |
| Oracle® Access Manager Upgrade Guide 10g (10.1.4.0.1) Part Number B25354-01 |
|
|
View PDF |
In addition to the guidelines and techniques presented throughout this guide, this chapter provides troubleshooting details that you can employ during or after the upgrade process. Topics include:
Authorization Failure Re-direct Problems After Upgrading from 6.1.1
Compatibility of Earlier Plug-ins in the Upgraded Environment
During each component upgrade, one or more log files may be produced to inform you if any problem should arise. If a log file is created, a message during the upgrade process indicates the name and location of each log file created. In general, you can find upgrade log files in:
\Component_install_dir\identity|access\oblix\tools\migration_tools\toolname.log
where \Component_install_dir is the directory where the specific component is installed; identity|access represents the system to which the component belongs (Identity System or Access System, respectively); and toolname represents the name of the utility that produced the log. For example, the following log files may be generated:
Each log file contains information about a particular activity that occurs during the component upgrade. For example, a separate log file may be generated for file upgrades, or message and parameter upgrades, or the Oracle Access Manager schema upgrade to name a few.
In general, log files include the following information that you can use to troubleshoot specific problems:
A snapshot of the steps being executed by the respective tool is recorded to help you identify any failure points.
Any argument details passed while the tool is executing the tool is logged to help you detect any incorrect values that were passed. This can also help if you need to execute the tool manually.
Return code details are logged to help you identify any error being returned. You can communicate the specific error to Oracle Support for analysis.
During parameter and message catalog upgrades (performed by the obmigrateparamsg tool) a corresponding log file (obmigrateparamsg.log) shows all files that have got upgraded. This helps you identify any missing files to detect any loss of customizations.
Component-specific log files show the changes that were completed for that specific component. Changes include any component-specific configuration file and registry changes occurring during the upgrade. This helps you identify any upgrade failures for the respective component.
For information about specific log files, their content, and the tools that generate them see Appendix B, "Upgrade Process and Utilities".
Additionally, the following files are created to log any ldap specific errors:
During Identity Server data migration, error_output_fromversion_to_toversion_osd.ldif file is created in the IdentityServer_install_dir\identity\oblix\tools\migration_tools\obmigratedata directory.
During Policy Manager data migration, error_output_fromversion_to_toversion_psc.ldif file is created in the PolicyManager_install_dir\access\oblix\tools\migration_tools\obmigratedata directory
If you have a newly installed Access Server that does not appear to process information from an earlier WebGate, there may be a backward compatibility problem.
Upgraded Access Servers are automatically enabled for backward compatibility with earlier WebGates. However, if you install a new 10g (10.1.4.0.1) Access Server in an environment that includes earlier WebGates, you must manually set the "IsBackwardCompatible" Value="true" in the newly installed Access Server globalparams.xml to enable communication with earlier plug-ins and interfaces, as well as earlier WebGates and custom AccessGates. See also "Access Server Backward Compatibility".
If you had auditing and access reporting configured in your earlier environment, you need to perform specific steps to ensure you can continue using this function. Otherwise, you may notice that some language characters (for example, Chinese or Japanese) in audit records are not being inserted correctly.
The steps you need to take to accommodate globalization changes, even when you have an English only environment, depends on the type of database you are using.
|
Note: Simply upgrading or altering existing database instances and tables is not supported and could result in permanent truncation and loss of existing data. |
Task overview: Correcting auditing and access reporting issues
If your environment includes an Oracle database instance for auditing, you can check to ensure that your database character set is AL32UTF8.
Review and complete all steps in "Upgrading Auditing and Access Reporting for the Identity System".
Review and complete all steps in "Upgrading Auditing and Reporting for the Access Server".
Users with non Latin-1 login IDs may not be able to log in successfully when using a custom form. This problem can occur when you have internationalized data in your custom login forms, but you have not updated the login HTML encoding to UTF-8.
As discussed in Chapter 4, "System Behavior and Backward Compatibility", in 10g (10.1.4.0.1), form-based authentication supports non-ASCII login credentials (username/password). When you use form-based authentication with 10g (10.1.4.0.1) WebGates, you must ensure that character set encoding for the login form is set to UTF-8.
|
Note: Basic Authentication fails with non-ASCII login credentials. Use form-based authentication for non-ASCII login credentials. Use Basic Authentication with ASCII login credentials. |
To correct problems with form-based authentication, see "Upgrading Forms-based Authentication".
Problem: Authorization failure redirects may not work as expected after upgrading from release 6.1.1.
Cause: A new authorization inconclusive state was introduced in release 7.x (apart from authorization success and failure states).
Solution: In the Authorization Rule, be sure to specify an explicit Deny rule and change Allow takes precedence to Yes under the General panel. For more information, see "Assuring Proper Authorization Failure Re-directs After Upgrading from 6.1.1".
Problem: If your earlier environment has the challenge phrase and response attributes on separate panels, then the response attribute will not be displayed in the Profile page.
Cause: In earlier releases, the challenge phrase and response attributes were allowed on different panels of the Profile page of the User Manager, Group Manager, and Organization Manager. In 10g (10.1.4.0.1), however, both the challenge phrase and response attributes must be on the same panel.
Solution: You need to update your panel definitions to include the response attribute on the same panel as the challenge attribute. For more information, see "Combining Challenge and Response Attributes on a Panel".
If you choose to manually migrate data during an upgrade (exporting user data from old instance into new instance which is not recommended), the Challenge Response for lost password management may not convert properly. As a result, some users will not be able to use the lost password feature. For example, when providing a correct response on the Lost Password Management page the user cannot reset the password. Also some users might not be able to set new responses, basically it will complain that the old response is not correct.
The Challenge Response value is encrypted with the shared secret in the CPResponseEncryptionKey node, using the RC6 encryption algorithm. The Challenge Response encryption key contains the attributes:
DN:
cn=CPResponseEncryptionKey,obcontainerId=encryptionKey,o=Oblix,<container> Attribute: obSecretSize Attribute: obSharedSecret
where Attribute: obSharedSecret is a binary attribute.
|
Note: If the configuration tree moved or a different directory server is used in the upgraded environment, the shared secrets may not match. |
To ensure the Challenge Phrase Response is properly converted
Use caution with the shared secret, which cannot be copied and pasted.
Manually document the shared secret in your original configuration tree and add it to the 10g (10.1.4.0.1) configuration tree.
For more information, see "Encryption Schemes and the Shared Secret" and "Checking Compatibility with Previous Releases".
If your earlier customized plug-ins are not operating as expected after the upgrade when working with internationalized data (that is, non latin-1 data), you need to redesign these to ensure they can process UTF-8 encoded data. To send or receive internationalized data, earlier custom plug-ins must be redesigned to use UTF-8 encoding.
Also, on Solaris and Linux, plug-ins earlier than release 7.x must be re-compiled using the GCC v3.3.2 C++ compiler, regardless of the compiler that may be provided with the Operating System.
|
Note: Release 7.0 plug-ins as well as earlier plug-ins implemented as executables or those using a scripting language (such as perl) do not require recompiling after the upgrade. However, to send and receive internationalized data, earlier plug-ins should be redesigned to communicate using UTF-8 encoding. |
To ensure compatibility of your earlier plug-ins in the upgraded environment, see:
Broken images or the incorrect appearance of a customized Graphical User Interface (GUI) or JavaScript errors is an indication that earlier customizations have not been manually incorporated into the upgraded environment.
As discussed earlier, customized .XSL style files, images, and JavaScript files are not migrated during the upgrade. If your previous installation includes significant changes to earlier XSL stylesheets, or if you use a style other than the Oracle Access Manager default Classic Style, you need to manually include those changes in 10g (10.1.4.0.1) stylesheets, images, and JavaScript files.
|
WARNING: If you simply copy earlier stylesheets, you may receive stylesheet bug reports or experience unpredictable behavior when using new features designed to work with new stylesheets. |
For details about migrating customized styles, images, and JavaScript (including message handling), see details in Chapter 12, "Upgrading Your Identity System Customizations".
If previous installations and upgrades have left behind a vpd.properties file, you may have trouble when you specify the installation directory. This may occur if a component installation terminates (or is terminated by you) after component files were extracted to the designated installation directory and you simply remove the installation directory without running the Uninstaller. In this case, you are left with an inconsistent vpd.properties file.
Before starting an upgrade you need to remove this file.
To remove the vpd.properties file
Locate the vpd.properties file. For example:
On Windows NT: vpd.properties file is located in c:\WINNT.
On Unix: The vpd.properties file is located in the home directory of the user running the installer
Delete it.
After the upgrade if you notice that your portal inserts are not working as expected, you need to ensure that your portal insert URLs have been manually updated for UTF-8 encoding. Also, to use internationalized data in PresentationXML requests, these requests must indicate UTF-8 encoding.
Oracle Access Manager 10g (10.1.4.0.1) cannot detect query string character encoding and assumes it to be UTF-8. The 10g (10.1.4.0.1) Identity Server cannot process Latin-1 data from earlier Portal Inserts. After upgrading to 10g (10.1.4.0.1)), you must change the encoding of the query string in earlier Portal Inserts from Latin-1 to UTF-8.
To ensure compatibility with portal inserts in your environment, see "Ensuring Compatibility with Earlier Portal Inserts".
You should not experience any problems in this area following an upgrade. Refer to following discussions for more information:
If you have a newly installed Identity Server that does not appear to process information from an plug-in, there may be a backward compatibility problem.
Upgraded Identity Servers are automatically enabled for backward compatibility with earlier plug-ins. However, if you install a new 10g (10.1.4.0.1) Identity Server in an upgraded environment you must manually set the encoding flag in the Identity Server oblixpppcatalog.lst to enable communication with earlier plug-ins and interfaces. See also "Identity Server Backward Compatability".
IdentityXML calls require authentication credentials. If there is no WebGate protecting WebPass, then the basic credential mechanism is used. This takes the form of username and password embedded in the SOAP request itself. However, when a WebGate is installed later, then the IdentityXML calls must be changed to use a SSO token-based authentication.
The IdentityXML calls need to be changed to first obtain an OBSSOCookie, and then pass that token into all the subsequent calls. An example of how to do this is shown in the Oracle Access Manager Developer Guide. Look for details on code examples of deployed IdentityXML functions, and the ObSSOCookie Example.
If you are upgrading from Oracle Access Manager 5.2.x on Windows 2000 SP3, you may receive LDAP add errors during the upgrade. If you receive these errors, you may need to set the replication agreements for the machines.
To you receive LDAP add errors in your Windows environment
Install the Support Tools from the Windows 2000 CD.
Run the dcdiag program, optionally using the /v command-line option.
Under the Replication test, check for failures.
If failures are reported, use the next procedure to troubleshoot LDAP add errors.
To troubleshoot LDAP add errors in a forest
Confirm that the clocks are synchronized for the domain controllers.
On the command line for all domain controllers in the forest, enter the following:
net time /setsntp:machine name
Use the same machine name so there is minimal clock skew.
Set the group policy for replication:
Open the Users and Computers tool.
Go to Domain Controllers, right click, and select Properties.
Under the Group Policy tab, select Default Domain Controllers Policy, select Computer Configuration, then click Windows Settings.
Select Security Settings, select Local policies, then click User Rights Assignment.
From the right hand side, select Access this computer from the network.
Add ENTERPRISE DOMAIN CONTROLLERS to the access list.
Do a replication using the Sites and Services tool:
Go to Sites, select Default-First-site-name, then select Servers.
Select the server name.
Select NTDS settings.
Right click <automatically generated> on the right hand side, and select replicate now.
Enter the dcdiag program again on the command line to see if the replication test is now working.
After performing these steps, the schema migration should work properly.
If you attempt to upload and use the full schema installation files for any directory during the upgrade (instead of using release-specific delta files for an existing schema), the operation will fail. This is because the schema already exists and the files used to upgrade an existing schema provide only the difference between the existing schema and the next release.
For example, suppose you have an installation with ADAM as the directory. If you attempt to upload and install the complete (new installation) schema file (ADAM_oblix_schema_add.ldif andADAM_user_schema_add.ldif) rather than release-specific delta-content files (osd_650_to_700_schema_adam.ldif and policy_650_to_700_schema_adam.ldif) the process will fail. This is because the schema already exists.
Guidelines
Oracle recommends that you accept automatic schema and data upgrades.
If you must manually update the schema and data (for ADAM, for example), use only those release-specific delta-content files provided to upgrade your directory schema.
You may notice that your mime_types-related customizations are not reflected in the attribute configuration applet in the System Console.
When upgrading, multiple entries with the same ParamName in mime_types (.xml and .lst) files are not retained:
The .xml version of the file is used by the Identity Server. The .lst version of the file is used by the WebPass Java applet. Both versions of the file must match. Both versions of the file must reside in the IdentityServer_install_dir and in the WebPass_install_dir.
For example, if your original mime_types.xml file in IdentityServer_install_dir/identity/oblix/apps/admin/bin/mime_types.xml contains the following NameValPair ParamNames:
<NameValPair ParamName="application/postscript" Value="ai1"/> <NameValPair ParamName="application/postscript" Value="eps1"/> <NameValPair ParamName="application/postscript" Value="ps1"/>
the following entries will occur in the newly upgraded file:
<NameValPair ParamName="application/postscript" Value="ai1"/> (CORRECT) <NameValPair ParamName="application/postscript" Value="eps"/> (INCORRECT) <NameValPair ParamName="application/postscript" Value="ps"/> (INCORRECT)
For existing user entries, the MIME type is stored along with the user entry in the directory. As a result, there is no impact on existing user entries and Oracle Access Manager installations after the upgrade.
|
Note: Both .lst and .xml versions of the file are needed. You may remove MIME types that are no longer needed or add new MIME types to be associated with the particular attribute for further use. Simply edit the mime_types.lst and .xml files for the Identity Server, then copy these into the WebPass_install_dir to replace the earlier version. |
To ensure MIME type files are accurate and available in the upgraded environment
Edit the Identity Server mime_types.lst file if needed to remove MIME types that are no longer needed or add new MIME types to be associated with the particular attribute for further use.
Edit the Identity Server mime_types.xml file to match your edited mime_types.lst file.
Copy both Identity Server mime_types files (.lst and .xml) in to the WebPass_install_dir to replace the earlier version.
If you do not upload the indexes for iPlanet and NDS directories, the product will work. However, searching will be inefficient and impact performance.
For details, see "Uploading Directory Server Index Files".
The release numbers in this discussion are for illustration only and related to the information in Appendix D, "Upgrading Sun Web Server Version 4 to Version 6 on Windows 2000". Specific details of the intermediate upgrade from earlier Oracle Access Manager releases to release 6.1.1 are outside the scope of this manual. Before you start upgrading from a release earlier than Oracle Access Manager 6.1.1, contact Oracle Support at http://www.oracle.com/support/contact.html.
There are several potential issues that may occur after upgrading to Sun release 6.0 Web server and upgrading to the Oracle Access Manager 7.0 Identity System.
During the upgrade, the following entries are added to obj.conf:
NameTrans fn="pfx2dir" from="/identity/oblix" dir="G:/70/webpass/identity/oblix" name="idoblix" ……<Object name="idoblix">PathCheck file=".nsconfig" fn="load-config" descend="1"</Object>
However, in the Oracle Access Manager 5.2 Identity System installed on a version 4.1 Web server, the obj.conf does not contain the entries underlined earlier. Even when the version 4 Web server is migrated to release 6 and Oracle Access Manager is upgraded to release 7.0, these entries are not included in obj.conf.
If you have enabled cgi for the 4.1 iPlanet instance, the URL prefix and script directory settings are carried over exactly during migration. If this directory is under the version 4.1 document root, you might want to change this directory by:
Either using the release 6.0 Web server Admin Console (Class manager > Programs)
Or by hand editing the appropriate line in obj.conf
For example, an example line in the 6.0 obj.conf is shown next:
NameTrans fn="pfx2dir" from="/cgi-bin" dir="D:/NSWS/Server4/docs/cgi-bin"
name="shellcgi"
|
Note: It is a good idea to search the migrated obj.conf for the old install area (in this case D:/NSWS/Server4) to make sure that the 6.0 instance of the server does not refer to the old install area in any way. |
In the file jvm12.conf in the Web server config directory, the following line can be found after migration. This property contains references to the old (4.1) bits and is not correctly migrated:
jvm.classpath=D:/NSWS/Server4/plugins/samples/servlets/beans.10/SDKBeans10.jar; D:/NSWS/Server4/plugins/samples/servlets/beans/SDKBeans.jar;D:/NSWS/Server4/bin /https/jar/Bugbase.jar;D:/NSWS/Server4/bin/https/jar/Calljsac.jar
This line should be replaced by the following:
jvm.classpath=G:/iPlanet6WS/plugins/servlets/examples/legacy/beans.10/SDKBeans 10.jar
|
Note: The other jars are not to be included in the release 6.0 Web server configuration and have been intentionally left out. |
Any files or folders that were in your old document-root need to be copied manually to the same structure in the new document-root. This is important if you want the new Web server instance to behave exactly as the old one.
As noted earlier, both Admin Consoles (version 4.1 and version 6.0) can operate the server, which work using the 6.0 binaries. The Admin Consoles simply use the Windows NT service to start/stop the server.
From the 4.1 Console, if you delete the old instance the result is deleting the service and the version 4.1 files. If this happens, even the 6.0 Console cannot operate the instance, because the service has been deleted. Since this is not desirable, the following steps are required:
Stop the server (from either the version 4.1 or the release 6.0 console or using the NT service).
If you want to preserve the logs and the like, back up the old logs directory manually.
Delete the version 4.1 instance directory manually.
Restart the version 4.1 Admin Console.
|
Note: The upgraded server is no longer available for the version 4.1 Admin Console to manage. |
This completes the process.
If you do not upload appropriate indexes for Oracle Internet Directory after the schema and data upgrade, users will not be able to login.
For details, see "Uploading Directory Server Index Files".
During installation of the integration connector for WebSphere Application Server and Portal Server, you are asked to provide the WebSphere classes directory path so the following files are added:
jobaccess.jar and NetPointWASRegistry.jar
However, during the upgrade of the integration connector for WebSphere Application Server and Portal Server, you are not asked for this directory. Instead, you need to manually copy the three files (listed in the following example) into the directory following the upgrade, then restart the Websphere Application Server and the Portal Server.
There is no NetPointCMR.jar in a release 6.5 installation.
For more information, see "Upgrading Third-Party Integration Connectors".
