Attaching a Policy to a Single Subject

A subject is an entity to which a policy can be associated. You can attach one or more policies to a subject.

The order in which policies are attached to a subject or appear in the list of attached polices does not determine the order in which policies are executed. As a message is passed between the client and the Web service, the order of the interceptors in the policy interceptor chain determines the order in which the policies are executed.

Policy attachment is not synchronized automatically for ADF and WebCenter Web services in a cluster. When using ADF and WebCenter Web services in a cluster, you must attach and/or detach policies to each instance of the cluster. This issue does not apply to SOA composite applications.

Use the attachWebServicePolicy command to attach a single policy to a Web service port. Specify the policy to be attached using the policyURI argument. If you specify a policy that is already attached or exists, then this command enables the policy if it is disabled.

Use the attachWebServicePolicies command to attach multiple policies to a Web service port. Specify the policies to be attached using the policyURIs argument. If any of the policies that you specify in this command are already attached, then this command enables the policies that are already attached (if they are disabled), and attaches the others.

The policyURIs are validated through the Oracle WSM Policy Manager APIs if the wsm-pm application is installed on WebLogic Server and is available. If the policy validation fails, a message is displayed and the command is not executed.

If the wsm-pm application is not installed or is not available, these commands are not executed.

Attaching a Policy to Multiple Subjects (Bulk Attachment)

From the Application pages, you can attach one or more policies to one or more Web services.

Note:

The bulk attachment mechanism does not perform validation on the policies that you attach.

The bulk attachment mechanism does not prevent you from creating an unsupported configuration such as having multiple authentication policies, or from attaching the same policy multiple times, and so forth.

Policy attachment is not synchronized automatically for ADF and WebCenter Web services in a cluster. When using ADF and WebCenter Web services in a cluster, you must attach and/or detach policies to each instance of the cluster. This issue does not apply to SOA composite applications.

To attach a policy to multiple Web services within an application:

In the navigator pane, expand WebLogic Domain to show the domain in which you want to attach the policy.

Select the domain, and then the instance of the server in which you want to attach the policy. The server can be an administration server or a managed server.

From the Select Policy Subjects page, select one or more applications to which to attach a policy, as shown in Figure 8-3.

Use the Search control to search for a particular policy subject type, a particular application name, or the type of Web service to which you want to attach a policy. Valid policy subject types include: Web Service Endpoint, Web Service Client, Web Service Connection, SOA Component, SOA Service, SOA Reference, or Asynchronous Callback Client. For more information about asynchronous callback clients, see "Developing Asynchronous Web Services" in Concepts Guide for Oracle Infrastructure Web Services.

For example, if you choose to search for a policy subject type of Web Service Client, only available Web service clients, if any, are displayed.

To select more than one application, press the Ctrl key and click the applications.

From the Select Policies page, select one or more policies that you want to attach to the selected applications, as shown in Figure 8-4. The Select Policies page shows only those policies that you can apply to all of the subjects selected in the previous step.

To select more than one policy, press the Ctrl key and click the policies you want to attach.

Click Back to make any changes, or click Attach to complete the bulk attachment.

Restart the application that uses the Web services.

Validating Policy Subjects

The type and number of assertions within a policy may be valid and, therefore, a policy may be internally consistent and valid. However, when more than one policy is attached to a policy subject, the combination of policies must also be valid. Specifically, the following must be true:

Only one MTOM policy can be attached to a policy subject.

Only one Reliable Messaging policy can be attached to a policy subject.

Only one WS-Addressing policy can be attached to a policy subject.

Only one Management policy can be attached to a policy subject.

Only one Security policy with subtype authentication can be attached to a subject.

Only one Security policy with subtype message protection can be attached to a subject.

Only one security policy with subtype authorization can be attached to a subject.

Note:

There may be either one or two security policies attached to a policy subject. A security policy can contain an assertion that belongs to the authentication or message protection subtype categories, or an assertion that belongs to both subtype categories. The second security policy contains an assertion that belongs to the authorization subtype.

If an authentication policy and an authorization policy are both attached to a policy subject, the authentication policy must precede the authorization policy.

