17 Maintaining the Oracle WSM Repository

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

About the Oracle WSM Repository
Registering an Oracle WSM Repository
Understanding the Different Mechanisms for Importing and Exporting Policies
Importing and Exporting Documents in the Repository
Migrating Policies Between Application Environments
Patching Policies in the Repository
Backing Up and Restoring the Oracle WSM Repository
Upgrading the Oracle WSM Policies in the Repository
Rebuilding 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:

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 Metadata Repository in Navigation Pane"
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 Registering an Oracle WSM Repository"
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 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:

If the archive specified using the archive argument already exists, you can choose to merge the documents into the existing archive, overwrite the existing archive, or cancel the operation.

Use the optional documents argument to specify the documents you want exported to the archive. If you do not specify this argument, then all assertion templates, intents, policies, and policy sets are exported. You can specify a list of the documents to be exported, or use a search expression to find specific documents in the repository. For example, to export a list of policies whose URI begins with either "oracle/wss10_" or "oracle/wss11_", enter the following:

wls:/jrfServer_domain/serverConfig>exportRepository('/tmp/test2.zip',['policies:oracle/wss10_%','policies:oracle/wss11_%'])

Exporting "/policies/oracle/wss10_message_protection_client_policy"
Exporting "/policies/oracle/wss10_message_protection_service_policy"
.
.
.
Exporting "/policies/oracle/wss11_x509_token_with_message_protection_client_policy"
Exporting "/policies/oracle/wss11_x509_token_with_message_protection_service_policy"
Successfully exported "43" documents.

Use the optional expandReferences argument to expand the policy references during the export. The default is false. When no list of documents is provided, expandReferences is true.

For example, to export active policy set documents and the policies they use:

wls:/jrfServer_domain/serverConfig>exportRepository('/tmp/repository-active.jar', ['policysets:global/%'], true)

Exporting "/policies/oracle/wsaddr_policy"
Exporting "/policies/oracle/wss11_saml_or_username_token_with_message_protection_service_policy"
Exporting "/policies/oracle/wss_username_token_service_policy"
Exporting "/policysets/global/all-domains-default-web-service-policies"
Exporting "/policysets/global/app-only-web-service-policies"
Exporting "/policysets/global/migrate_example"
Successfully exported "6" documents.

If you modify a document in the repository, you can update it in the archive file. For example, if you modified a policy set named module-web-service-policies, you can update the policy set in the archive using the following command:
```
wls:/jrfServer_domain/serverConfig>exportRepository('/tmp/repository-backup.jar', ['/policysets/global/module-web-service-policies'])
```

To import documents into the repository use the importRepository command.

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

Note the following:

The archive argument, which is required, specifies the path to the archive file that contains the list of documents to be imported.
Optionally, you can use the map argument to provide the location of a file that describes how to map physical information in a policy set, from the source environment to the target environment. For example, you can use the map file to ensure that the resource scope expression in a policy set is updated to match the target environment, such as Domain("foo")=Domain("bar") If you specify a map file and it does not exist, the operation fails and an error is displayed.
You can set the optional generateMapFile argument to true to create a sample map file at the location specified by the map argument. No documents are imported when this argument is set to true. The default is false. After the file is created you can edit it using any text editor.

For example, to generate a map file /tmp/mapfile.txt for the /tmp/repository-active.jar, enter the following command:
```
wls:/jrfServer_domain/serverConfig>importRepository('/tmp/repository-active.jar', '/tmp/mapfile.txt', true)
 
Successfully generated "Resource Scope Mappings" file at "/tmp/mapfile.txt"
```

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:

You create a new policy or update an existing policy that uses a new policy URI. In this scenario, the patching of the repository acts as if a new file was added to the installation and, as a result, only impacts the components that expect to use the new policy. Once loaded, the policy is available to all applications. Generally speaking, using a new policy URI is the preferred model as policies are typically named to convey the behavior they represent.
You create a new policy or update an existing policy that uses an existing policy URI. In this scenario, the patching of the repository acts as if an existing file was overwritten with a new version and, therefore, impacts all components that are using the existing policy. Once loaded, all applications will use the new version of the policy. Reusing an existing URI is typically only done to make minor modifications to the behavior of a policy. Note that if you use WLST commands to patch the repository, you need to restart the server to ensure that the latest version of the policy is enforced. You do not need to restart if you use Fusion Middleware Control.

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:

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.
Ensure that the Oracle WSM Repository to be upgraded is:
- Registered with the new installation of Oracle Fusion Middleware. For more information, see "Registering an Oracle WSM Repository".
- Upgraded to the latest schema version. For more information, see "Updating Your Schemas with Patch Set Assistant" in Oracle Fusion Middleware Patching Guide.
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".
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 "Oracle WSM Repository Management 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:

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.
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 "Oracle WSM Repository Management 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.