Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.6.3)

Part Number E15866-08
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
PDF · Mobi · ePub

51 Using WS-Policy in Oracle Service Bus Proxy and Business Services

This chapter describes how to use Oracle WebLogic Server security policies (WLS 9 policies) in Oracle Service Bus.

Note:

This chapter applies only to WLS 9 policies and not Oracle Web Services Manager policies. In future releases of Oracle Service Bus, Oracle Web Services Manager policies will replace and enhance the functionality of WLS 9 security policies. While this version of Oracle Service Bus continues to support WLS 9 policies, you should consider using Oracle Web Services Manager policies for new service creation to prepare for the eventual deprecation of WLS 9 policy support.

To express the message-level security requirements for a proxy service or business service that is a Web service, you use the Web Services Policy (WS-Policy) framework.

The following sections describe configuring WS-Policy for proxy services and business services:

51.1 About Web Services Policy

Web Services Policy (WS-Policy) is a standards-based framework for defining a Web service's constraints and requirements. It expresses constraints and requirements in a collection of XML statements called policies, each of which contains one or more assertions.

In Oracle Service Bus, WS-Policy assertions are used to specify a Web service's requirements for digital signatures and encryption, along with the security algorithms and authentication mechanisms that it requires.

The WS-Policy framework allows other specifications to declare "policy assertions." These are domain-specific XML elements that appear inside a <policy> element. Policy assertions specifications describe the syntax and semantics of these domain-specific assertions.

WS-SecurityPolicy is one example of a domain-specific assertion language. The WS-SecurityPolicy specification defines a set of security policy assertions for use with the WS-Policy framework.

WS-ReliableMessaging is another example of a domain-specific assertion language; it defines assertions for declaring reliable-messaging policy.

51.1.1 Relationship Between WS-Security and WS-Policy

Web Services Security (WS-Security) works in conjunction with the Web Services Policy Framework (WS-Policy), and it is important that you understand what these terms mean and how they relate:

  • Web Services Security (WS-Security) is an OASIS standard that defines interoperable mechanisms to incorporate message-level security into SOAP messages. WS-Security determines "how" message-level security is incorporated into SOAP messages.

    WS-Security supports message integrity and message confidentiality. It also defines an extensible model for including security tokens in a SOAP envelope and a model for referencing security tokens from within a SOAP envelope. WS-Security allows you to specify which parts of a SOAP message are digitally signed or encrypted.

  • The Web Services Policy Framework (WS-Policy) provides a general-purpose model and corresponding syntax to describe and communicate the policies of a Web service. WS-Policy is an abstract XML framework. The interesting aspects of a WS-Policy are defined in child elements called policy "assertions."

  • WS-SecurityPolicy defines assertions for specifying the security aspects of a WS-Policy. WS-SecurityPolicy determines "what" message-level security is required of SOAP messages.

    The policies can determine which operations are secured and which security measures a Web services client must apply.

When you configure the WS-Policy of a proxy or business service, if the WS-Policy contains one or more security policy assertions, then the proxy service or business service is considered to be WS-Security enabled.

51.1.2 WS-Policies Can be Bound Directly to Service

As in prior releases of Oracle Service Bus, WS-Policy policies can be included directly in a WSDL document or included by reference, and a WSDL document may import other WSDL documents that contain or refer to WS-Policy policies. An XML file that contains these policies can be used by multiple proxy services or business services.

In addition, there is an alternative way to bind WS-Policy to services. The Policies page allows you to bind policies directly to a service. Policies can be bound to different scopes:

  • The entire service

  • A service operation

  • The request message of a service operation

  • The response message of a service operation

If a policy is bound to the entire service, it applies to all operations in the service and all request and response messages of all operations. If a policy is bound to an operation, the policy applies to the request and response message of that operation.

Any number of policies can be bound on any given scope.

For the purpose of example, assume there is a service S with operations A, B, C and D, where A, B and C are request/response operations and D is a request-only operation. An administrator can configure the following WS-Policy bindings:

  • Policy X bound to the entire service S,

  • Policies Y and Z on operation A

  • Policies Y and Z on operation B

  • Policy P on the request message of operation C

  • Policy Q on the response message of operation C

  • Policy R on the request message of operation D

In this example:

  • The effective policy of the request/response messages of operations A and B is the union of policies X, Y and Z.

  • The effective policy on the request message of operation C is the union of X and P. The effective policy on the response message of operation C is the union of X and Q.

  • The effective policy on the request message of operation D is the union of X and R.

51.1.3 Abstract and Concrete WS-Policy Statements