If the policy requires a particular transport protocol (for example, HTTP or HTTPS), it checks to see that the Web service uses the expected transport protocol.

You cannot use policy subject validation to check the validity of multiple policy subjects when you use the bulk attachment feature. After you attach the policies to your subjects with this feature, you must validate each subject individually.

Note:

The policy subject validation does not validate the XML schema of the policy. Therefore, if you manually edit the policy file, you must use another tool to check that the XML is valid.

To check for policy subject validation:

From the navigator pane, click the plus sign (+) for the Application Deployments folder to expose the applications in the farm, and select the application.

In the Web Service Details section of the page, click on the plus (+) for the Web service to display the Web service ports if they are not already displayed.

Click the name of the port to navigate to the Web Service Endpoints page.

Click the Policies tab.

Click Attach/Detach.

Click Validate.

If there is a validation error, a dialog box appears describing the error. Fix the error and do a policy subject validation again.

Attaching Policies to Web Service Clients

This section describes how to attach a policy to a Web service client, including SOA reference, ADF Data Control (DC), and asynchronous Web service Callback clients.

When using WLST to attach policies to a Web service client, the steps that you follow are also the same for all Web service client types. The argument settings specify the type of client to which you are attaching the policy.

Using Fusion Middleware Control

In Fusion Middleware Control, the steps you follow to attach a policy to a Web service client are the same for all Web service client types. However, how you navigate to the Web service client varies based on the application type, as described in the following sections.

Attaching Policies to SOA References

The following procedures describe how to attach policies to SOA references. For more information about developing SOA references, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

From the Available Policies portion of the page, select one or more policies that you want to attach. Click Validate to validate the policy, or Check Services Compatibility to make sure that the client policies are compatible with the service policies.

Click Attach when you are sure that you want to attach the policy or policies.

Click OK.

Attaching Policies to ADF DC Web Service Clients

The following procedure describes how to attach policies to an ADF DC Web service client. For more information about developing ADF DC Web service clients, see "Using Oracle ADF Model in a Fusion Web Application" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To attach policies to an ADF DC Web service client:

Use Fusion Middleware Control to expand Application Deployments.

Click on the target application.

From the Application Deployments menu, select ADF.

Click on the Administration tab.

In the Configure Properties section of the page, click ADF Connections.

Select a row in the Web Service Connections list and click Configure Web Service.

From the Web Service Connection popup, select a Web service client to configure.

Click the Policies tab.

Click Attach/Detach.

From the Available Policies portion of the page, select one or more policies that you want to attach. Click Validate to validate the policy, or Check Services Compatibility to make sure that the client policies are compatible with the service policies.

Click Attach when you are sure that you want to attach the policy or policies.

Click OK.

Attaching Policies to Asynchronous Web Service Callback Clients

The following procedure describes how to attach policies to an asynchronous Web service Callback client. For more information about developing asynchronous Web services and callback clients, see "Developing Asynchronous Web Services" in Concepts Guide for Oracle Infrastructure Web Services.

Click Callback Client in the upper right portion of the endpoint page.

Click the Policy tab.

Click Attach/Detach.

From the Available Policies portion of the page, select one or more policies that you want to attach. Click Validate to validate the policy, or Check Services Compatibility to make sure that the client policies are compatible with the service policies.

Click Attach when you are sure that you want to attach the policy or policies.

Click OK.

Using WLST

The following procedure describes how to attach policies to SOA references, ADF Web service DC and WebCenter clients, and asynchronous Web service callback clients. The steps that you follow are the same for each type of client. However, the argument settings will vary depending on the type of client to which you are attaching or detaching policies.

For a SOA reference, specify the name of the SOA composite using the moduleOrCompName argument, specify soa for the moduleType argument, and the name of the SOA reference using the serviceRefName argument.

For an ADF DC or WebCenter client, specify the name of the client application using the application argument, specify wsconn for the moduleType argument, and the service reference name using the serviceRefName argument.

For an asynchronous Web service callback client, specify web for the moduleType argument. Specify the name of the client application or SOA composite using the application and moduleOrCompName arguments, respectively.

For all client types, specify the name of the port using the portInfoName argument.

