3 Upgrading a Security Provider

If you are using a custom security provider in a WebLogic Server Version 8.1 environment, you can use the WebLogic Upgrade Wizard to upgrade your security provider for use in a WebLogic Server 10.3.6 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 10.3.6 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 want, 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" in Information Roadmap for Oracle WebLogic Server .

The following sections describe how to use the WebLogic Upgrade Wizard for upgrading the Security Provider.

For information about developing custom security providers, see Developing Security Providers for Oracle WebLogic Server.

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 10.3.6 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 Oracle WebLogic Server. If an MDF is not located in the JAR file, the upgrade process fails for that specific security provider.

If an MDF contains undocumented tags, warnings are generated during the upgrade process. These warnings do 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.2 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 fails 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 Oracle 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 to run in the WebLogic Server 10.3.6 environment.

Note:

If you are installing WebLogic Server 10.3.6 into an existing home directoryFoot 1  that contains an installation of WebLogic Server Version 8.1, all custom security providers that reside in the default location (that is, WL_HOME\server\lib\mbeantypes, where WL_HOME represents the root directory of the pre-9.0 installation) are upgraded automatically. 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.

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:

  1. Verify that the WebLogic domain is not running.

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

  3. 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 when the upgrade process is complete. After you run the command, the WebLogic Upgrade Wizard opens, as shown in Figure 3-1.

    Figure 3-1 WebLogic Upgrade Wizard for Security Providers

    Description of Figure 3-1 follows
    Description of "Figure 3-1 WebLogic Upgrade Wizard for Security Providers"

  4. Click Next to proceed to the Select Source Directory window.

Procedure for Upgrading a Security Provider

Table 3-1 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 must 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.0 installation of WebLogic Server.

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 Oracle WebLogic Server. If JAR file does not contain an MDF, the upgrade process fails for the associated security provider.

Click Next to proceed to the Select Destination Directory 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 10.3.6 installation.

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 when 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.

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 Oracle WebLogic Server. 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 
Oracle 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.

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 computer, 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:

  1. Verify that the WebLogic domain is not running.

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

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

  4. Navigate to the directory that contains the security provider to upgrade.

  5. 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 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 Appendix E, "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.