For security policy assertions written under the WS-Policy specification (using the proprietary Oracle schema for security policy), the WebLogic Web Services runtime environment recognizes two types of WS-Policy statements:

  • Concrete WS-Policy statements specify the security tokens that are used for authentication, encryption, and digital signatures. A concrete encryption policy always has the server's encryption certificate embedded in the form of a base-64 encoded certificate in an X.509 binary security token.

    You can create concrete WS-Policy statements if you know at design time the type of authentication (such as using X.509 or SAML tokens) that you want to require.

  • Abstract WS-Policy statements do not specify security tokens. Specifically, this means the <Identity> and <Integrity> elements (or assertions) of the WS-Policy files do not contain a <SupportedTokens><SecurityToken> child element, and the <Confidentiality> element WS-Policy file does not contain a <KeyInfo><SecurityToken> child element.

    The Oracle Service Bus runtime environment determines which security token types an abstract policy will accept.

51.2 Oracle Service Bus WS-Policy Files

Oracle Service Bus includes a set of out-of-the-box WS-Policy files that you can use. (The Oracle Service Bus policy files are a subset of the policy files that Oracle WebLogic Server provides.)

The policy statements are of three types:

The predefined policy files are described in the sections that follow.

51.2.1 Predefined Oracle Proprietary Policy Files

The following Oracle proprietary predefined policy files are available:

  • Auth.xml—contains a policy that requires Web service clients to authenticate. Oracle recommends that you do not use the Auth.xml policy file: use the Sign.xml and Encrypt.xml policies whenever possible.

  • Encrypt.xml—contains a policy that requires clients to encrypt the SOAP body with 3DES-CBC. The key wrapping algorithm is RSA 1.5. A symmetric key for Triple DES (Data Encryption Standard) is generated by the client and encrypted for the recipient with RSA 1.5.

    You cannot use this policy with a business service. Instead, create your own concrete encryption policy. See Section 51.3, "Creating and Using Custom WS-Policy Statements."

  • Sign.xml—contains a policy that requires clients to sign the SOAP body. It also requires that the WS-Security engine on the client add a signed timestamp to the wsse:Security header—which prevents certain replay attacks. All system headers are also signed. The digital signature algorithm is RSA-SHA1. Exclusive XML canonicalization is used.

    The system headers are:

    • wsrm:SequenceAcknowledgement

    • wsrm:AckRequested

    • wsrm:Sequence

    • wsa:Action

    • wsa:From

    • wsa:To

    • wsa:FaultTo

    • wsa:MessageID

    • wsa:RelatesTo

    • wsa:ReplyTo

    • wsu:Timestamp

    • wsax:SetCookie

    The name space prefixes correspond to the name spaces in the following table:

    Prefix Name Space

    wsrm

    http://schemas.xmlsoap.org/ws/2005/02/rm
    

    wsa

    http://schemas.xmlsoap.org/ws/2004/08/addressing
    

    wsu

    http://schemas.xmlsoap.org/ws/2002/07/utility
    

    wsax

    http://schemas.xmlsoap.org/ws/2004/01/addressingx
    

51.2.2 Predefined Reliable Messaging Policy Files

WebLogic Web Services use WS-Policy files to enable a destination endpoint to describe and advertise its Web Service reliable messaging capabilities and requirements. These WS-Policy files are XML files that describe features such as the version of the supported WS-ReliableMessaging specification, the source endpoint's retransmission interval, the destination endpoint's acknowledgment interval, and so on.

Oracle Service Bus includes two simple reliable messaging WS-Policy files that you can use (only with the WS-RM transport) if you do not want to create your own WS-Policy files:

  • DefaultReliability.xml—Specifies typical values for the reliable messaging policy assertions, such as inactivity timeout of 10 minutes, acknowledgement interval of 200 milliseconds, and base re-transmission interval of 3 seconds. See DefaultReliability.xml WS-Policy File for the actual WS-Policy file.

  • LongRunningReliability.xml—Similar to the preceding default reliable messaging WS-Policy file, except that it specifies a much longer activity timeout interval (24 hours.)

51.2.3 When to Use the Predefined Policy Files

Oracle recommends that you use these pre-packaged policies whenever possible. However, you cannot use them under the following conditions:

  • Use transport-level policies only where message-level security is not required.

  • If you need to specify that particular parts of the body of a SOAP message are encrypted or digitally signed, rather than the entire body, you cannot use the Oracle Service Bus WS-Policy statements.

    Instead, create custom WS-Policy statements. See Section 52.5.1, "Example: Encrypting Part of the SOAP Body and Header."

  • If you require clients to provide SAML tokens, you cannot use the Oracle Service Bus WS-Policy statements. WS-Policy statements that require SAML tokens must specify the confirmationMethod and therefore must be concrete.

  • If you want a business service to require encryption, you cannot use the Oracle Service Bus Encrypt.xml policy. Business services require concrete encryption policies (the certificate must be embedded in the policy).