Specify the policy to be attached using the policyURI argument. If you specify a policy that is already attached or exists, then this command enables the policy if it is disabled.

For example, to attach the client policy oracle/wss_username_token_client_policy to the HelloWorld_pt of the client service, use the following command:

Use the attachWebServiceClientPolicies command to attach multiple policies to a Web service client port. Set the arguments as described for attaching a single client policy above, however you specify multiple policies to be attached using the policyURIs argument. If any of the policies that you specify in this command are already attached, then this command enables the policies that are already attached (if they are disabled), and attaches the others.

The policyURIs are validated through the Oracle WSM Policy Manager APIs if the wsm-pm application is installed on WebLogic Server and is available. If the policy validation fails, a message is displayed and the command is not executed.

If the wsm-pm application is not installed or is not available, these commands are not executed.

Use the detachWebServiceClientPolicies command to detach multiple policies from a Web service client port. Set the arguments as described for detaching a single client policy above, however you specify multiple policies to be detached using the policyURIs argument.

Attaching Client Policies Permitting Overrides

The policy configuration override feature allows you to specify certain Web service client configuration information on a per-client basis, in addition to or in lieu of setting it globally for any attachment of the policy. This targeting of configuration information limits the number of distinct policies you need to maintain.

You can define a single policy, and specify a default value for a configuration value. Rather than creating multiple policies with slightly varied configurations, you could use the same generic policy and override specific values to meet your requirements.

For example, the oracle/wss_http_token_client_policy policy is one example of a policy that includes the csf-key property, which has a default value of basic.credentials. The value signifies a key that maps to a username/password. It might happen that you will always use the same key value any time you attach this policy to any number of Web service clients. In this case, you can specify the key value on the oracle/wss_http_token_client_policy policy Configurations page and have it apply to every instance.

However, you also have the option to override this key value on a per-client basis. After you attach a client policy that includes a property you can override, you can then supply a value in the Security Configuration Setting section of the Policies page, as shown in Figure 8-6.

You can override only the following properties in Web service client policies:

user.roles.include (Optional, does not have to be set.)

csf-key (Must be set on policy Configuration page or overridden.)

saml.issuer.name (Optional, does not have to be set.)

saml.assertion.filename (Optional, does not have to be set.)

service.principal.name (Must be set on policy Configuration page or overridden.)

keystore.recipient.alias (Can be set on policy Configuration page or overridden. Superseded by the "Using Service Identity Certification Extension" feature. If the client overrides the keystore.recipient.alias property, the override is always used, and not the certificate published in the WSDL.)

keystore.sig.csf.key (Optional, does not have to be set.)

keystore.enc.csf.key (Optional, does not have to be set.)

Note:

The keystore.enc.csf.key property puts the client's certificate in the replyTo header.

For WSS11 policies, keystore.enc.csf.key is used for asynchronous clients only.

For WSS10 policies, keystore.enc.csf.key is used for both asynchronous and synchronous clients.

Clearing a Configuration Property

If you need to clear an overridden configuration property, set it to an empty string.

Before you clear it, remember that other policies could be using the same property. The properties are client-specific and there could be multiple policies that are attached to the same client that use the same property.

Attaching Web Service Policies Permitting Overrides

You can specify a value for server-side configuration properties in a predefined or custom Web service policy, and then either use that value each time you attach the policy to a Web service or override it on a per-attachment basis.

For example, you might specify an IP address as a configuration property, and then validate the IP address from your Web service.

The scope for the server-side configuration property value is limited to the specific policy. That is, you could have two policies with the same server-side configuration property name, say P1, attached to the same Web service endpoint, and the two P1 properties can have different values.

Server side properties that you can override are of two types: included in the predefined policies, and user defined.

The server-side configuration properties included with the predefined policies allow you to override certain domain-wide configuration settings from a policy, such as the CSF key used for storing the signature-key password.

For a user-defined property, you can add a property that has meaning in your environment. You can add a user-defined server-side property to the predefined policies, or to a custom policy.

This release of Oracle WSM includes the server-side override properties shown in Table 8-1 for message protection policies.

If you set (or then override) these properties, the new values are used in the attached Web service instead of the keystore passwords you configure as part of setting up the keystore for message protection, as described in "Setting up the Keystore for Message Protection".

