16 Managing the OWSM Repository

The repository allows you to import, export, backup, and restore Oracle Web Services Manager metadata, such as policies, assertion templates, and policy usage data. Policies in the repository can also be patched and upgraded.

This chapter contains the following sections:

16.1 About the OWSM Repository

Oracle Web Services Manager (WSM) uses an MDS repository to store OWSM metadata, such as policies, assertion templates, and policy usage data. The OWSM 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 OWSM Repository, each policy has a URI that is evaluated to form a path in which to locate a particular XML document containing the policy. OWSM 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, OWSM only accesses the latest version during policy enforcement.

Details about managing the MDS repository are provided in "Managing the MDS Repository" in Administering Oracle Fusion Middleware.

16.2 Registering an OWSM Repository

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

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

    Figure 16-1 Metadata Repository in Navigation Pane

    Description of Figure 16-1 follows
    Description of "Figure 16-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 16-2.

    Figure 16-2 Registering an OWSM Repository

    Description of Figure 16-2 follows
    Description of "Figure 16-2 Registering an OWSM 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 Administering Oracle Fusion Middleware.

16.3 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 OWSM Repository.

Fusion Middleware Control provides the ability to selectively import and export one or more user-created policies or assertion templates to/from a zip archive file. Read only documents, including predefined policies and assertion templates, can not be imported or exported because the same documents would be present in the target environment. The procedures for importing and exporting policies and assertion templates using Fusion Middleware Control are described in the following sections:

The WLST commands, importWSMArchive and exportWSMRepository, are provided to facilitate importing and exporting multiple OWSM documents directly to and from the OWSM 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 OWSM 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.

16.4 Importing and Exporting Documents in the Repository

You can import and export OWSM documents and application metadata to and from the OWSM Repository using the importWSMArchive, exportWSMRepository, and exportWSMAppMetadata commands as described in the following sections.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for Infrastructure Components.

16.4.1 Exporting Documents from the Repository

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

exportWSMRepository(archive,[documents=None],[includeShared='false'])

Note the following:

  • Read only documents, including predefined policies and assertion templates, will not be exported because the same documents already exist in the target environment.

  • 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 no documents are specified, then only shared documents that include policies and policy sets are exported. Because read-only documents can not be exported, only custom or cloned shared policies will be included in the export. If this argument is specified as an empty string [''], then all shared documents that include policies and policy sets, application metadata and configuration documents 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 user-created policies whose URI begins with either "test/wss_" or "test/wss11_", enter the following:

    wls:/jrfServer_domain/serverConfig>exportWSMRepository('/tmp/test2.zip',['policies:test/wss_%','policies:test/wss11_%'])

Exporting "/policies/test/wss11_x509_token_with_message_protection_service_policy_test"
Exporting "/policies/test/wss_username_token_over_ssl_service_policy_Test"
Successfully exported "2" documents.

  • Use the optional includeShared argument to include the shared documents (those that are specified as policy references within policy sets and wsm-assembly documents) as part of same archive during the export. Because read-only documents can not be exported, only custom or cloned shared policies will be included in the export. The default is false.

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

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

Exporting "/policies/test/wss_username_token_over_ssl_service_policy_Test"
Exporting "/policysets/global/all-domains-default-web-service-policies"
Exporting "/policysets/global/app-only-web-service-policies"
Exporting "/policysets/global/migrate_example"
Successfully exported "4" 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>exportWSMRepository('/tmp/repository-backup.jar', ['/policysets/global/module-web-service-policies'])

16.4.2 Exporting Application Metadata from the Repository

To export application metadata from the repository to a supported ZIP archive file, use the exportWSMAppMetadata command.

exportWSMAppMetadata(archive,[applications=None],[includeShared='false'])

