Skip Headers
Oracle® Fusion Middleware Security and Administrator's Guide for Web Services
11g Release 1 (11.1.1)

Part Number B32511-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

8 Attaching Policies to Web Services

This chapter includes the following sections:

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 endpoints if they are not already displayed.

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

  4. Click the OWSM Policies tab.

    Figure 8-1shows the screen display for an Oracle Infrastructure Web service endpoint that has both a globally attached and a directly attached policy. Only policies in effect for the endpoint are displayed. For details about effective policies for an endpoint, see "Calculating the Effective Set of Policies".

    Figure 8-1 Policies Attached to an Oracle Infrastructure Web Service Endpoint

    Description of Figure 8-1 follows
    Description of "Figure 8-1 Policies Attached to an Oracle Infrastructure Web Service Endpoint"

    Figure 8-2 shows the screen display for a WebLogic Java EE endpoint. Only policies that are directly attached to an endpoint are displayed. Globally attached policies are not available.

    Figure 8-2 Policies Attached to a WebLogic Java EE Web Service Endpoint

    Description of Figure 8-2 follows
    Description of "Figure 8-2 Policies Attached to a WebLogic Java EE Web Service Endpoint"

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
    security : oracle/wss_username_token_service_policy, enabled=true
    Attached policy or policies are valid; endpoint is secure.
    

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 SOA, ADF, and WebCenter services in a cluster. When using SOA, ADF, and WebCenter services in a cluster, you must attach and/or detach policies to each instance of the cluster. This issue does not apply to WebLogic Java EE Web services and SOA composite services.

Attaching a Policy to a Web Service Using Fusion Middleware Control

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

Note:

For WebLogic Java EE 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 Java EE 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 endpoints, if they are not already displayed.

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

  4. Click the OWSM Policies tab.

    The policies that are already globally and directly attached to the endpoint are displayed as shown in Figure 8-1.

  5. Click Attach/Detach.

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

    Figure 8-3 Attaching Policies to a Web Service

    Description of Figure 8-3 follows
    Description of "Figure 8-3 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-4. Click OK when you are finished reviewing the details of the policy.

    Figure 8-4 Viewing Details about a Policy

    Description of Figure 8-4 follows
    Description of "Figure 8-4 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 OWSM Policies tab.

    Note:

    If you directly attach a policy that contains an assertion with the same category as a policy that is attached globally using a policy set, the globally attached policy is overridden by the directly attached policy. In this case, the globally attached policy is no longer in effect, and is not displayed in the list of policies attached to the endpoint. For more information about effective policies, see "Calculating the Effective Set of Policies".
  11. For ADF and WebCenter applications, restart the Web service application. You do not need to restart a SOA composite or a WebLogic Java EE 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 SOA, ADF, and WebCenter services in a cluster. When using SOA, ADF, and WebCenter services in a cluster, you must attach and/or detach policies to each instance of the cluster. This issue does not apply to WebLogic Java EE Web services and SOA composite services.

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

    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-5 Select Subjects Page

    Description of Figure 8-5 follows
    Description of "Figure 8-5 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-6. 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 Java EE 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-6 Select Policies Page

    Description of Figure 8-6 follows
    Description of "Figure 8-6 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-7.

    Figure 8-7 Attachment Summary Page

    Description of Figure 8-7 follows
    Description of "Figure 8-7 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 Java EE 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:

Note:

When you view a policy, only the major category, such as security, is displayed. To see the subtype (such as authorization), see the Assertion Details section of the assertion template on which the policy is based.

The run time automatically enforce STS-Trust configuration policies first and authorization policies last

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 Java EE 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. Select the Policies tab.

  3. In the Directly Attached Policies section of the page, click Attach/Detach.

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

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

  6. Click OK.

Attaching Policies to Connection-Based Web Service Clients

The following procedure describes how to attach policies to a connection-based Web service client such as an ADF DC Web service client, ADF JAX-WS Indirection Proxy, or WebCenter 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 a connection-based 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 OWSM Policies tab.

  6. In the Directly Attached Policies section of the page, 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. On 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, connection-based Web service clients (such as an ADF DC Web service client, ADF JAX-WS Indirection Proxy, or WebCenter client), 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 a connection-based Web service client such as an ADF DC Web service client, ADF JAX-WS Indirection Proxy, 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 that you can override, select the policy, then supply a value for the property in the Security Configuration Details section of the OWSM Policies page, as shown in Figure 8-8.

Figure 8-8 Overriding a Client Configuration Property

Description of Figure 8-8 follows
Description of "Figure 8-8 Overriding a Client Configuration Property"

In Web service client policies, you can override only the properties defined in the following table.

Table 8-1 Overridable Properties in Web Service Client Policies

Property Notes

attesting.mapping.attribute

Optional, does not have to be set.

caller.principal.name

