Managing the Oracle Web Services Manager Repository

15 Managing the Oracle Web Services Manager Repository

The OWSM 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.

Topics:

15.1 Overview of 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.

15.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:

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

Figure 15-1 Metadata Repository in Navigation Pane

Description of "Figure 15-1 Metadata Repository in Navigation Pane"
Select Metadata Repository, then Administration, then Register/Deregister.

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

Figure 15-2 Registering an OWSM Repository

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

15.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, cannot 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 "About Importing and Exporting Documents in the Repository Using WLST".

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.

15.4 About Importing and Exporting Documents in the Repository Using WLST

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

This is 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.

15.4.1 Exporting Documents from the Repository Using WLST

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

15.4.2 Exporting Application Metadata from the Repository Using WLST

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.

15.4.3 Importing Documents into the Repository Using WLST

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

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

This is 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\owsm

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

In this default policy store location, OWSM policies must be included using the directory structure policies/policyname.

Note:

Within this directory structure, policyname includes the directory in which the policy is located. For example, all predefined policies provided by Oracle are contained in the oracle/ directory, such as oracle/wss_http_token_service_policy.

Oracle recommends that custom policies be located in a directory that is separate from the /oracle directory that contains the predefined policies, for example mycompany/mypolicy.

When exporting policy files from the OWSM Repository using WLST or Fusion Middleware Control, they are exported into a zip archive using the following directory structure:

META-INF/policies/policyname

To use the policies in a JDeveloper environment, you must extract the contents of the META-INF directory in the zip archive into the default JDeveloper policy store location noted above. When you do so, the policies/policyname structure is maintained and the policies will be available in the JDeveloper environment. If you do not maintain this directory structure, the policies will not be available in the JDeveloper environment.

15.6 About Patching Policies in the Repository

You can patch the OWSM Repository using either Fusion Middleware Control or the WLST commands.

This is 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.

15.7 Creating Back 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 "About Importing and Exporting Documents in the Repository Using WLST".

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 Infrastructure Components.

15.8 Upgrading the OWSM Repository

You can upgrade the OWSM repository from 11g to 14c.

The predefined OWSM documents distributed in the 14c release, including predefined policies and assertion templates, are now read only. During the upgrade from 11g to 14c, the following occurs:

Existing predefined documents that have not been modified will be replaced with the 14c read-only versions.
New predefined documents introduced in 14c will be added.
Existing predefined documents that have been modified, and any user-created documents, will not be overwritten and remain unchanged.

To ensure that you always have the latest versions of the Oracle predefined documents, Oracle recommends that you do the following:

Clone any of the modified documents as described in the following topics:
- "Cloning a Web Service Policy"
- "Cloning an Assertion Template"
Replace any policy references to the modified documents with policy references to the cloned versions.
Upgrade the OWSM repository using the resetWSMRepository(clearStore='false') command. Using the clearStore='false' option deletes and replaces only the predefined documents provided by Oracle. Custom documents and predefined documents that you cloned are not deleted. This is the default setting for this command.

Note:

The resetWSMRepository command also updates the version number of the predefined policies and assertion templates.

To delete all documents in the repository, including custom documents, see "Rebuilding the OWSM Repository".

15.9 Rebuilding the OWSM Repository

In some circumstances, it may be desirable to delete all of the documents in the OWSM Repository and replace them with the latest set that was provided with your Fusion Middleware installation. For example, when starting a new project in a test environment it may be useful to reset the repository contents to their original state.

Note:

The procedure described in this section deletes all documents in the OWSM Repository, including cloned and user-created documents. To delete and replace only the predefined documents provided by Oracle, see "Upgrading the OWSM Repository".

To rebuild the OWSM 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" 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.
Use the resetWSMRepository(clearStore='true') command to delete all the documents, including custom user documents, from the OWSM Repository and repopulate it with full set of predefined read-only documents that were provided by Oracle.

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.

15.10 Configuring Multiple Domains for a Single OWSM Repository Instance