For information on using these policies in your proxy services or business services, see Section 51.4, "Attaching WS-Policy Statements to WSDL Documents."

51.3 Creating and Using Custom WS-Policy Statements

If the Oracle Service Bus WS-Policy packaged policy files do not meet your security needs, you can write your own WS-Policy statements. You cannot modify the Oracle Service Bus WS-Policy statements.

You can write custom WS-Policy statements directly in your Web service's WSDL document. Or, if you want to reuse your statements in multiple Web services, write them in a separate XML file and then:

Note the following restrictions for WS-Policy statements in Oracle Service Bus:

51.4 Attaching WS-Policy Statements to WSDL Documents

Oracle Service Bus implements the WS-Policy Attachment specification (http://www.w3.org/Submission/WS-PolicyAttachment/), which defines the mechanisms for associating WS-Policy statements with Web services.

To attach WS-Policy statements to a WSDL document for a Web service:

  1. If you created a custom WS-Policy in a separate XML file, add the custom WS-Policy file as a resource in the Oracle Service Bus domain. See "Adding Custom WS-Policies" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

  2. In the <definitions> element of the WSDL document, add the following child element:

    <wsp:UsingPolicy
       wsdl:Required="true"
       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/> 
    

    The wsdl:required="true" attribute ensures that proxy services and business services are capable of processing the policy attachments.

    If you do not add this element, Oracle Service Bus ignores any WS-Policy statements in the WSDL.

  3. Within each element in the WSDL document that you want to secure:

    1. Determine the URI of the WS-Policy statements that you want to use. See Section 51.4.1, "Determining the URI of a WS-Policy Statement."

    2. Specify the URI in the WSDL document. See Section 51.4.2, "Specifying the URI of a WS-Policy Statement in a WSDL Document."

51.4.1 Determining the URI of a WS-Policy Statement

For the Oracle Service Bus WS-Policy statements, the URIs are always as follows:

  • policy:Auth.xml

  • policy:Encrypt.xml

  • policy:Sign.xml

For WS-Policy statements that are located directly in the WSDL document, the URI is as follows: #policy-ID where policy-ID is the value of the policy's wsu:ID attribute. See Example 51-2.

For WS-Policy statements that you created in a separate XML file and added as resources to Oracle Service Bus, the URI is as follows: policy:policy-ID where policy-ID is the value of the policy's wsu:ID attribute (which you specified in the policy's XML file).

