8 Attaching Policies to Web Services

This chapter includes the following sections:

• Viewing the Policies That are Attached to a Web Service

• Attaching a Policy to a Single Subject

• Attaching a Policy to Multiple Subjects (Bulk Attachment)

• Validating Policy Subjects

• Attaching Policies to Web Service Clients

• Attaching Client Policies Permitting Overrides

• Attaching Web Service Policies Permitting Overrides

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

• Overriding Configuration Properties When Attaching a Policy Using WLST

Viewing the Policies That are Attached to a Web Service

The following sections describe how to view the policies that are attached to a Web service using Fusion Middleware Control and the WebLogic Scripting Tool (WLST).

Using Fusion Middleware Control

To view the policies that are attached to a Web service:

1. Navigate to the home page for the Web service, as described in "Navigating to the Web Services Summary Page for an Application".

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

3. Click the name of a port to navigate to the Web Service Endpoints page for a particular Web service.

4. Click the Policies tab.

   A list of the policies that are attached to the port is displayed, as shown in Figure 8-1.

   Note:

   This figure shows the screen display for an Oracle Infrastructure Web service endpoint. The Charts and Configuration tabs are not available for WebLogic JEE Web service endpoints.

   Figure 8-1 Policies Attached to a Web Service

   
   Description of "Figure 8-1 Policies Attached to a Web Service"
   
   

Using WLST

Use the following procedure to view the policies that are attached to a Web service:

Note:

This procedure applies to Oracle Infrastructure Web services only.

1. Connect to the running instance of WebLogic Server to which the application is deployed as described in "Accessing the Web Services Custom WLST Commands".

2. Use the listWebServices WLST command to display a list of the Web services in your application as described in "Viewing the Web Services in Your Application".

3. Use the listWebServicePorts command to display the port name and endpoint URL for a Web service.

   listWebServicePorts(application,moduleOrCompName,moduleType,serviceName)
   

   For example, to display the port for the WsdlConcreteService:

   wls:/wls-domain/serverConfig> listWebServicePorts("/wls-domain/AdminServer/jaxwsejb30ws",
   "jaxwsejb","web","WsdlConcreteService")
    
   WsdlConcretePort   http://host.us.oracle.com:7001/jaxwsejb/WsdlAbstract
   

4. Use the listWebServicePolicies command to view the policies that are attached to a Web service port.

   listWebServicePolicies(application,moduleOrCompName,moduleType,serviceName,subjectName)
   

   For example, to view the policies attached to the WsdlConcretePort port and any policy override settings:

   wls:/wls_domain/serverConfig> listWebServicePolicies("/wls_domain/AdminServer/jaxwsejb30ws",
   "jaxwsejb","web","WsdlConcreteService","WsdlConcretePort")
    
   WsdlConcretePort : 
   addressing : oracle/wsaddr_policy , enabled=true
   management : oracle/log_policy , enabled=true
   

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.

See "How Policies are Executed" for more information.

Note:

Policy attachment is not synchronized automatically for ADF, WebCenter, and WebLogic JEE Web services in a cluster. When using ADF, WebCenter, and WebLogic JEE 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.

Attaching a Policy to a Web Service Using Fusion Middleware Control

Follow this procedure to attach a policy to a single Web service. See "Attaching a Policy to Multiple Subjects (Bulk Attachment)" to attach a policy to multiple Web services at the same time.

Note:

For WebLogic JEE Web services policy attachment using Fusion Middleware Control:

• Only Oracle WSM security policies can be attached.

• Oracle WSM policies and WebLogic Web Service policies cannot be attached to the same endpoint. If a WebLogic JEE endpoint has WebLogic polices attached, you cannot attach Oracle WSM security policies using Fusion Middleware Control. Note that WebLogic policies can be attached using the WebLogic Server Administration Console. You cannot attach WebLogic policies using Fusion Middleware Control.

To attach a policy to a Web service:

1. Navigate to the home page for the Web service, as described in "Navigating to the Web Services Summary Page for an Application".

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

3. Click the name of a port to navigate to the Web Service Endpoints page for a particular Web service.

4. Click the Policies tab.

   A list of the policies that are already attached to the port is displayed. For example, consider the policies shown in Figure 8-1.

5. Click Attach/Detach.

6. Select a policy from the Available Policies list, and click Attach. See Figure 8-2.

   Figure 8-2 Attaching Policies to a Web Service

   
   Description of "Figure 8-2 Attaching Policies to a Web Service "
   
   