You can use a centralized OWSM Repository to import, export, backup, and restore Oracle Web Services Manager metadata, such as policies, assertion templates, and policy usage data for multiple domains. Each domain can have its own OWSM Policy Manager wired to a shared OWSM Repository.

The following OWSM documents and Application Metadata can be shared across multiple shared domains using a single OWSM repository instance:

Policies & Assertions
Global Policy Sets
Token Issuer Trust

Note:

Any change made to the default configuration document in a domain cannot be shared across multiple domain, because customizing configuration document is domain specific.

To configure the OWSM repository for multiple domain, do the following:

Prerequisites

Before configuring the domains for a single OWSM repository instance, you must complete the following:

You must install the Metadata Services (MDS), Oracle Platform Security Services (OPSS), Service Table (STB), and Audit Services Append (IAU_APPEND) schemas using the Repository Creation Utility (RCU). See Creating Database Schemas in Oracle Fusion Middleware Installing and Configuring the Oracle Fusion Middleware Infrastructure.
Note:
- The database schema associated with the domain being created must be brand new and cannot be one that has been previously used.
- You must create the schemas for each domain that will be managed by a centralized repository.
If your domains are sharing a single database instance then you must associate the domains with the database, as described in Sharing a Database Instance in Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services
Configure the OWSM domains using the Configuration Wizard, as described in Configuring Your WebLogic Domain in Oracle Fusion Middleware Installing and Configuring the Oracle Fusion Middleware Infrastructure.

Note:
From the Administration Server screen, ensure that you assign a a user-expandable server group to the Administration Server from the Server Group drop-down list.
Verify the service table entries and components using the the Fusion Middleware Control, as described in Verifying Service Table Entries and Components Using Fusion Middleware Control.
Verify that the OWSM Agent is wired correctly to the appropriate Policy Manager URL in a domain, as described in Verifying Agent Bindings Using Fusion Middleware Control.

Configuring the Domains

To share the OWSM documents and Application Metadata across multiple shared domains, complete the following:

Create a global policy set to secure the domains, by running the createWSMPolicySet command:
```
createWSMPolicySet(name, type, attachTo, [description=None], [enable='true'])
```
See Also:
Creating a New Policy Set Using WLST

Create a token issuer trust domain document for the domains (For example, base_domain1 and base_domain2) sharing a single OWSM Repository instance, using the createWSMTokenIssuerTrustDocument command.

Create and configure token issuer trust domain document for the base_domain1 by running createWSMTokenIssuerTrustDocument command:

wls:/base_domain/serverConfig>
createWSMTokenIssuerTrustDocument('tokenissuertrustWLSbase_domain1')
New Token Issuer Trust document named "tokenissuertrustWLSbase_domain1"
created.
Run the setWSMConfiguration command where category = "TokenIssuerTrust",
property name = "name" and value = "tokenissuertrustWLSbase_domain", for the
new
document to be used in the domain configuration.
wls:/base_domain/serverConfig> setWSMConfiguration
(None,'TokenIssuerTrust','name',None,['tokenissuertrustWLSbase_domain1'])
The values "[tokenissuertrustWLSbase_domain]" have been added to property
"name" within category "TokenIssuerTrust".
Configuration properties associated with the context "/WLS/base_domain1" has
been updated.

Configure token issuer trust domain document for the base_domain2 by running createWSMTokenIssuerTrustDocument command:

wls:/base_domain/serverConfig> setWSMConfiguration
(None,'TokenIssuerTrust','name',None,['tokenissuertrustWLSbase_domain2'])
The values "[tokenissuertrustWLSbase_domain]" have been added to property
"name" within category "TokenIssuerTrust".
Configuration properties associated with the context "/WLS/base_domain" has
been updated.

Create the OPSS Keystore to manage keys and certificates for SSL, message security, encryption, and related tasks. After you create the keystore, you must configure it for the domains (For example, base_domain1 and base_domain2) by running the configureWSMKeystore command:
```
configureWSMKeystore(context, keystoreType,location, keystorePassword, signAlias, signAliasPassword, cryptAlias, cryptAliasPassword)
```
See Also:
Configuring the OWSM Keystore Using WLST