You can also use UDDI to attach WS-Policy statements to a WSDL document, in which case the URI is expressed differently. For more information, see the WS-Policy Attachment specification (http://www.w3.org/Submission/WS-PolicyAttachment/).

51.4.2 Specifying the URI of a WS-Policy Statement in a WSDL Document

Use one of the following techniques to specify the URI in a WSDL document:

  • PolicyURIs attribute

    If the WSDL schema (described in http://www.w3.org/TR/wsdl) allows attribute extensibility for the element that you want secure, add the PolicyURIs global attribute to the element.

    For the value of this element, specify a list of URIs, each of which refers to a single policy.

    For example:

    <input message="tns:foo" wsp:PolicyURIs="policy:Sign.xml"/> 
    
  • Nested <Policy> element

    If the WSDL schema allows element extensibility for the element that you want to secure, add <Policy> as a global child element. For each WS-Policy that you want to use, add one <PolicyReference> element as a child of the <Policy> element.

    For each <PolicyReference> element, include a URI attribute that refers to a single policy. You can also include a digest and digest algorithm in the element.

    For example:

    <wsp:Policy>
       <wsp:PolicyReference URI="policy:Sign.xml"/> 
    </wsp:Policy> 
    

Table 51-1 lists the XPath name of WSDL elements and the technique that you use to specify the URI of the WS-Policy statement. The table also indicates the WSDL elements for which Oracle Service Bus does not support the attachment of WS-Policy statements.

Table 51-1 WSDL Elements That Can Be Protected in Oracle Service Bus

To Attach a Policy to This WSDL Element... Use This Technique...
/definitions/message 

Nested <Policy> element

/definitions/message/part 

PolicyURIs attribute

/definitions/portType 

PolicyURIs attribute

/definitions/portType/operation 

Nested <Policy> element

/definitions/portType/operation/input 

PolicyURIs attribute

/definitions/portType/operation/output 

PolicyURIs attribute

/definitions/portType/operation/fault 

Oracle Service Bus does not support attaching WS-Policy statements to this element

/definitions/binding 

Nested <Policy> element

/definitions/binding/operation 

Nested <Policy> element

/definitions/binding/operation/input 

Nested <Policy> element

/definitions/binding/operation/output 

Nested <Policy> element

/definitions/binding/operation/fault 

Oracle Service Bus does not support attaching WS-Policy statements to this element

/definitions/binding/service 

Oracle Service Bus does not support attaching WS-Policy statements to this element

/definitions/service/port 

Nested <Policy> element


51.4.3 Best Practices: Attaching WS-Policy Statements

Oracle recommends that you attach WS-Policy statements to any of the following elements or its descendants:

  • portType

  • binding

Oracle recommends that you do not attach WS-Policy statements to the following elements:

  • service

  • port

  • message or message/part

51.4.4 Example: Requiring X.509 Credentials for Identity and Confidentiality

If a WS-Policy statement requires an X.509 token for authentication, it must also require a digital signature. An X.509 token cannot satisfy an identity assertion unless the client also signs some content with the corresponding private key.

To create a proxy service that requires clients to use X.509 certificates for authentication and digital signatures, you can do the following:

  1. In the WSDL document that you will use to create a proxy service, attach the Oracle Service Bus policies that are in the Sign.xml and Auth.xml files. See Example 51-1.

  2. Configure the proxy service to use a service key provider that contains an X.509 certificate for digital signatures. See "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Because the Oracle Service Bus Sign.xml and Auth.xml policies are abstract, they will require the client to provide the credentials that are specified in the service key provider that is associated with the proxy service.

Example 51-1 shows a WSDL with references to the Oracle Service Bus Sign.xml and Auth.xml policies.

Example 51-1 WSDL with Policy References to Oracle Service Bus WS-Policies

<definitions
   ...
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401
      -wss-wssecurity-utility-1.0.xsd">
   <wsp:UsingPolicy
      wsdl:Required="true"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/> 
   ...
   <portType name="Sample">
      <operation name="doFoo" parameterOrder="data">
         <input message="tns:foo" wsp:PolicyURIs="policy:Sign.xml"/>
         <output message="tns:fooResponse"/>
      </operation>
   </portType>
   <binding name="SampleBinding" type="tns:Sample">
      <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="doFoo">
        <wsp:Policy>
            <wsp:PolicyReference URI="policy:Sign.xml"/>
            <wsp:PolicyReference URI="policy:Auth.xml"/>
         </wsp:Policy>
         ...
      </operation>
      </binding>
   ...
</definitions>

51.4.5 Example: Attaching Custom Inline WS-Policy Statements to a WSDL Document

Example 51-2 shows a WSDL with two custom WS-Policy policies, wsu:Id="policy1" and wsu:Id="policy2". The policies are located in the WSDL document; therefore the URIs that refer to these polices use XML fragments.

Example 51-2 WSDL with Policy References to a Custom Inline Policy

<definitions
   ...
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-
   200401-wss-wssecurity-utility-1.0.xsd">
   <wsp:UsingPolicy
      wsdl:Required="true"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/>
<wsp:Policy wsu:Id="policy1">...</wsp:Policy>
<wsp:Policy wsu:Id="policy2">...</wsp:Policy>
...
   <portType name="Sample">
      <operation name="doFoo" parameterOrder="data">
         <input message="tns:foo" wsp:PolicyURIs="#policy1"/> 
         <output message="tns:fooResponse"/>
      </operation>
   </portType>
   <binding name="SampleBinding" type="tns:Sample">
      <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="doFoo">
         <wsp:Policy>
            <wsp:PolicyReference URI="#policy2"/>
         </wsp:Policy>
         <soap:operation
            soapAction="http://com.bea.samples/sample/doFoo"
            style="document"/>
         <input>
            <soap:body namespace="http://com.bea.samples/sample"
               use="literal"/>
         </input>
         <output>
            <soap:body namespace="http://com.bea.samples/sample"
              use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>

51.5 Oracle-Proprietary Security Policy Best Practices

This section describes best practices you should follow when using security policy assertions written under the WS-Policy specification, using the proprietary Oracle schema for security policy.

Note:

Carefully analyze your security requirements before you design your WS-SecurityPolicy. These best practices may or may not apply to your specific business security needs.

51.6 Policy Subjects and Effective Policy

A policy subject is an entity, such as service, endpoint, operation, or message, with which a policy can be associated. You can associate a single WS-Policy statement with multiple policy subjects; conversely, multiple WS-Policy statements can be associated with a single policy subject. A policy scope is the collection of policy subjects to which a policy applies. For example, the policy scope implied by a policy attached to wsd:binding/wsdl:operation/wsdl:input is the input message, the operation, the endpoint, and the service.

The effective policy for a given policy subject is the merge of all policies whose scopes contain that policy subject. For example, the effective policy of the input message of a binding operation is the merge of all policies attached to the following:

The Oracle Service Bus Administration Console displays the effective policy (read only) when configuring a business or proxy service with WS-Policy statements.