7. To view details about a policy, select the policy and click the View Detail icon. A pop-up window provides a full read-only description of the policy and lists the assertions that it contains. See Figure 8-3. Click OK when you are finished reviewing the details of the policy.

   Figure 8-3 Viewing Details about a Policy

   
   Description of "Figure 8-3 Viewing Details about a Policy"
   
   

8. Continue selecting and attaching policies. When you are finished, click Validate to verify that the combination of policies selected are valid.

9. Click OK.

10. The Web Service Endpoint page now displays the attached policy on the Policies tab.

11. For ADF and WebCenter applications, restart the Web service application. You do not need to restart a SOA composite or a WebLogic JEE Web service application.

    Note:

    You need to wait approximately 30 seconds (or the equivalent of the configured Graceful Shutdown Timeout time) between stopping and restarting the application. During this time, the server is allowing all global transactions to complete before shutting down the application. If you do not wait the configured Graceful Shutdown Timeout time, then the application will not be restarted appropriately and you will not be able to access it. To avoid waiting the graceful shutdown timeout period, you can restart the application twice.

Attaching a Policy to a Web Service Using WLST

Use the following procedure to attach (or detach) a single policy, or multiple policies, to a single Web service port using WLST.

Note:

This procedure applies to Oracle Infrastructure Web services only.

1. View the list of policies currently attached to the port as described in "Using WLST" in "Viewing the Policies That are Attached to a Web Service".

2. View the list of available policies as described in "Displaying a List of the Available Policies Using WLST".

