Skip Headers
Oracle® Fusion Middleware Security and Administrator's Guide for Web Services
11g Release 1 (11.1.1)

Part Number B32511-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

17 Maintaining the Oracle WSM Repository

The following topics provide guidance for maintaining the Oracle WSM Repository:

About the Oracle WSM Repository

Oracle Web Services Manager (WSM) uses an MDS repository to store Oracle WSM metadata, such as policies, assertion templates, and policy usage data. The Oracle WSM Repository is available as a database (for production use) or as files in the file system (for development use in JDeveloper).

For a list of the databases that are supported for this release, see Oracle Fusion Middleware Supported System Configurations at: http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html

Within the Oracle WSM Repository, each policy has a URI that is evaluated to form a path in which to locate a particular XML document containing the policy. Oracle WSM does not use the MDS customization feature, so all policies are stored as complete documents. Although MDS supports the ability to store multiple versions of a given document, Oracle WSM only accesses the latest version during policy enforcement.

Details about managing the MDS repository are provided in "Managing the MDS Repository" in Oracle Fusion Middleware Administrator's Guide.

Registering an Oracle WSM Repository

Before you can deploy an application to an MDS Repository, such as the Oracle WSM Repository, you must register the repository with the Oracle WebLogic domain. To register an Oracle WSM Repository:

  1. In the Navigator pane, expand Metadata Repositories and select mds-owsm, as shown in Figure 17-1.

    Figure 17-1 Metadata Repository in Navigation Pane

    Description of Figure 17-1 follows
    Description of "Figure 17-1 Metadata Repository in Navigation Pane"

  2. Select Metadata Repository, then Administration, then Register/Deregister.

    The Metadata Repositories page is displayed, as shown in Figure 17-2.

    Figure 17-2 Registering an Oracle WSM Repository

    Description of Figure 17-2 follows
    Description of "Figure 17-2 Registering an Oracle WSM Repository"

  3. Click Register and provide the required database connection and repository information to register the repository.

    Complete details for registering and managing a metadata repository are provided in "Managing the Oracle Metadata Repository" in the Oracle Fusion Middleware Administrator's Guide.

Understanding the Different Mechanisms for Importing and Exporting Policies

You can use Enterprise Manager Fusion Middleware Control or WebLogic Scripting Tool (WLST) commands to import and export policies to and from the Oracle WSM Repository. Oracle Enterprise Manager Fusion Middleware Control provides the ability to selectively import and export one policy at a time. The procedures for importing and exporting policies using Fusion Middleware Control are described in the following sections:

The WLST commands, importRepository and exportRepository, are provided to facilitate importing and exporting multiple Oracle WSM documents directly to and from the Oracle WSM Repository. For details about using these commands, see "Importing and Exporting Documents in the Repository".

When you import or export policies using either of these mechanisms, the operation is routed through an instance of the Oracle WSM Policy Manager application. At run time, when a request for a policy is made, the Policy Manager guarantees that the latest policy is always provided. Therefore, the latest policies are always enforced.

Note:

In earlier releases, the only WLST commands available to import and export polices were the importMetadata and exportMetadata MDS WLST commands. Oracle does not recommend using these commands for Oracle WSM documents because the operation is not routed through an instance of the Oracle WSM Policy Manager. Consequently, Oracle Web Services Manager may not be aware of the changes and may continue to enforce outdated policies. To ensure that only the latest polices are enforced, you must restart all the servers to which the Oracle WSM MDS repository is registered.

Importing and Exporting Documents in the Repository

You can import and export Oracle WSM documents to and from the Oracle WSM Repository using the importRepository and exportRepository commands.

To export documents from the repository to a supported ZIP archive file, use the exportRepository command.

exportRepository(archive,[documents=None],[expandReferences='false'])

Note the following:

To import documents into the repository use the importRepository command.

importRepository(archive,[map=none],[generateMapFile='false'])

Note the following:

To import the active policy set archive /tmp/repository-active.jar using the map file /tmp/mapfile.txt, enter the following:

wls:/jrfServer_domain/serverConfig>importRepository('/tmp/repository-active.jar', '/tmp/mapfile.txt')
 
Importing "META-INF/policies/oracle/wsaddr_policy"
Importing "META-INF/policies/oracle/wss11_saml_or_username_token_with_message_protection_service_policy"
Importing "META-INF/policies/oracle/wss_username_token_service_policy"
Importing "META-INF/policysets/global/all-domains-default-web-service-policies"
Importing "META-INF/policysets/global/app-only-web-service-policies"
Importing "META-INF/policysets/global/migrate_example"
Successfully imported "6" documents

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Migrating Policies Between Application Environments

Policies can be migrated through the different stages of the application development and deployment cycles, such as from development to production. Oracle recommends using the importRepository and exportRepository commands for policy migration, as described in "Migrating Policies".

Exporting Policies from the Oracle WSM Repository for Use in JDeveloper

In JDeveloper, you can add custom policies to the default policy store location at:

C:\Documents and Settings\user-dir\ApplicationData\JDeveloper\system11.1.1.2.x.x.x\DefaultDomain\oracle\store\gmds

Within this directory, Oracle WSM policies files must be included using one of the following directory structures:

  • Predefined Oracle WSM policies: owsm/policies/oracle/policy_file

  • Custom user policies: owsm/policies/policy_file

When exporting policy files from the Oracle WSM Repository for use in JDeveloper, this directory structure is not maintained. You must ensure that when adding the exported policy to the JDeveloper environment that you use the required directory structure noted above. Otherwise, the policies will not be available in the JDeveloper environment.

