6 Managing Web Service Policies with Fusion Middleware Control
For information about web services policies and how Oracle Web Services Manager (OWSM) uses policies to manage Quality of Service (QoS) for web services, see Overview of OWSM Policy Framework in Understanding Oracle Web Services Manager. The following sections describe managing web service policies with fusion middleware control:
6.1 Overview of Web Services Policy Management
In the 12c release, the predefined documents delivered with OWSM, including policies and assertion templates, are read-only. If this is a new installation, then all of the documents that are installed with OWSM will be read-only. To modify a predefined policy or assertion template, you will need to clone it and then make the desired modifications to the cloned version.
If you are installing into an existing OWSM environment, or if you are upgrading from an older release, any predefined documents that have not been customized for your environment are replaced with read-only versions, and new predefined read-only documents are added. Note, however, that any existing predefined documents that you have customized, and user-created custom policies in the repository are not overwritten.
Note:
To ensure that you always get all of the latest policies, Oracle recommends that you clone any predefined documents that you have modified and migrate any policy attachments. For details, see "Upgrading the OWSM Repository".
6.2 Managing Web Service Policies
From Managing Web Service Policies page you can search for specific policies or types of policies, view policies, create new policies, edit custom policies, delete custom policies, and import and export custom policies to or from the OWSM repository.
Topics:
6.2.1 Navigating to the WSM Policies Page
Use the WSM Policies page to manage the web service policies. From this page you can search for specific policies or types of policies, view policies, create new policies, edit custom policies, delete custom policies, and import and export policies to or from the OWSM repository.
6.2.2 Searching for Policies in the WSM Policies Page
Use the WSM Policies page to search for policies using the advanced search feature, the Query by Example filter, or a combination of the two to refine the search.
Details of searching for policies is provided in the following sections:
6.2.2.1 Using Advanced Search
In theWSM Policies page, you can reduce the number of policies that are returned by specifying the appropriate search criteria. To do so, perform the following steps:
6.2.3 Viewing the Details of a Web Service Policy
Use the WSM Policies page to view the details of a web service policy.
Predefined policies from Oracle are read-only and cannot be modified. These policies are displayed in read-only mode. User-created policies are not read-only, and can be edited as described in "Editing a Web Service Policy".
Perform the following steps to view the details of a web service policy:
6.2.4 Creating and Editing Web Service Policies
Use the WSM Policy Details page, to create and edit web service policies.
Topics:
6.2.4.1 Creating a New Web Service Policy
Use the following procedure to create a new policy using one or more assertion templates.
Perform the following steps to create a new web service policy
6.2.4.2 Cloning a Web Service Policy
You can create a new policy by cloning an existing web service policy. For example, you can create a copy of one of the read-only predefined policies and edit it to suit your needs. You can also create a copy of a policy that you have created. Once the policy is created, you can treat it like any other user-created policy, adding or deleting assertions, and modifying existing assertions.
Perform the following steps to clone a web service policy:
6.2.4.3 Creating Custom Policies
You can create custom policies using custom assertions.
For more information and procedures about how to create both custom assertions and policies, see "Creating Custom Assertions" in Developing Extensible Applications for Oracle Web Services Manager.
6.2.4.4 Editing a Web Service Policy
You can edit a user-created policy as described in this topic.
Note:
The predefined policies that are provided with OWSM are read-only and cannot be edited. To edit a predefined policy you can clone it and then edit the cloned version.
The changes that you make to the policy take effect at the next polling interval for policy changes.
If you are using a database-based metadata repository, each time you save a change to your policy, a new version is created, and the older versions are retained. For more information about policy versioning, see "Versioning Web Service Policies".
Perform the following steps to edit a web service policy:
6.2.5 Using Local Optimization with OWSM Policies (SOA Composites)
OWSM supports an Oracle SOA Suite local optimization feature for composite-to-composite invocations in which the reference of one composite specifies a web service binding to a second composite running in the same container. Local optimization enables you to bypass the HTTP stack and SOAP/normalized message conversions during run time. If a policy is attached to the web service binding, the policy may not be invoked if local optimization is used.
Topics:
For details about the SOA local optimization feature, see "Configuring Local Optimization" in Administering Oracle SOA Suite and Oracle Business Process Management Suite.
6.2.5.1 Viewing the Default Local Optimization Setting in OWSM Policies
By default, each of the OWSM predefined policies includes a local optimization property. The default setting for the Local Optimization property is displayed on the General tab of each policy. Procedures for viewing the details of a policy using Fusion Middleware Control, including the Local Optimization property setting, are described in "Viewing the Details of a Web Service Policy".
There are three possible settings for the Local Optimization property:
-
on
— Local optimization is turned on in the policy and the policy is not applied at runtime. -
off
— Local optimization is turned off and the policy is applied at runtime. The request goes through the usual WS/SOAP/HTTP process. -
check-identity
— Local optimization is used only if a JAAS subject exists in the current thread, indicating that authentication has already succeeded. If the JAAS subject does not exist in the thread, the request goes through the usual WS/SOAP/HTTP process.
6.2.5.2 Controlling When Local Optimization is Used
There are two ways to control the local optimization feature, and they have different scopes:
-
At the composite level, by adding the
oracle.webservices.local.optimization
property in the binding section of thecomposite.xml
file. The following values are supported:-
true
-- (Default value). Local optimization is used if the attached policy is configured to use it. For a description of the local optimization property settings, see "Viewing the Default Local Optimization Setting in OWSM Policies". If optimization is used, the policy is not applied. -
false
-- Local optimization is not used, regardless of the how the local optimization property is configured in the policy. This setting forces the policy to be applied.
The composite-level property is independent of the policy-level configuration. That is, if you want to turn off the optimization regardless of whether a policy is attached, set the composite-level property to
false
.For more information, see "Policy Attachments and Local Optimization in Composite-to-Composite Invocations" in Administering Oracle SOA Suite and Oracle Business Process Management Suite.
-
-
At the policy level, by configuring the local optimization property for a policy. The possible settings for the local optimization property are described in "Viewing the Default Local Optimization Setting in OWSM Policies". The policy-level property controls the optimization wherever the policy is used, unless it has been overridden by the composite-level property.
Note:
Predefined policies from Oracle are read-only and cannot be modified. If you clone a predefined policy, Oracle recommends that you do not change the local optimization setting. Doing so may prevent the policy from being invoked, resulting in unexpected behavior. If you create a new policy, however, you can set this property as required for your environment.
If a policy is attached to a web service, the policy may not be invoked if local optimization is used. Therefore, for each new policy that you create, you need to decide whether you want to use local optimization.
6.2.6 Generating Client Policies from a WSDL
After you have configured a web service, you can use the web service WSDL to generate compatible client policies with the parameters required to call that service. Note that only assertions that are advertised in a policy can be used to generate equivalent client assertions in the client policy.
Note:
You must use the Oracle WSDL instead of the standard WSDL to generate the client policy. The URL for the web service must be appended with ?orawsdl, instead of ?wsdl. Generating the policy increases the likelihood that the client policy will work with the service policy.
When you generate a client policy, it is populated with the client assertion that is the matching pair to the advertised service assertion. For example, if the service policy in the WSDL contained the oracle/ wss_http_token_service_template, then the generated client policy is populated with its counterpart, oracle/wss_http_token_client_template.
Before editing the policy, you must first save it. After you have made the desired changes to the policy, you can access it from the WSM Policies page.
You can also delete any generated policies that you do not need. For example, you may want to delete duplicates of already existing MTOM or Reliable Messaging policies.
Perform the following steps to create a web service client policy:
Once the policy is saved, you can navigate to the WSM Policies page and find the policy in the list of policies.
6.2.7 Adding Assertions to a Policy
You can add assertions to a user-created policy during policy creation or editing. You cannot add assertions to the predefined policies provided with OWSM. The predefined policies are read-only and cannot be modified.
Each policy can contain only one assertion for each of the following categories: MTOM Attachments and Reliable Messaging. The policy can contain any number of assertions belonging to the Security category; however, the combination of assertions must be valid. For more information on valid assertions, see "Validating Web Service Policies".
Perform the following steps to add an assertion to a policy:
6.2.8 Adding an OR Group to a Policy
You can create an OR group, consisting of one or more assertions, enabling a single policy to accept multiple types of security tokens. A client can enforce any one of the policies that are defined in the OR group.
For more information, see "Defining Multiple Policy Alternatives (OR Groups)" in Understanding Oracle Web Services Manager.
You can add only one OR group to a policy. Once you have added an OR Group, the OR Group option is greyed out.
You add an OR group from the Policy Details page.
Perform the following steps to add an OR group to a policy:
6.2.9 Importing Web Service Policies
Follow the procedure in this section to import one or more user-created policies into the OWSM repository. Once the policies are imported, you can attach them to web services and make changes to them.
For more information on importing web service policies, see "Understanding the Different Mechanisms for Importing and Exporting Policies".
Note:
The policy name you import must not already exist in the repository.
Be aware that "policy name" and "file name" are different. The policy name is specified by the name attribute of the policy content; the file name is the name of the policy file. You might find it convenient for the two names to match, but it is not required.
You cannot prefix the name of a policy with oracle_. Otherwise, you will receive exceptions when you try to use the policy.
Perform the following steps to import one or more web service policies:
6.2.10 Exporting Web Service Policies
You may want to export a policy to copy it from a development environment to a production environment, or to simply view the policy in another tool or application.
You can export web service policies that you have created as described in "Creating and Editing Web Service Policies". Predefined policies cannot be exported because the same read-only version of the policy will exist in the target environment. Once the policy is exported, you can import it to another repository, attach it to web services, make changes to it, and so forth.
For more information about exporting web service policies, see "Understanding the Different Mechanisms for Importing and Exporting Policies".
Use the following procedure to export a policy from the OWSM repository:
6.2.11 Versioning Web Service Policies
Whenever a change to a user-created policy is saved, a new version of the policy is automatically created and the version number is incremented. The Policy Manager maintains the history of these changes, enabling you to go back to an earlier version.
Note:
Version control does not apply to the Oracle predefined policies because they are read only and cannot be modified.
Policy versioning requires that you use a database-based OWSM Repository. If you are using a file-based repository, versioning information is not maintained or displayed.
The recreation of a document (either by importing an existing document or by creating a new document) with the same name that already exists in the repository will result in increment of the version number.
For example, you might find it useful to create two different versions of a policy, perhaps one with logging and one without, and alternate between them. As another example, you might have an occasional need to use a policy such as oracle/binding_authorization_denyall_policy
policy with selected roles to temporarily lock down access to a web service.
By using the versioning feature, you can reuse multiple versions of a policy without having to recreate them every time you need them.
You can also delete any version of the policy, except the active policy, from the Policy Version history table by selecting the policy and clicking Delete.
You cannot edit the policy from the Policy Version history page. You must edit a policy from the Policy Details page.
The following sections describe versioning in more detail:
6.2.11.1 Viewing the Version History of a Web Service Policy
You can view the version history for a web service policy from the Policy Version history page, which you can access from the Policy Details page.
Perform the following steps to view the version history for a policy:
6.2.11.2 Changing the Current Version of a Policy
Use this procedure to change the current version of the policy:
6.2.11.3 Deleting Versions of a Web Service Policy
Use the following procedure to delete earlier versions of a policy. You can delete all versions except the active policy version. To delete all versions of the policy, including the active version, see "Deleting a Web Service Policy".
Perform the following steps to delete the version of a web service policy:
6.2.12 Deleting a Web Service Policy
Before you delete a policy, Oracle recommends that you verify that the policy is not attached to any policy subjects. If you try to delete a policy that is attached to a subject, you will receive a warning. You will not be prevented from deleting an attached policy. However, the web service request will fail the next time the subject to which the policy is attached is invoked.
Note:
Only user-created policies can be deleted. The predefined policies delivered with OWSM are read only and cannot be edited or deleted.
When you delete a policy, the active policy and all previous versions of the policy are deleted. To retain the active policy version and delete only the previous versions of the policy, see "Deleting Versions of a Web Service Policy".
Perform the following steps to delete a user-created web service policy:
6.3 Validating Web Service Policies
There are restrictions on the type and number of policy assertions that are permitted in a web service policy. A policy can contain only assertions that belong to a single category. Therefore, you cannot combine a Security assertion with an MTOM assertion in the same policy. The policy type is determined by the category of the assertion. Therefore, a policy containing a security assertion is a security policy, a policy containing a management assertion is a management policy, and so on. Security assertions are further categorized into subcategories: authentication, logging, message protection (msg-protection), and authorization.
There are restrictions on the number and type of assertions you can have in a policy. The restrictions are as follows:
-
MTOM and Reliable Messaging policies can contain only one assertion.
-
A security policy can contain multiple security assertions; however, there can be only one assertion from the following subcategories in a policy: encryption, signing, and authentication.
-
Some assertions contain both authentication and message protection. For example, if you view the
oracle/wss11_username_token_with_message_protection_service_policy
, you will see that the second assertion falls into two categories: security/authentication and security/msg-protection, as shown in Figure 6-6.Figure 6-6 Security Assertion with Two Subcategories
-
A security policy can contain any number of security_log_template assertions. For example, if you view any of the predefined security policies, you will see two logging assertions included.
Oracle recommends that you create one policy for authentication and message protection, and a second policy for authorization. If you create a policy that contains both an authentication and an authorization assertion, then the authentication assertion must precede the authorization assertion.
When you create a new policy or edit a user-created policy, the validation process checks to see that your policies meet these requirements. If the validation fails during policy creation, the policy is created but is marked as disabled.
Perform the following steps to validate a policy:
6.4 Managing Policy Assertion Templates
OWSM includes a set of predefined assertion templates that you can use to construct policies. The predefined assertion templates are read only and cannot be modified, but you can clone them to create new assertion templates, if needed, to satisfy a specific requirement.
For additional information, see "Building Policies Using Policy Assertions" in Understanding Oracle Web Services Manager.
If the functionality you require, such as support for a non-standard security token, is not provided out of the box, OWSM allows you to define custom policy assertions. For details, see Creating Custom Assertions.
You can add one or more assertions to a user-created policy as described in "Adding Assertions to a Policy". You cannot add assertions to the predefined policies that are provided with OWSM because they are read-only and cannot be modified. Assertions are executed in the order in which they are listed in the policy.
For details about the predefined assertion templates, see Oracle Web Services Manager Predefined Assertion Templates.
The following sections provide more detail about managing policy assertion templates:
6.4.1 About Navigating to the Assertion Templates Page
You can manage your assertion templates at the domain level from the Assertion Templates page. From this page, you can copy, edit, and delete, import, and export assertion templates.
6.4.2 Understanding Search Options on the Assertion Templates Page
You can search for assertion templates in the Assertion Templates page using the advanced search feature, the Query by Example filter, or a combination of the two to refine the search.
Details are provided in the following sections:
6.4.2.1 Searching for an Assertion Template Using Advanced Search
In the Assertion Templates page, you can reduce the number of assertion templates that are returned by specifying the appropriate search criteria. To do so:
6.4.3 Viewing the Details of an Assertion Template
Use these procedure to view the details of an assertion template. Predefined assertion templates from Oracle are read-only and cannot be modified. These assertion templates are displayed in read-only mode. User-created assertion templates are not read-only, and can be edited.
Perform the following steps to view the assertion template details:
6.4.4 Naming Conventions for Assertion Templates
The same naming conventions used to name predefined policies are used to name the assertion templates.
The predefined assertion templates begin with the directory name oracle/
and are identified with the suffix _template
at the end; for example, oracle/wss10_message_protection_service_template.
It is recommended that you follow the recommended naming conventions, and keep any assertion templates that you create in a directory that is separate from the oracle directory where the predefined assertion templates are located. You can organize your assertion templates at the root level, in a directory other than oracle, or in subdirectories.
For more information about the naming conventions for predefined policies, see "Recommended Naming Conventions for Policies" in Understanding Oracle Web Services Manager.
6.4.5 Cloning an Assertion Template
You can create a new assertion template using an existing template as the base. Select the assertion template that most closely matches the desired behavior, make a copy of it using the Create Like feature, then make any changes required to get the new behavior.
Perform the following steps to clone a web service policy:
6.4.6 Editing an Assertion Template
You can edit a user-created assertion template as described in the following procedure.
Note:
The predefined assertion templates that are provided with OWSM are read-only and cannot be edited. To edit a predefined template you can clone it and then edit the cloned version.
Perform the following steps to edit an assertion template:
6.4.7 Editing the Configuration Properties in an Assertion Template
If you have cloned one of the predefined assertion templates, you can modify the configuration properties to match your environment. For example, properties that are configurable in assertion templates include csf-key
, saml.issuer.name
, keystore.recipient.alias
, and role
, among others.
Note:
You cannot modify the configuration properties in the predefined assertion templates because they are read-only and cannot be modified.
When you clone an assertion template, or edit a cloned assertion template, you can configure the following settings for each property:
-
Description—Description of the property.
-
Value—Current value.
-
Default—Default value. This value is used if the Value field is not set.
-
Type—Can be one of the following:
-
Constant—Property cannot be overridden.
-
Required—Property is required and can be overridden. This value determines if the Value property needs to have a value or it could be left blank.
-
Optional—Property is optional and can be overridden.
-
Perform the following steps to configure the properties:
6.4.8 Exporting an Assertion Template
You can export one or more assertion templates that you have created. Predefined assertion templates can not be exported because the same read-only version of the template will exist in the target environment. After you have exported the assertion templates, you can then copy them to a new directory if desired, or import them into another repository.
Exporting one or more assertion templates is described in "Cloning an Assertion Template".
Perform the following steps to export one or more assertion templates:
6.4.9 Importing an Assertion Template
Follow the steps in this section to import a zip archive containing one or more user-created assertion templates. You can use this feature in combination with Export to move one or more assertion templates between different repositories. Once the assertion template is imported, you can add it to web service policies and make changes to it.
Perform the following steps to import an assertion template:
6.5 Managing Policies and Assertions
You can enable or disable policies, or assertions within a policy.
The following sections describe the different methods for enabling or disabling policies, or assertions within a policy:
6.5.1 Enabling or Disabling a Policy for all Policy Subjects
When you create a policy, it is enabled by default unless it has validation errors. A user-created policy can be globally enabled or disabled from the Policy Details page. You can enable or disable the policy from one central location, and it will be enabled or disabled for any policy subject to which it is attached.
Note:
You cannot disable a predefined policy from Oracle for all policy subjects. These policies are read-only and cannot be modified. You can, however, disable policy references to an individual subject. For more information, see "Enabling or Disabling Directly Attached Policies Using Fusion Middleware Control".
When you disable a policy from the Policy Details page, the policy continues to be attached to the policy subjects, but the policy is not enforced. You may want to temporarily disable a policy if you discover that there is a problem with the policy that is causing all requests to a web service to fail. Once the problem is corrected, you can globally enable the policy.
You may also selectively enable or disable a policy for a specific policy subject rather than for all policy subjects. For more information, see "Enabling or Disabling Directly Attached Policies Using Fusion Middleware Control".
Perform the following steps to enable or disable a user-created web service policy for all policy subjects:
6.5.2 Enabling or Disabling Assertions Within a Policy
You can enable or disable one or more of the assertions that are contained within a policy. This provides a more fine-grained level of control over the assertions that are executed.
Note:
You cannot disable an assertion in a predefined policy from Oracle. These policies are read-only and cannot be modified. To disable an assertion in a predefined policy, you need to clone it and then edit the cloned version.
For example, if you created a policy based on one of the read-only predefined web service security policies, it contains an instance of the Security Log Assertion Template (oracle/security_log_template
), to capture the entire SOAP message before and after the primary security assertion is executed. By default, the log assertion is not enforced. You must enable it in order for the SOAP message to be logged in message logs. (It is recommended that the logging assertion be enabled for debugging and auditing purposes only. For more information about logging, see "Diagnosing Problems Using Logs" in Administering Web Services.
Perform the following steps to enable or disable one or more assertions within a policy:
6.6 Analyzing Policy Usage
The policy usage feature described in this section requires that you use a database-based OWSM Repository. If you are not using a database-based repository, policy usage information is not available.
Policies are created and managed at the domain level. The central management of policies gives you the ability to reuse policies and attach them to multiple policy subjects. Any change to a policy (for example, editing a policy or deleting a policy) affects all policy subjects to which the policy is attached. Therefore, before making any changes to your policies, Oracle recommends you do a usage analysis to see which subjects are using a particular policy.
Note:
The usage analysis simply identifies which policy subjects will be affected; it does not define the effect of the change. You need to evaluate the change on each of the policy subjects and determine if you should proceed.
Perform the following steps to perform a usage anlysis
Please note:
-
Both enabled and disabled policy references are included in the policy usage count. For information about disabling a policy reference, see "Enabling or Disabling Directly Attached Policies Using Fusion Middleware Control" and "Enabling or Disabling a Policy for all Policy Subjects".
-
You must invoke an ADF DC client to display an accurate policy usage count.
6.7 About Advertising Policy Assertions
You can enable the advertisement of a policy assertion within the WSDL file.
The advertisement of a policy assertion within the WSDL file is enabled by selecting the Advertised option on the Assertions tab, as shown in Figure 6-8, when performing any of the following tasks:
-
Creating or editing an assertion template, as described in "Creating and Editing Web Service Policies".
-
Adding an assertion or OR group to a policy, as described in:
Note:
Advertisement of policy assertions in a WADL file is not supported. The Advertised option has no effect when the associated policy is attached to a RESTful web service.
Figure 6-8 Enabling Advertising for Policy Assertions
6.8 About Advertising WS-Policy and WS-SecurityPolicy Versions
For a standard WSDL (?wsdl
) file, you can publish different version combinations for WS-Policy and WS-SecurityPolicy.
For example, http://localhost:8080/abc?wsdl&wsp=1.5&wssp=1.2 returns a WSDL with the following policy versions published: WS-Policy 1.5 and WS-SecurityPolicy 1.2.
Note:
For an Oracle WSDL (?orawsdl), you cannot advertise different version combinations for WS-Policy and WS-SecurityPolicy. For ?orawsdl, the policy is advertised with the following versions only: WS-Policy 1.2 and WS-SecurityPolicy 1.1 with Oracle extensions.
Table 6-1 lists the valid version combinations.
Table 6-1 Policy Advertisement
Version Combination | Description |
---|---|
?wsdl |
WS-Policy 1.2 and WS-SecurityPolicy 1.1 |
?wsdl&wsp=1.5 |
WS-Policy version 1.5 and WS-SecurityPolicy 1.3 |
?wsdl&wssp=1.2 |
WS-Policy versions 1.5 and WS-SecurityPolicy 1.2 |
?wsdl&wssp=1.3 |
WS-Policy versions 1.5 and WS-SecurityPolicy 1.3 |
?wsdl&wsp=1.5&wssp=1.2 |
WS-Policy 1.5 and WS-SecurityPolicy 1.2 |
?wsdl&wsp=1.5&wssp=1.3 |
WS-Policy 1.5 and WS-SecurityPolicy 1.3 |
?wsdl&wsp=1.2&wssp=1.2 |
WS-Policy 1.2 and WS-SecurityPolicy 1.2 |