Tasks in this chapter are intended for administrators who are responsible to upgrade and redeploy earlier Access System customizations. Oracle recommends that you upgrade and then test your upgraded customizations in a small isolated environment.
Unless explicitly stated, the information in this chapter applies to both upgrade methods. The tasks you perform will depend on what was implemented in your earlier installation. You can skip any task that is not relevant for your earlier environment. This chapter includes the following topics:
Recompiling and Redesigning Custom Authentication and Authorization Plug-Ins
Associating Release 6.1.1 Authorization Rules with Access Policies
Assuring Proper Authorization Failure Re-directs After Upgrading from 6.1.1
Updating the ObAMMasterAuditRule_getEscapeCharacter in Custom C Code
Recovering from an Access System Customization Upgrade Failure
Note: When you are performing a zero downtime upgrade, Oracle recommends that you perform these tasks and test your upgraded customizations in the cloned environment. For more information, see "Customization Upgrades Using the Zero Downtime Upgrade Method". |
Before starting to upgrade any Access System customizations, Oracle recommends that you:
Upgrade and redeploy any Identity System customization upgrades, as described in Chapter 12.
Review information in "Customization Upgrade Planning".
Back up the directory containing the earlier customization and store it in a new location to help you if you decide to roll back to this later.
After completing and testing each upgraded customization, Oracle recommends that you back up the directory containing the upgraded customization and store it in a new location.
As discussed earlier, you complete a few activities to ensure that your auditing and access reporting environment is properly set up for Oracle Access Manager 10g (10.1.4.0.1). To complete activities for the Access Server, you will use information available in the file:
AccessServer_install_dir\oblix\reports\crystal\audit.sql
The procedures are similar to those you performed for the Identity Server, as outlined next. For details about individual steps within the task here, including uploading the audit schema, see the Oracle Access Manager Identity and Common Administration Guide. For general information about the procedures, see "Upgrading Auditing and Access Reporting for the Identity System".
Task overview: Upgrading auditing and reporting with a Microsoft SQL Server
Retain the original database, as is, to preserve your original data.
After upgrading all Policy Managers, upgrade the first Access Server (but do not restart the Access Server Service).
If you are using an MS SQL database, review information in "Database Record Sizing".
To query or generate any report that requires data from both the old and new database, you must import the earlier data audited by each Access Server instance into the 10g (10.1.4.0.1) database and confirm that it is imported successfully. You will repeat this step for each Access Server instance that you upgrade.
The serverId
field in audit table indicates the ID of the Access Server that audited that record. Based on the serverId
field, it is feasible to differentiate the records audited by each Access Server. The same rule applies to the Identity Servers.
Note: With an MS SQL database instance, earlier data might be truncated, as described in "Database Record Sizing". There is no data truncation with an Oracle database instance. |
Change the DSN (ODBC Data Source Name used by the RDBMS profile of audit & reporting applications) on this computer to refer to the new database instance.
Note: If you have multiple Access Servers on the same computer, be sure to upgrade all Access Server instances on this computer before you change the DSN to refer to the new database. |
Start the Access Server service.
The Access Server will now audit and store data in the new database instance. However, other Access Servers will continue to audit and store data in the old database instance.
Upgrade all other Access Server instances as follows:
Upgrade the next Access Server instance but do not restart the Access Server service.
Repeat step 4 to import data for this Access Server instance.
Note: If you have multiple Access Servers on the same computer, be sure to upgrade all Access Server instances on this computer before you change the DSN to refer to the new database. |
Repeat step 5 to change the DSN (ODBC Data Source Name used by the RDBMS profile of the audit & reporting applications) on this computer to refer to the new database instance.
Repeat step 6 to restart the Access Server service on this computer.
Repeat this step (7) for all Access Servers in your environment.
After upgrading all Access Server instances, you complete the rest of the Access System deployment-specific activities in this chapter. You can upgrade WebGates as described in"Upgrading WebGates In Place".
Start auditing, as described in the Oracle Access Manager Identity and Common Administration Guide.
If your previous Access System installation was configured for failover or load balancing, it is a good idea to verify that these configurations are still working properly.
During Policy Manager Upgrades: When creating the Directory Server Profile during the incremental upgrade to release 6.5, directory server credentials are read from:
PolicyManager_install_dir/access/oblix/config/userDB.lst
If the configuration tree is in the user directory server and under the user node, then the configuration directory profile is not created. Otherwise, a configuration directory profile is created using directory server information from:
PolicyManager_install_dir/oblix/config/ldap/configdb.lst
The configuration directory profile is marked for use only by the Policy Manager. Profiles are not created for Policy Manager failover servers. In the case of release 6.1, if the policy tree was on a separate directory server a profile for policy data existed.
During Access Server Upgrades: Profiles are not created for the configuration or policy trees at this time. Before release 6.5, Access System connection pools values for Initial Connections
and Maximum Connections
appeared in the UserDB.lst and UserDBFailover.lst. These might not be retained. Also, many .lst files have been transformed into .xml files as part of the globalization effort.
After upgrading Access System Components, it is a good idea to verify the values for Initial Connections
and Maximum Connections
in the Database Instance profile of the newly created Directory Server profile.
To confirm failover, load balancing, and connection pool details after the Access System upgrade
From the Access System Console, select System Configuration, Server Settings.
Under the heading Configure LDAP Directory Server Profiles, select the name of the Profile you want to check.
On the Directory Server Profile page, confirm the servers that use the failover information and confirm that the information matches previous settings. For example:
Maximum Active Servers
Failover Threshold
Sleep For (Seconds)
Max. Session Time (Min.)
Locate the Database Instances list on the Directory Server Profile page and select the name of the Database Instance Profile you want to check.
In the Database Instance Profile, verify the values for Initial Connections
and Maximum Connections
.
Make any changes needed and save the profile.
Perform a test to ensure that everything is working as expected.
For more information about configuring failover and load balancing, see the Oracle Access Manager Deployment Guide.
As discussed in Chapter 4, 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.
To set the login form encoding to UTF-8 for 10g (10.1.4.0.1)
Add the following META tag to the HEAD tag of the login form HTML page.
<META http-equiv="Content-Type" content="text/html;charset=utf-8">
If you upgrade an earlier WebGate to 10g (10.1.4.0.1), you must also update the login form HTML page after upgrading.
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. |
Custom Access System plug-ins are copied into the target directory during the Access Server upgrade. However, as discussed earlier, earlier plug-ins send and receive data in Latin-1 encoding.To send or receive internationalized data you must re-design plug-ins to use UTF-8 encoding.
Solaris and Linux: Release 5.2 and 6.x plug-ins must be re-compiled using the GCC v3.3.2 C++ compiler. For more information, see "Plug-ins".
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 use authentication and authorization plug-ins in an upgraded environment
Create a folder in the top level of your Access API directory and copy your earlier plug-ins in to the new directory.
Redesign custom authentication and authorization plug-ins to use UTF-8 encoding, if desired.
Solaris and Linux: Recompile release 5.2 or 6.x plug-ins on platforms using the GCC v3.3.2 compiler.
WARNING: You must use the GCC v3.3.2 compiler, regardless of the compiler that might be provided with the Operating System. |
Complete any testing to ensure your plug-ins are working properly with 10g (10.1.4.0.1).
When using plug-ins that send and receive data in Latin-1 encoding, ensure that any new Access Servers added to the upgraded environment are backward compatible as described in Chapter 4.
You must recompile earlier AccessGates only if the 10g (10.1.4.3) SDK for .NET 2 is installed and you want to move forward with only .NET 2 AccessGates. For details about adding the 10g (10.1.4.3) SDK for .NET 2, see the Oracle Access Manager Developer Guide.
Access Servers can communicate with AccessGates that support the .NET 1 Framework and AccessGates that support the .NET 2 Framework. As a result, you can have a mixed environment that includes the upgraded SDK for .NET 1 and earlier AccessGates along with the 10g (10.1.4.3) SDK for .NET 2 and new AccessGates. In this case, you might not want to recompile earlier AccessGates.
For more information about the SDK and .NET, see "Installing the Access Manager SDK" in the Oracle Access Manager Developer Guide.
To recompile earlier custom AccessGates for .NET 2 support
Create a folder in the top level of your AccessGate directory and copy your earlier AccessGates in to the new directory.
Redesign custom AccessGates to use UTF-8 encoding, if desired.
.NET 2 SDK: Recompile any custom AccessGate with .NET 2.0.
Complete any testing to ensure your AccessGates are working properly in the upgraded environment.
If you upgraded from release 6.5 or later, you can skip this discussion.
During an upgrade, the names of any release 6.1.1 Authorization Rules move to the Authorization Rules tab of the corresponding policy domain. In addition, the original rule is renamed with a combination of the name of the Policy to which the rule belongs, followed by the Authorization Rule name: PolicyName_AuthorizationRuleName.
For example, suppose your 6.1.1 installation includes a Policy Domain (named MyPolicyDomain) with two policies (named P1 and P2). And suppose that you have three Authorization Rules associated with these two policies: rules "A1" and "A2" are associated with policy P1, and rule A3 is associated with policy P2. In this case, after the upgrade you will find the following (under the Authorization Rules tab of MyPolicyDomain):
P1_A1 P1_A2 P2_A3
To confirm Release 6.1.1 Policy Domain Authorization Rule names
After upgrading from release 6.1.1, navigate to the Policy Manager/Access System Console using the appropriate URL for your environment. For example:
http://hostname:port/access/oblix
where hostname refers to computer that hosts the Web server; port refers to the HTTP port number of the WebPass Web server instance; and /access/oblix connects to the Policy Manager and Access System Console.
On the Access System landing page, select the Policy Manager link.
On the main Policy Manager page, select My Policy Domains on the left side of the page.
On the My Policy Domains page, select the link to one of your earlier Policy Domains: DomainName.
On the domain page, select the Authorization Rules tab.
On the Authorization Rules page, look for the renamed rules which are sorted alphabetically.
Each authorization rule in your Policy Domains might include Allow Access and Deny Access conditions. The Allow Access condition of the rule specifies who is authorized to access a protected resource. The Deny Access condition of an authorization rule specifies the end users and groups of users who are explicitly denied access to a resource protected by the rule. If Allow Access or Deny Access conditions (or both) are specified and they do not apply to a user, the user is not qualified by the rule. If a user is unqualified by a rule, by default the user is denied access to the requested resource.
A new authorization state was introduced in release 7.x (apart from authorization success and failure states). This new state is "inconclusive". To accommodate this new state when your earlier installation included authorization failure redirects, you complete the procedure here to specify an explicit Deny rule and to change Allow takes precedence
to Yes
on the General panel of the authorization rule.
To reset your Authorization Rule
After upgrading from release 6.1.1, navigate to the Policy Manager/Access System Console using the appropriate URL for your environment. For example:
http://hostname:port/access/oblix
where hostname refers to computer that hosts the Web server; port refers to the HTTP port number of the WebPass Web server instance; and /access/oblix connects to the Policy Manager and Access System Console.
On the Access System landing page, select the Policy Manager link.
On the main Policy Manager page, select My Policy Domains on the left side of the page.
On the My Policy Domains page, select the link to one of your earlier Policy Domains: DomainName.
On the domain page, select the Authorization Rules tab.
On the Authorization Rules page, look for the renamed rules which are sorted alphabetically and select the rule you want to modify.
On the General panel, confirm that Allow takes precedence
is set to Yes
.
Select the Deny Access panel, then create or modify a rule to specify the users and groups who are denied access to resources protected by this rule (using the People, Role, Rule, and IP Address controls) as indicated in the Oracle Access Manager Access Administration Guide.
If your earlier installation does not use C code created with the Policy manager, that includes the ObAMMasterAuditRule_getEscapeCharacter you can skip this discussion.
An object of the ObAMMasterAuditRule class represents the master audit rule, which specifies global audit parameters and defaults to be used if there is no audit rule specified for a specific policy. In earlier releases, ObAMMasterAuditRule_getEscapeCharacter
returned the audit escape character. In 10g (10.1.4.0.1), the C language API the ObAMMasterAuditRule_getEscapeCharacter
remains and you can continue using this. However, the audit escape character must be an ASCII character; otherwise the return value is incorrect.
You might need to modify your C code to use the new ObAMMasterAuditRule_getUTF8EscapeCharacter
, which returns a pointer to the UTF-8 encoded audit escape character.
For more information, see "Policy Manager API". For details about using the Policy Manager API, see the Oracle Access Manager Developer Guide.
Oracle recommends that you test your upgraded Access System customizations in a test or development environment before deploying these in an upgraded production environment.
To validate Access System customization upgrades
Verify that your customizations have been restored properly by performing specific operations that will exercise the upgraded customizations.
Verify that auditing and access reporting is working properly.
Upgrade Not Successful: Proceed to "Recovering from an Access System Customization Upgrade Failure".
Upgrade Successful: Proceed to "Backing Up Upgraded Access System Customizations" next.
As mentioned earlier, Oracle recommends that you finish each upgrade by backing up the appropriate 10g (10.1.4.0.1) directory. This will enable you to easily restore your environment to the newly upgraded state should that be a requirement.
To back up Access System customizations after upgrading them
Back up the 10g (10.1.4.0.1) directory that contains the upgraded customizations and store it in a new location.
When all customizations are completed and redeployed, proceed to validating operations as described in Chapter 14.
If an Access System customization was not successful, you can perform the following steps to rollback this upgrade, then try again.
To recover from an unsuccessful Access System component upgrade
Restore the earlier customization files or directory that you backed up before the upgrade (to recover the earlier customization), then back it up again. You will retain one as a backup copy and use one in the next step.
Using a backup copy of your earlier customization files, restart the upgrade as described in this chapter.
After ensuring that your previous Access System customizations are integrated and operating properly in the upgraded environment, see Chapter 14.
If you are using the zero downtime upgrade method, see also Part VI.