Patching Policies in the Repository

You can patch the Oracle WSM Repository using either Fusion Middleware Control or the WLST commands, as described in "Understanding the Different Mechanisms for Importing and Exporting Policies". When you create or update a policy, there are two possible scenarios to consider when you patch the repository:

Backing Up and Restoring the Oracle WSM Repository

Use the exportRepository and importRepository WLST commands to back up and restore the Oracle WSM Repository. For more information about these commands, see "Importing and Exporting Documents in the Repository".

For example, to backup all the Oracle WSM artifacts in the repository, enter the following command:

wls:/jrfServer_domain/serverConfig>exportRepository('/tmp/repository-backup.jar')

Exporting "/assertiontemplates/oracle/binding_authorization_template"
Exporting "/assertiontemplates/oracle/binding_permission_authorization_template"
.
.
.
Exporting "/policies/oracle/binding_authorization_denyall_policy"
Exporting "/policies/oracle/binding_authorization_permitall_policy"
.
.
.
Exporting "/policysets/global/all-domains-default-web-service-policies"Exporting "/policysets/global/app-only-web-service-policies"
Successfully exported "170" documents.

To restore the repository from the backup, use the importRepository command to import all the Oracle WSM Repository artifacts.

For example, to restore the repository using the backup file created in the previous example, enter the following command:

wls:/jrfServer_domain/serverConfig>importRepository('/tmp/repository-backup.jar')

Importing "META-INF/assertiontemplates/oracle/binding_authorization_template"Importing "META-INF/assertiontemplates/oracle/binding_permission_authorization_template"
.
.
.
Importing "META-INF/policies/oracle/binding_authorization_denyall_policy"
Importing "META-INF/policies/oracle/binding_authorization_permitall_policy"
.
.
.
Importing "META-INF/policysets/global/all-domains-default-web-service-policies"Importing "META-INF/policysets/global/app-only-web-service-policies"
Successfully imported "170" documents.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Upgrading the Oracle WSM Policies in the Repository

Both predefined and custom Oracle WSM policies are stored in the Oracle WSM Repository. In subsequent releases, these predefined policies may be discontinued, changed, or additional predefined policies may be provided. You can use the Web services custom WLST commands to upgrade the repository with new or updated predefined policies when you install a new version of the Fusion Middleware software. You can also refresh the repository by deleting all Oracle WSM policies from the repository, including custom policies, and then repopulating it using the predefined policies provided in your installation. All of the policies in the repository are also revalidated when you upgrade the repository.

Note:

You should back up your existing policies to a safe location before deleting any policies. In the event you have any issues with the new policies, you can import the existing policies from the backup.

To upgrade the Oracle WSM Repository:

  1. Install or patch the new version of Oracle Fusion Middleware. For more information, see "Understanding Your Installation Starting Point" in Oracle Fusion Middleware Installation Planning Guide.

  2. Ensure that the Oracle WSM Repository to be upgraded is:

  3. Invoke WLST from the Oracle home in which you installed the new version of Oracle Fusion Middleware as described in "Accessing the Web Services Custom WLST Commands".

  4. Do one of the following:

    • To add new predefined policies that are provided in the latest installation of the Oracle Fusion Middleware software, enter the following command:

      upgradeWSMPolicyRepository()

      When you execute this command, a message is displayed indicating the policies that have been added to the repository. Note that existing predefined and user-defined custom policies in the repository are unchanged. The output message also displays a list of any existing predefined policies that have changed or discontinued in the latest release. If a policy has been discontinued and is no longer supported, Oracle recommends that you remove all references to it and then delete it using Oracle Enterprise Manager. If a predefined policy has changed in the latest release, Oracle recommends that you import the updated version of the policy using Oracle Enterprise Manager. For details about deleting and importing policies using Enterprise Manager, see Chapter 7, "Managing Web Service Policies."

    • To delete existing predefined policies stored in the repository and replace them with the latest set of predefined policies, use the following command:

      resetWSMPolicyRepository(false)

      User-defined custom policies are unchanged. An output message is displayed that lists the predefined policies that have been added, deleted, or replaced in the repository.

    • To delete all policies from the repository, including custom policies, and replace them with the latest set of predefined policies, use the following command:

      resetWSMPolicyRepository(true)

      Note:

      Before you delete a policy, Oracle recommends that you verify that the policy is not attached to any policy subjects.

    When you execute any of these commands, all existing policies are revalidated.

    For more information about these WLST commands, see "Policy Repository Upgrade Commands" in WebLogic Scripting Tool Command Reference.

Rebuilding the Oracle WSM Repository

In some circumstances, it may be desirable to rebuild the entire Oracle WSM Repository, including restoring the original predefined policies and assertion templates. For example, when starting a new project in a test environment it may be useful to reset the repository contents to their original state.

To rebuild the Oracle WSM Repository, perform the following steps:

  1. Connect to the Administration Server instance of the WebLogic Server domain to which the repository is registered. For instructions, see "Accessing the Web Services Custom WLST Commands".

    Note:

    You should back up your existing policies to a safe location before deleting any policies or rebuilding the repository. In the event you have any issues with the new policies, you can import the existing policies from the backup.
  2. Use the resetWSMPolicyRepository(true) command to delete all the documents from the Oracle WSM Repository and repopulate it with the set of predefined policies and assertion templates that were installed with the software. This is the preferred method.

    For more information about the resetWSMPolicyRepository WLST command, see "Policy Repository Upgrade Commands" in WebLogic Scripting Tool Command Reference.

Note:

Before you delete a policy, Oracle recommends that you verify that the policy is not attached to any policy subjects.