Note the following:

  • This command is supported for Oracle Infrastructure and RESTful Web services only. This command is not supported for ADF DC Web service clients and Java EE Web services.

  • 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. If you choose the overwrite option, the original archive is backed up and a message describes the location of the backup archive.

  • Use the optional applications argument to specify the applications for which you want to export the metadata to the archive. If no application names are specified, then the metadata for all the applications in the domain is exported. You can specify a list of search expressions to find specific application metadata in the repository, using this syntax: /{PLATFORM_NAME}/{DOMAIN_NAME}/{APPLICATION_NAME}.

  • Use the optional includeShared argument to specify whether the shared documents (those that are specified as policy references within wsm-assembly documents) should be included in the export. The default is false. Because read-only documents can not be exported, only custom or cloned shared policies will be included in the export.

For example, the following command exports the application metadata for an application whose name begins with jaxws into the applications.zip file in the tmp directory:

wls:/jrfServer_domain/serverConfig>exportWSMRepository('/tmp/applications.zip',['/WLS/base_domain/jaxws%'])

Exporting "\assembly\WLS\base_domain\jaxwsejb30ws\jaxwsejb\wsm-assembly.xml"Successfully exported "1" documents.

16.4.3 Importing Documents into the Repository

To import documents into the repository use the importWSMArchive command.

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

Note the following:

  • Read only documents, including predefined policies and assertion templates, will not be imported because the same documents already exist in the target environment.

  • 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. 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>importWSMArchive('/tmp/repository-active.jar', '/tmp/mapfile.txt', true)
 
Successfully generated "Documents 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>importWSMArchive('/tmp/repository-active.jar', '/tmp/mapfile.txt')
 
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 "3" documents

16.5 Exporting Policies from the OWSM Repository for Use in JDeveloper

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 importWSMArchive and exportWSMRepository commands for policy migration, as described in "Migrating Policies" in Administering Web Services.

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

JDEV_USER_HOME\system12.1.2.0.x.x.x\DefaultDomain\store\gmds

If not set, JDEV_USER_HOME defaults to C:\Users\user-dir\AppData\Roaming\JDeveloper.

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

  • Predefined OWSM policies: owsm/policies/oracle/policy_file

  • Custom user policies: owsm/policies/policy_file

When exporting policy files from the OWSM 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.

16.6 Patching Policies in the Repository

You can patch the OWSM 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:

Note:

Predefined policies are read-only and cannot be updated or overwritten.

  • You create a new policy or update an existing user-defined 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 user-defined 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.

16.7 Backing Up and Restoring the OWSM Repository

Use the exportWSMRepository and importWSMArchive WLST commands to back up and restore the OWSM Repository. For more information about these commands, see "Importing and Exporting Documents in the Repository".

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

wls:/jrfServer_domain/serverConfig>exportWSMRepository ('/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 importWSMArchive command to import all the OWSM 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>importWSMArchive ('/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 WLST Command Reference for WebLogic Server.

16.8 Upgrading the Repository to 12c

The predefined documents distributed in the 12c release, including predefined policies and assertion templates, are all read only. During the upgrade from 11g to 12c, existing documents will not be overridden, and only read-only versions of new documents will be added to the repository.

If you have not modified any of the existing predefined documents, then you can use the resetWSMRepository WLST command to perform a complete upgrade of the repository to the read-only versions of the predefined documents distributed with the 12c release.

If you have modified any of the predefined documents in the repository, then you must clone the modified documents and change all references to point to the cloned versions. When all documents have been cloned, and references have been changed, you can then perform the upgrade with the resetWSMRepository WLST command as described in "Rebuilding the OWSM Repository".

After the 12c release, you must migrate any of the predefined documents that you have modified. In the release following 12c, all predefined documents will be made read-only; any modifications that you have made to predefined documents will be lost.

16.9 Rebuilding the OWSM Repository

In some circumstances, it may be desirable to rebuild the entire OWSM 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 OWSM 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" in Administering Web Services.

    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 resetWSMRepository(true) command to delete all the documents from the OWSM 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 resetWSMRepository WLST command, see "OWSM Repository Management Commands" in WLST Command Reference for Infrastructure Components.

Note:

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