Upgrading WebLogic Application Environments

Upgrading a Security Provider

If you are using a custom security provider in a WebLogic Server 7.0 or 8.1 environment, you can use the WebLogic Upgrade Wizard to upgrade your security provider for use in a WebLogic Server 9.1 application environment.

Notes: As of 9.1, WebLogic Server includes two new security providers, the XACML Authorization provider and the XACML Role Mapping provider. Existing WebLogic domains that you upgrade to 9.1 will continue to use the authorization and role mapping providers currently specified, such as third-party partner providers or the original WebLogic Authorization and Role Mapping providers. If you wish, you can migrate existing domains from using WebLogic Server proprietary providers to the XACML providers, including performing bulk imports of existing policies. For more information, see Security for BEA WebLogic Server 9.1 at http://download.oracle.com/docs/cd/E13222_01/wls/docs91/security.html.

Custom security providers were not supported in WebLogic Server 6.1.

The following sections describe how to use the WebLogic Upgrade Wizard for this purpose:

For information about developing custom security providers, see Developing Security Providers for WebLogic Server at http://download.oracle.com/docs/cd/E13222_01/wls/docs91/dvspisec/index.html.

What Happens During a Security Provider Upgrade

For a security provider upgrade, you specify the source and destination directories for the upgrade, and the WebLogic Upgrade Wizard upgrades the existing JARs so that the security provider can run in a WebLogic Server 9.1 application environment.

Note: The security provider JAR must contain the appropriate MBean Definition File (MDF) that defines the MBean. An MDF is used to generate the .java files for a particular MBean type. For more information about creating MDFs, see Developing Security Providers for WebLogic Server at http://download.oracle.com/docs/cd/E13222_01/wls/docs91/dvspisec/index.html. If an MDF is not located in the JAR file, the upgrade process will fail for that specific security provider.

If an MDF contains undocumented tags, warnings will be generated during the upgrade process. These warnings will not affect the upgrade, and can be ignored. To avoid any further such warnings, however, you may want to remove undocumented tags from the MDF.

Security realms defined in pre-9.1 configurations must define a lockout manager (UserLockoutManagerMBean), and must conform to the following naming convention for JMX objects: Security:Name=name. Otherwise, the upgrade process will fail for the security provider.

During the upgrade, the Upgrade Wizard performs the following tasks:

Adds required classes to the security provider JAR. These classes include MBeanImpl elements, schema files, and so on.
Reads the MDF and creates the necessary schemas, MBean Implementation, and Binder classes.
Stores the upgraded JARs for the security provider in the specified location.
Appends _Upgraded to the security provider name to make the upgraded JARs distinct from the existing security provider JARs, which are maintained.
Ignores security provider JARs that are shipped with BEA products, or JARs with names that contain _Upgraded, indicating that they have been upgraded already.

Upgrading a Security Provider

You must upgrade each custom security provider that you want to run in the WebLogic Server 9.1 environment.

Note: If you are installing WebLogic Server 9.1 into an existing BEA Home directory that contains an installation of WebLogic Server 7.0 or 8.1, all custom security providers that reside in the default location, WL_HOME\server\lib\mbeantypes, where WL_HOME specifies the root directory of the pre-9.1 installation, are upgraded automatically. (Custom security providers were not supported in 6.1 environments.) If all of your custom security providers reside in the default location, then you do not have to perform the security provider upgrade step described in this section.

To verify that a custom security provider has been upgraded, locate the upgraded security provider, security_provider_name_Upgraded, in the WL_HOME\server\lib\mbeantypes directory, where WL_HOME specifies the root directory of the 9.1 installation, and security_provider_name specifies the name of the security provider.

You can upgrade a security provider using the WebLogic Upgrade Wizard in one of the following modes:

Graphical—For upgrading a security provider interactively, using the graphical user interface.
Silent—For upgrading a security provider silently, by specifying upgrade requirements in a file.

You must upgrade a security provider on each machine in the domain.

The following sections describe how to upgrade a security provider:

