Note:
This chapter applies only to WLS 9.2 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.2 security policies. While this version of Oracle Service Bus continues to support WLS 9.2 policies, you should consider using Oracle Web Services Manager policies for new service creation to prepare for the eventual deprecation of WLS 9.2 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.
This chapter describes conceptual information that you will need in the next chapter, Chapter 53, "Configuring Message-Level Security for Web Services."
The following sections describe configuring WS-Policy for proxy services and business services:
Section 52.3, "Creating and Using Custom WS-Policy Statements"
Section 52.4, "Attaching WS-Policy Statements to WSDL Documents"
Section 52.5, "Oracle-Proprietary Security Policy Best Practices"
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.
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.
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.
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.
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:
WS-Security Policy assertions
Oracle security policy assertions
Reliable-messaging assertions
The predefined policy files are described in the sections that follow.
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 52.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 |
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.)
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 53.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 52.4, "Attaching WS-Policy Statements to WSDL Documents."
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:
Import them to Oracle Service Bus and refer to them from the WSDL documents.
Directly bind them to a service
Note the following restrictions for WS-Policy statements in Oracle Service Bus:
Security policy files written under the WS-Policy specification using the proprietary Oracle schema for security policy are required to have an Id attribute from the following name space: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd
The value of this attribute must be unique across all WS-Policy statements in the Oracle Service Bus domain. This attribute is optional in the WS-Policy schema but required in an Oracle Service Bus Web service.
If you create a confidentiality assertion in a proxy service, it must be abstract (the certificate must not be embedded in the policy). You will get error messages while creating a proxy service that contains a concrete confidentiality assertion.
If you create a confidentiality assertion in a business service, it must be concrete (the certificate must be embedded in the policy) and it must be located directly in the WSDL document. You cannot attach such a policy by reference. See Section 53.5.1, "Example: Encrypting Part of the SOAP Body and Header."
When naming WS-Policy resources, follow the Section 2.1.1, "Resource Naming Restrictions."
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:
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.
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.
Within each element in the WSDL document that you want to secure:
Determine the URI of the WS-Policy statements that you want to use. See Section 52.4.1, "Determining the URI of a WS-Policy Statement."
Specify the URI in the WSDL document. See Section 52.4.2, "Specifying the URI of a WS-Policy Statement in a WSDL Document."
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 52-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/).
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 52-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 52-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 |
/definitions/message/part |
|
/definitions/portType |
|
/definitions/portType/operation |
Nested |
/definitions/portType/operation/input |
|
/definitions/portType/operation/output |
|
/definitions/portType/operation/fault |
Oracle Service Bus does not support attaching WS-Policy statements to this element |
/definitions/binding |
Nested |
/definitions/binding/operation |
Nested |
/definitions/binding/operation/input |
Nested |
/definitions/binding/operation/output |
Nested |
/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 |
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
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:
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 52-1.
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 52-1 shows a WSDL with references to the Oracle Service Bus Sign.xml and Auth.xml policies.
Example 52-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>
Example 52-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 52-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>
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.Make sure you do not use Identity assertions on an operation's response policy. As a corollary, do not use the predefined Auth.xml policy in a response policy.
When using WS-Security username tokens on inbound to an active intermediary proxy service, if you want to pass the username/password to a back-end service (username/password pass-through), the username token must include the password in clear-text.
Whenever using WS-Security username tokens with clear-text passwords, it is strongly recommended that you protect the confidentiality of the username token, either by encrypting the entire token (with WS-Security) or by sending the message over SSL.
Whenever using an Identity assertion, you may also want to use an Integrity assertion to digitally sign the authentication token (username, X.509 or SAML token) together with sensitive message content (SOAP body and/or SOAP header parts). The digital signature protects the integrity of the signed content and binds together the authentication token and message content. This is important to prevent someone from copying the authentication token into an arbitrary SOAP envelope, thus forging a message. (You can also send the message over SSL instead of using an integrity assertion.)
When using an Integrity assertion, you should also use a MessageAge assertion. You should also include the signing token (that is, the verification certificate) in the wsse:Security header and that the digital signature covers the signing token and the timestamp, in addition to whatever SOAP body and/or SOAP header parts you wish to sign. The message age assertion guarantees a timestamp will be included in the security header. The timestamp is used to prevent some replay attacks. The predefined Sign.xml policy follows this best practice.
When using timestamps over JMS (MessageAge assertions), make sure you set the age of the MessageAge assertion appropriately. If the value is too low, the message may expire while on the queue.
Whenever an Identity assertion includes X.509 tokens in the supported token list, your policy must also have an Integrity assertion. The server will not accept X.509 tokens as proof of authentication unless the token is also used in a digital signature.
If the Identity assertion accepts other token types, you may use the X509AuthConditional attribute of the Integrity assertion to specify that the digital signature is required only when the actual authentication token is an X.509 token. Remember that abstract Identity assertions are pre-processed at deploy time and converted into concrete assertions by inserting a list of all token types supported by your runtime environment.
Oracle recommends that you do not use abstract Identity assertions in your policy. It is preferable instead to directly specify exactly which token types are supported for authentication. Furthermore, Oracle recommends that your Identity assertion supports only one token type.
Note:
This makes the X509AuthConditional attribute of Integrity assertions unnecessary, as there is no ambiguity as to which token types are supported.As a corollary, Oracle recommends that you do not use the Auth.xml policy file: use the Sign.xml and Encrypt.xml policies whenever possible.
Whenever an Oracle Service Bus proxy processes digital signatures (on inbound request messages or back-end response messages), it is strongly recommended that you configure a certificate registry in your security realm and import your trading partner certificates in the registry.
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 input message of the binding operation
The binding operation
The binding
The input message of the port-type operation
The port-type operation
The port-type
The service
The Oracle Service Bus Administration Console displays the effective policy (read only) when configuring a business or proxy service with WS-Policy statements.