Setting Default Values for the Configuration Properties

By default, the keystore.sig.csf.key and keystore.enc.csf.key properties have a blank value. You can choose to set a value such that any Web service that attaches the policy can use these values, or override the values when you attach the policy.

Overriding the Configuration Properties When Attaching a Policy

After you attach a message protection policy that includes a server-side configuration property, you can then override the existing value. In Fusion Middleware Control, you do this using the Security Configuration Setting section of the Policies page. In WLST, you do so using the setWebServicePolicyOverride command as described in "Overriding Configuration Properties When Attaching a Policy Using WLST".

To do this using Fusion Middleware Control, select the attached policy with the server-side configuration property. The Security Configuration Details portion of the page appears, as shown in Figure 8-8.

For example, assume that you have not changed the value of the keystore.sig.csf.key property for the oracle/wss10_message_protection_service_policy policy and that it is still blank. If Web service A attaches the oracle/wss10_message_protection_service_policy policy and overrides the keystore.sig.csf.key property to be "sigkey," the keystore.sig.csf.key property has a value of "sigkey" only for the oracle/wss10_message_protection_service_policy policy attached to Web service A.

This release of Oracle WSM includes the server-side override properties shown in Table 8-2 for the oracle/binding_permission_authorization_policy policy. You can use these properties to set a different action and resource.

Specify the Web service name (Namespace of Web service plus ServiceName)

Setting Default Values for the Configuration Properties

By default, the action and resource properties have a value of *. You can choose to set a different value such that any Web service that attaches the policy can use that value, or override the value when you attach the policy.

From the Web Services Policies page, select the oracle/binding_permission_authorization_policy policy from the Policies table and click Edit.

On the Edit Policy page, click the Configurations tab.

Select the configuration property and click Edit to make the change to the action or resource property based on your environment.

Validate your changes.

Click Save.

Overriding the Configuration Properties When Attaching a Policy

After you attach the oracle/binding_permission_authorization_policy policy, you can then override the existing value in the Security Configuration Setting section of the Policies page using Fusion Middleware Control. In WLST, you do so using the setWebServicePolicyOverride command as described in "Overriding Configuration Properties When Attaching a Policy Using WLST".

To do this using Fusion Middleware Control, select the attached oracle/binding_permission_authorization_policy policy. The Security Configuration Details portion of the page appears.

Configuring User-Defined Client- or Server-Side Override Properties

You can use the Add New Configure Property feature to add one or more configuration properties that have meaning in your environment. Specifically, you can add one or more user-defined server- or client-side properties to the predefined policies, or to a custom policy. Then, you can either use the user-defined property as-is, or override it when you attach the policy.

In both cases, the property must already exist in the policy before you can override it when attaching the policy to a Web service or client. That is, you can override only those properties that are already present in the policy.

Therefore, you would typically add a user-supplied property with some default value to the predefined or custom policy, and then override it on a per-attachment basis.

You can add a user-defined property of type required, optional, or constant, but you cannot override a property of type constant.

Scope of User-Defined Configuration Properties

As with the predefined configuration properties, the scope for user-defined configuration properties in a policy differs for clients and Web services. Consider the following:

The scope for a client-side configuration property value is the client. There could be multiple policies that are attached to the same client that use the same property.

The scope for a server-side configuration property value is limited to the specific policy. That is, you could have two policies with the same server-side configuration property name, say P1, attached to the same Web service endpoint, and the two P1 properties can have different values.

Adding a User-Defined Configuration Property

You edit the predefined or custom policy to add a user-defined configuration property.

From the Web Services Policies page, select the policy for which you want to delete a property from the Policies table and click Edit.

On the Edit Policy page, click the Configurations tab.

Select the user-defined configuration property you want to delete and click Delete.

Validate the policy.

Click Save.

Overriding the Configuration Properties When Attaching a Policy

When you attach a policy that has a user-defined configuration property, you can override the existing value in the Security Configuration Setting section of the Policies page using Fusion Middleware Control. In WLST, you do so using the setWebServicePolicyOverride command as described in "Overriding Configuration Properties When Attaching a Policy Using WLST".