Upgrading a Security Provider in Graphical Mode

The following sections describe how to upgrade a security provider by using the WebLogic Upgrade Wizard in graphical mode:

Note: The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Security Provider

Note: Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in graphical mode and upgrade the security provider:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 5: Set Up the Environment.

At a command prompt, enter the following command:

java weblogic.Upgrade -type securityproviders [-out file]
The -out argument is optional. It allows you to designate a file in which you want all standard output (stdout) and error messages to be written. By default, these messages are written to the command window and a summary of them is displayed at the end of the upgrade process.
After you run the command, the WebLogic Upgrade Wizard opens, as shown in the following figure.

Click Next to proceed to the next window.

Procedure for Upgrading a Security Provider

The following table summarizes the steps in the procedure to upgrade a security provider using the WebLogic Upgrade Wizard.

Table 3-1 Procedure for Upgrading a Security Provider

In this step ...	You ...
Select Source Directory	Select the directory that contains the security provider JARs that need to be upgraded. By default, the selected directory is the current directory. By default, security providers are located in `WL_HOME\server\lib\mbeantypes`, where `WL_HOME` specifies the root directory of the pre-9.1 installation of WebLogic Server, as shown in the following example. Note: The security provider JARs must contain the MBean Definition File (MDF) for the associated MBean. For more information about creating MDFs, see Developing Security Providers for WebLogic Server at `http://download.oracle.com/docs/cd/E13222_01/wls/docs91/dvspisec/index.html`. If JAR file does not contain an MDF, the upgrade process fails for the associated security provider. Click Next to proceed to the next window.
Select Destination Directory	Select the directory in which you want to save the new security provider JAR files. The default directory is `WL_HOME\server\lib\mbeantypes`, where `WL_HOME` specifies the root directory of the WebLogic Server 9.1 installation, as shown in the following example. Note: To ensure the success of the domain upgrade, you must target the upgraded security providers to the default destination directory, `WL_HOME\server\lib\mbeantypes`. If you prefer to keep the security providers in a different location, you can move them once the domain upgrade process is complete. Click Next to proceed to the next window.
Upgrade Security Providers in Progress	Review progress of the wizard as it saves the upgraded JARs and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window, as illustrated in the following illustration. The security provider JAR must contain the MBean Definition File (MDF) for the associated MBean. For more information about creating MDFs, see Developing Security Providers for WebLogic Server at `http://download.oracle.com/docs/cd/E13222_01/wls/docs91/dvspisec/index.html`. If a JAR file does not contain an MDF, the upgrade process fails for the associated security provider. For example: `Now processing mySecurityProviderToo.jar ...` `No MDFs (.xmls) found in the old security provider jar with name mySecurityProviderToo.jar` If an MDF contains undocumented tags, warnings are generated during the upgrade process. These warnings do not affect the upgrade; they can be ignored. To avoid further such messages, you may want to remove undocumented tags from the MDF. If the wizard locates a security provider JAR that was installed with the product, that has been upgraded already, or that is invalid, it does not upgrade that JAR. For example: `Not upgrading foo.txt because either this is a Out of the Box BEA Security Provider jar or this Security Provider jar is already upgraded or this is not a valid archive (may be not a .jar)` Click Next to proceed to the next window.
Upgrade Complete	Review the upgrade results, including any important messages that require further consideration, such as the messages shown in the following example. Click Done to close the wizard.

Upgrading a Security Provider in Silent Mode

In some circumstances, for example, when the security provider resides on a remote machine, it is not practical to use the WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade a security provider.

Note: Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in silent mode and upgrade a security provider:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 5: Set Up the Environment.

(Optional) Create an XML script to define the upgrade requirements. For more information, see Silent Upgrade XML Script Reference.

Navigate to the directory that contains the security provider that you want to upgrade.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type securityproviders [-responses xmlfile] [-out file]

Two arguments are optional: -responses and -out. Include these arguments if you want to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Silent Upgrade XML Script Reference.
The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.