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

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

/definitions/message 

/definitions/message/part 

/definitions/portType 

/definitions/portType/operation 

/definitions/portType/operation/input 

/definitions/portType/operation/output 

/definitions/portType/operation/fault 

/definitions/binding 

/definitions/binding/operation 

/definitions/binding/operation/input 

/definitions/binding/operation/output 

/definitions/binding/operation/fault 

/definitions/binding/service 

/definitions/service/port 

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.

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

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