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.

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 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 WLST commands as described in the following sections:

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

Exporting Documents from the Repository

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'])

Importing Documents into the Repository

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. If a document being imported is a duplicate of the current version that already exists in the repository, then it will not be imported and a new version of the document is not created.

  • 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 map file is created you can edit it using any text editor. The map file contains the document names given in the archive file and their corresponding attachTo values. The attachTo value can be updated to correspond to the new environment. If a mapping update is not required for a document name, that entry may be either deleted or commented out using the # character.

    Note:

    When importing documents into the repository, OWSM validates the attachTo values only. If a value is invalid, then the policy set is disabled. Other text in the map file is not validated.

    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

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, the predefined policies may be discontinued, changed, or new predefined policies may be provided.

After you install a Fusion Middleware patch set, the repository is automatically upgraded as part of the server startup process. Any predefined policies that have not been customized for your environment are replaced, and any new policies are automatically added. Note, however, that predefined policies that have been customized and user-created custom policies in the repository are not replaced. If desired, you can refresh the repository for these policies also, as described in "Rebuilding the Oracle WSM 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.

For details about patching your Oracle Fusion Middleware installation, see Oracle Fusion Middleware Patching Guide.

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