3. To attach policies, do one of the following:

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

     attachWebServicePolicy(application, moduleOrCompName, moduleType, serviceName, 
     subjectName, policyURI, [subjectType=None]
     

     For example, to attach the policy oracle/wss_username_token_service_policy to the WsdlConcretePort of the WsdlConcreteService, use the following command:

     wls:/wls_domain/serverConfig> attachWebServicePolicy("/wls_domain/AdminServer/jaxwsejb30ws",
     "jaxwsejb","web","WsdlConcreteService","WsdlConcretePort",
     "oracle/wss_username_token_service_policy")
     

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

     attachWebServicePolicies(application, moduleOrCompName, moduleType,
      serviceName, subjectName, policyURIs, [subjectType=None]
     

     For example, to attach the policies oracle/wss_username_token_service_policy and oracle/wsrm10_policyto the WsdlConcretePort of the WsdlConcreteService, use the following command:

     wls:/wls_domain/serverConfig> attachWebServicePolicies("/wls_domain/AdminServer/jaxwsejb30ws",
     "jaxwsejb","web","WsdlConcreteService","WsdlConcretePort",
     ["oracle/wss_username_token_service_policy","oracle/wsrm10_policy"])
     
     Please restart application to uptake the policy changes.
     

   Note:

   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.

   For additional information about validating policies, see "Validating Policy Subjects".

4. To detach policies, do one of the following:

   • Use the detachWebServicePolicy command to detach a single policy from a Web service port. Specify the policy to be detached using the policyURI argument.

     detachWebServicePolicy(application, moduleOrCompName, moduleType,
      serviceName, subjectName, policyURI, [subjectType=None]
     

     For example, to detach the policy oracle/wss_username_token_service_policy from the WsdlConcretePort of the WsdlConcreteService, use the following command:

     wls:/wls_domain/serverConfig> detachWebServicePolicy("/wls_domain/AdminServer/jaxwsejb30ws",
     "jaxwsejb","web","WsdlConcreteService","WsdlConcretePort",
     "oracle/wss_username_token_service_policy")
     

   • Use the detachWebServicePolicies command to detach multiple policies from a Web service port. Specify the policies to be detached using the policyURIs argument.

     detachWebServicePolicies(application, moduleOrCompName, moduleType,
     serviceName, subjectName, policyURIs, [subjectType=None]
     

     For example, to detach the policies oracle/wss_username_token_service_policy and oracle/wsrm10_policyto the WsdlConcretePort of the WsdlConcreteService, use the following command:

     wls:/wls_domain/serverConfig> detachWebServicePolicies("/wls_domain/AdminServer/jaxwsejb30ws",
     "jaxwsejb","web","WsdlConcreteService","WsdlConcretePort",
     ["oracle/wss_username_token_service_policy","oracle/wsrm10_policy"])
     
     Please restart application to uptake the policy changes.
     

5. For ADF and WebCenter applications, restart the Web service application. You do not need to restart a SOA composite.

   Note:

   You need to wait approximately 30 seconds (or the equivalent of the configured Graceful Shutdown Timeout time) between stopping and restarting the application. During this time, the server is allowing all global transactions to complete before shutting down the application. If you do not wait the configured Graceful Shutdown Timeout time, then the application will not be restarted appropriately and you will not be able to access it. To avoid waiting the graceful shutdown timeout period, you can restart the application twice.

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

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.

Notes:

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, WebCenter, and WebLogic JEE Web services in a cluster. When using ADF, WebCenter, and WebLogic JEE 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:

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

2. Select the domain, and then the instance of the server to which you want to attach the policy. The server can be an Administration Server or a Managed Server.

3. Using Fusion Middleware Control, click WebLogic Server and then Web Services.

4. From the Web Services Summary page, click Attach Policies.

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

   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, Asynchronous Callback Client, or WLS Web Service Endpoint. For more information about asynchronous callback clients, see "Developing Asynchronous Web Services" in Oracle Fusion Middleware 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.

   Figure 8-4 Select Subjects Page

   
   Description of "Figure 8-4 Select Subjects Page"
   
   

6. Click Next.

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

   Note:

   You can attach only security policies to WebLogic JEE Web service endpoints using Fusion Middleware Control. If you attempt to attach a non-security policy to a WebLogic Web service endpoint, the action is ignored.

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

   Figure 8-5 Select Policies Page

   
   Description of "Figure 8-5 Select Policies Page"
   
   

8. Click Next.

   The Summary page displays the applications you selected and the policies that will be attached to those applications, as shown in Figure 8-6.

   Figure 8-6 Attachment Summary Page

   
   Description of "Figure 8-6 Attachment Summary Page"
   
   

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

10. For ADF and WebCenter applications, restart the Web service application. You do not need to restart a SOA composite or a WebLogic JEE Web service application.

    Note:

    You need to wait approximately 30 seconds (or the equivalent of the configured Graceful Shutdown Timeout time) between stopping and restarting the application. During this time, the server is allowing all global transactions to complete before shutting down the application. If you do not wait the configured Graceful Shutdown Timeout time, then the application will not be restarted appropriately and you will not be able to access it. To avoid waiting the graceful shutdown timeout period, you can restart the application twice.

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:

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

   The Application Deployment home page is displayed.

2. Using Fusion Middleware Control, click Application Deployment, then click Web Services.

   This takes you to the Web Services summary page for your application.

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

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

5. Click the Policies tab.

6. Click Attach/Detach.

7. 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 the same for all Web service client types. The argument settings specify the type of client to which you are attaching the policy.

Note:

Attaching Oracle WSM policies to WebLogic JEE Web service clients is not supported.

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.

To attach policies to a SOA reference:

1. View the SOA reference, as described in "Viewing SOA References".

2. Click the Policies tab.

3. Click Attach/Detach.

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

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

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

1. Use Fusion Middleware Control to expand Application Deployments.

2. Select the target application.

3. From the Application Deployment menu, select ADF, and then Configure ADF Connections.

4. On the ADF Connections Configuration page, select a row in the Web Service Connections list, and then use the Configure Web Service list to configure the Web Service client.

5. On the Web Service Client page, select the Policies tab.

6. Click Attach/Detach.

7. On the Available Policies section 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.

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

9. 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 Oracle Fusion Middleware Concepts Guide for Oracle Infrastructure Web Services.

To attach policies to an asynchronous Callback client:

1. Navigate to the endpoint for the asynchronous Web service, as described in "Viewing the Details for a Web Service Endpoint".

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

3. Click the Policy tab.

4. Click Attach/Detach.

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

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

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

1. View the Web service clients as described in Using WLST in "Viewing Web Service Clients".

2. Use the listWebServiceClientPorts command to display the port name and endpoint URL for a Web service client.

   listWebServiceClientPorts(application,moduleOrCompName,moduleType,serviceRefName)
   

   For example, to display the port for the service reference client:

   wls:/wls-domain/serverConfig> listWebServiceClientPorts('/base_domain/AdminServer/application1#V2.0',
   'test1','wsconn','client')
    
   HelloWorld_pt
   

3. View the list of available policies as described in "Displaying a List of the Available Policies Using WLST".

   To view only available client policies, set the subject argument to client. For example:

   listAvailableWebServicePolicies("","client")
   

4. To attach policies, do one of the following:

   • Use the attachWebServiceClientPolicy command to attach a single policy to a Web service client port.

     attachWebServiceClientPolicy(application, moduleOrCompName, moduleType,
     serviceRefName, portInfoName, policyURI, [subjectType=None]
     

     Set the arguments as follows:

     • 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:

     wls:/wls_domain/serverConfig> attachWebServiceClientPolicy("/wls_domain/AdminServer/application1#2.0",
     "test1","wsconn","client","HelloWorld_pt","oracle/wss_username_token_client_policy")
     

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

     attachWebServiceClientPolicies(application, moduleOrCompName, 
     moduleType, serviceRefName, portInfoName, policyURIs, [subjectType=None]
     

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

     wls:/wls_domain/serverConfig> attachWebServiceClientPolicies("/wls_domain/AdminServer/application1#2.0",
     "test1","wsconn","client","HelloWorld_pt",
     ["oracle/wss_username_token_client_policy","oracle/wsrm10_policy"])
     
     Please restart application to uptake the policy changes.
     

   Note:

   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.

   For additional information about validating policies, see "Validating Policy Subjects".

5. To detach policies, do one of the following:

   • Use the detachWebServiceClientPolicy command to detach a single policy from a Web service client port.

     detachWebServiceClientPolicy(application, moduleOrCompName, moduleType,
     serviceRefName, portInfoName, policyURI, [subjectType=None]
     

     Set the arguments as described in step 4 above.

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

     wls:/wls_domain/serverConfig> detachWebServiceClientPolicy("/wls_domain/AdminServer/application1#2.0",
     "test1","wsconn","client","HelloWorld_pt","oracle/wss_username_token_client_policy")
     

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

     detachWebServiceClientPolicies(application, moduleOrCompName, 
     moduleType, serviceRefName, portInfoName, policyURIs, [subjectType=None]]
     

     For example, to detach the policies oracle/wss_username_token_client_policy and oracle/wsrm10_policy from the HelloWorld_pt of the client service, use the following command:

     wls:/wls_domain/serverConfig> detachWebServiceClientPolicies("/wls_domain/AdminServer/application1#2.0",
     "test1","wsconn","client","HelloWorld_pt",
     ["oracle/wss_username_token_client_policy","oracle/wsrm10_policy"])
     
     Please restart application to uptake the policy changes.
     

6. For ADF DC and WebCenter client applications, restart the Web service client application. You do not need to restart a SOA composite.

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

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

Figure 8-7 Overriding a Configuration Property

Description of "Figure 8-7 Overriding a Configuration Property"

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

Note:

The procedures described in this section apply to Oracle Infrastructure Web services only.

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.

Configuring Server-Side Override Properties for Message Protection Policies

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

If you do not set these properties and leave the default blank values, the values you configure as part of setting up the keystore for message protection are used instead, as described in "Setting up the Keystore for Message Protection".

Table 8-1 Server-Side Configuration Properties for Message Protection Policies

Property Name	Default Value	Description
keystore.sig.csf.key	Blank	The alias and password used for storing the signature key password in the keystore. This property allows you to specify the signature key on a per-attachment level instead of at the domain level. (Applicable only to WSS10 message protection policies)
keystore.enc.csf.key	Blank	The alias and password used for storing the decryption key password in the keystore. This property allows you to specify the decryption key on a per-attachment level instead of at the domain level. (Applicable to WSS10 and WSS11 message protection synchronous policies)

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.

To set a value of a configuration property for a policy:

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

2. From the Web Services Policies page, select the message protection policy from the Policies table and click Edit.

3. On the Edit Policy page, click the Configurations tab.

4. Select the configuration property and click Edit to make the change to the keystore.sig.csf.key and keystore.enc.csf.key properties based on the keys in your keystore. See Figure 8-8.

   Figure 8-8 Server-Side Configuration Properties

   
   Description of "Figure 8-8 Server-Side Configuration Properties"
   
   

5. Validate your changes.

6. Click Save.

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

Figure 8-9 Overriding a Server-Side Configuration Property

Description of "Figure 8-9 Overriding a Server-Side Configuration Property"

The property is overridden on a per-attachment basis.

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.

For all other policies, keystore.sig.csf.key has the value you configure as part of setting up the keystore for message protection are used instead, as described in "Setting up the Keystore for Message Protection".

Configuring Server-Side Override Properties for Authorization Policies

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.

If you set (or then override) these properties, the new values are used in the attached Web service instead of the action and resource you configure as described in "How Authorization Permissions Are Determined".

Table 8-2 Server-Side Configuration Property for Authorization Policies

Property Name	Default Value	Description
action	*	Specify the operations for which this policy should be enforced.
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.

To set a value for the configuration property:

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

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

3. On the Edit Policy page, click the Configurations tab.

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

5. Validate your changes.

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

Note:

The procedures described in this section apply to Oracle Infrastructure Web services only.

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.

To add a user-defined configuration property:

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

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

3. On the Edit Policy page, click the Configurations tab.

4. Click Add. The Add New Configure Property dialog box shown in Figure 8-10 appears.

   Figure 8-10 Adding a New Configuration Property

   
   Description of "Figure 8-10 Adding a New Configuration Property"
   
   

5. Enter the following information and click OK.

   • Property Set is your name for the group (set) to which you want this property to belong. This is a required field.

   • Name is your name for the property. The name must be unique for this policy. This is a required field.

   • Description is your description for the property.

   • Value is the current String value for the property. This is a required field.

   • Default is the default String value for the property if it is not otherwise set.

   • Content Type can be one of Constant, Optional, or Required. You can subsequently override only properties of type Optional and Required.

6. Validate the policy.

7. Click Save.

Editing a User-Defined Configuration Property

You can edit a user-defined configuration property if you need to change it.

To edit a user-defined configuration property:

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

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

3. On the Edit Policy page, click the Configurations tab.

4. Select the user-defined configuration property you want to edit and click Edit.

5. Make any needed changes.

6. Validate the policy.

7. Click Save.

Deleting a User-Defined Configuration Property

You can delete a user-defined configuration property if you no longer need it.

To delete a user-defined configuration property:

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

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

3. On the Edit Policy page, click the Configurations tab.

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

5. Validate the policy.

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

To do this using Fusion Middleware Control, attach the policy as described in "Attaching a Policy to a Single Subject", "Attaching a Policy to Multiple Subjects (Bulk Attachment)", or "Attaching Policies to Web Service Clients" as appropriate.

Then, select the attached policy with the user-defined property. The Security Configuration Details portion of the page appears, as shown in Figure 8-11.

Figure 8-11 Overriding a User-Defined Configuration Property

Description of "Figure 8-11 Overriding a User-Defined Configuration Property"

Overriding Configuration Properties When Attaching a Policy Using WLST

Note:

This procedure applies to Oracle Infrastructure Web services only.

When you attach a policy that has an overridable property, you can override the existing value using the setWebServicePolicyOverride command. To do so, use the following procedure.

1. Attach the policy to the service as described in "Attaching a Policy to a Web Service Using WLST".

2. Use the setWebServicePolicyOverride command to override policy properties.

   setWebServicePolicyOverride(application,moduleOrCompName,moduleType,
   serviceName,portName,policyURI,properties)
   

   You can override the properties listed in Table 8-1 and Table 8-2, and user-defined properties as described in "Configuring User-Defined Client- or Server-Side Override Properties".

   For example, to override the ROLE property in the oracle/wss_username_token_service_policy policy, use the following command:

   wls:/wls-domain/serverConfig>setWebServicePolicyOverride
   ('/wls_domain/AdminServer/Jaxwsejb30ws','jaxwsejb',
   'web','WsdlConcreteService','WsdlConcretePort',
   "oracle/wss_username_token_service_policy",[("ROLE","ADMIN")])   
   

   Notes:

   If the policy that you specify is not attached to the port, an error message is displayed and/or an exception is thrown.

   If you set the properties argument to None, then all policy overrides are removed.

3. For ADF and WebCenter applications, restart the Web service application. You do not need to restart a SOA composite.

   Note:

   You need to wait approximately 30 seconds (or the equivalent of the configured Graceful Shutdown Timeout time) between stopping and restarting the application. During this time, the server is allowing all global transactions to complete before shutting down the application. If you do not wait the configured Graceful Shutdown Timeout time, then the application will not be restarted appropriately and you will not be able to access it. To avoid waiting the graceful shutdown timeout period, you can restart the application twice.

For more information about this WLST command and its arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.