Client's principal name as generated using the ktpass command and mapped to the username for which the kerberos token should be generated. Use the following format: <username>@<REALM NAME>.

Note: keytab.location and caller.principal.name are required for propagating client identity for J2EE applications.

csf-key

Must be set on policy Configuration page or overridden.

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.

keystore.recipient.alias

Can be set on policy Configuration page or overridden. Superseded by the Service Identity Certification Extension feature, as described in "Using Service Identity Certification Extension". If the certificate is published in the WSDL, then the client override property value is ignored.

keystore.sig.csf.key

Optional, does not have to be set.

keytab.location

Location of the client's keytab file.

Note: keytab.location and caller.principal.name are required for propagating client identity for J2EE applications.

on.behalf.of

Optional, does not have to be set. Used only when sts_trust_config_client_policy is attached to a client Web service.

saml.assertion.filename

Optional, does not have to be set.

saml.audience.uri

Optional, does not have to be set.

saml.enveloped.signature.required

Optional, does not have to be set. Default value is true.

saml.issuer.name

Optional, does not have to be set.

service.principal.name

Must be set on policy Configuration page or overridden.

Principal name for the Web service that needs to be protected, using the format <host>/<machine name>@<REALM NAME>. For example, HTTP/mymachine@MYREALM.COM.

subject.precedence

Optional, does not have to be set.

Note: For the wss11_saml_token_identity_switch_with_message_protection_client_policy policy, subject.precedence is required and set to false to allow for the use of a client-specified username rather than the authenticated subject. For all other SAML policies, subject.precedence is set to true and you can override it.

Applications from which Oracle WSM accepts the externally-supplied identity must have the WSIdentityPermission permission. This is to avoid potentially rogue applications from providing an identity to Oracle WSM.

See "Configuring SAML Web Service Clients for Identity Switching" for information about how to use subject.precedence. In particular, you need to "Set the javax.xml.ws.security.auth.username Property", and "Set the WSIdentityPermission Permission".

sts.auth.on.behalf.of.csf.key

Optional, does not have to be set. Used only when sts_trust_config_client_policy is attached to a client Web service.

sts.auth.user.csf.key

One or both of sts.auth.user.csf.key or sts.auth.x509.csf.key must be set, based on the STS configuration policy. Used only when sts_trust_config_client_policy is attached to a client Web service.

sts.auth.x509.csf.key

One or both of sts.auth.user.csf.key or sts.auth.x509.csf.key must be set, based on the STS configuration policy. Used only when sts_trust_config_client_policy is attached to a client Web service.

sts.keystore.recipient.alias

Must be set on policy Configuration page or overridden. Used only when sts_trust_config_client_policy is attached to a client Web service.

user.attributes

Optional, does not have to be set.

user.roles.include

Optional, does not have to be set.


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: properties that are included in the predefined policies and user-defined properties.

Configuring Server-Side Override Properties for Message Protection Policies

This release of Oracle WSM includes the server-side override properties shown in Table 8-2 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-2 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)

saml.enveloped.signature.required

True

Set to false (in both client and service policy) to have the bearer token be unsigned.

By default (true), the bearer token is signed using the domain signature key. You can override this by using the keystore.sig.csf.key property in the bearer client policy.


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

    Figure 8-9 Server-Side Configuration Properties

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

  5. Validate your changes.

  6. Click Save.

Configuring Server-Side Override Properties for Authorization Policies

This release of Oracle WSM includes the server-side override properties shown in Table 8-3 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-3 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.

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 follows
    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 User-Defined Policy

Attach the user-defined 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.

When you attach a policy that has a user-defined configuration property, you can override the existing value as follows:

Overriding Configuration Properties When Attaching a Service Policy

After you attach a policy that includes a server-side overridable configuration property, you can then override the existing value. In WLST, you do so using the setWebServicePolicyOverride command as described in "Overriding Configuration Properties When Attaching a Policy Using WLST".

To override a configuration property using Fusion Middleware Control:

  1. Select the attached policy with the overridable configuration property.

    The Override Policy Configuration button is displayed as shown in Figure 8-11.

    Note:

    The Override Policy Configuration button is displayed only when the selected policy contains configuration properties that can be overridden.

    Figure 8-11 Override Policy Configuration Button

    Description of Figure 8-11 follows
    Description of "Figure 8-11 Override Policy Configuration Button"

  2. Select Override Policy Configuration.

    The Security Configuration Details window is displayed, as shown in Figure 8-12. This figure shows the overridable properties for the oracle/wss10_message_protection_service_policy.

    Figure 8-12 Overriding a Policy Configuration Property

    Description of Figure 8-12 follows
    Description of "Figure 8-12 Overriding a Policy Configuration Property"

  3. Enter the override value in the Value field for the property and click Apply.

    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 and that it is still blank. If Web service A attaches the oracle/wss10_message_protection_service_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 attached to Web service A.

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

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-2 and Table 8-3, 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.