|
|
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, Configuring Message-Level Security for Web Services.
The following sections describe configuring WS-Policy for proxy services and business services:
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 AquaLogic 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:
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 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.
Previous releases of ALSB, released before the formulation of the WS-SecurityPolicy 1.2 specification, used security policy assertions written under the WS-Policy specification, using a proprietary BEA schema for security policy. As of release 3.0, ALSB has limited support for policies that conform to the WS-SecurityPolicy 1.2 specification (for the WS transport only), and the files written under the BEA web services security policy schema first included in WebLogic Server 9.
The WebLogic Server-proprietary format is based on the assertions described in the December 18, 2002 version of the Web Services Security Policy Language (WS-SecurityPolicy) specification. The syntax and usage of these AquaLogic Service Bus security assertions differ from the WS-Policy specification, but the assertions are similar in meaning and are fully compatible with security assertions used in WebLogic Server 9.0 and 9.1 Web services.
| WARNING: | WS-SecurityPolicy 1.2 policy files and BEA proprietary Web Services security policy schema files are not mutually compatible; you cannot define both types of policy file in the same Web Service. This is true whether the policies are attached to the WSDL or bound directly to the service. |
| WARNING: | ALSB service validation enforces this rule and a conflict is generated if a service has a mix of these two types of WS-SecurityPolicy. |
As in prior releases of ALSB, 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, as of ALSB 3.0 there is an alternative way to bind WS-Policy to services. The new Policies console page allows you to bind policies directly to a service. Policies can be bound to different scopes:
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:
For security policy assertions written under the WS-Policy specification (using the proprietary BEA schema for security policy), the WebLogic Web Services runtime environment recognizes two types of WS-Policy statements:
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.
<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 AquaLogic Service Bus runtime environment determines which security token types an abstract policy will accept.
AquaLogic Service Bus includes a set of out-of-the-box WS-Policy files that you can use. (The AquaLogic Service Bus policy files are a subset of the policy files that WebLogic Server provides.) To see the contents of these XML files, see BEA Web Services Security Policy Files.
The policy statements are of three types:
The predefined policy files are described in the sections that follow.
As a general rule, ALSB 3.0 does not support WS-Security Policy (WSSP) 1.2 assertions. The exception to this rule is the WS transport. The WS transport endpoints can have WSSP 1.2 policies, but only if they contain transport-level assertions only. WSSP 1.2 policies with message-level encryption or digital signature assertions are not allowed in ALSB 3.0.
The following WS-SecurityPolicy 1.2 predefined transport-level policy files are available:
Wssp1.2-Https-BasicAuth.xml — One way SSL with Basic Authentication. A 401 challenge occurs if the Authorization header is not present in the request. Wssp1.2-Https-ClientCertReq.xml — Two way SSL. The recipient checks for the initiator's public certificate. Note that the client certificate can be used for authentication. Wssp1.2-Https.xml — One way SSL. The following BEA proprietary predefined policy files are available:
Auth.xml—contains a policy that requires Web service clients to authenticate. BEA 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 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. As described in Use of WS-Policy Files for Web Service Reliable Messaging Configuration, 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.
ALSB 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 retransmisstion 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.)
See LongRunningReliability.xml WS-Policy File for the actual WS-Policy file. BEA recommends that you use these pre-packaged policies whenever possible. However, you cannot use them under the following conditions:
confirmationMethod and therefore must be concrete. For information on using these policies in your proxy services or business services, see Attaching WS-Policy Statements to WSDL Documents.
If the AquaLogic 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 AquaLogic 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 AquaLogic Service Bus:
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 AquaLogic Service Bus domain. This attribute is optional in the WS-Policy schema but required in an AquaLogic Service Bus Web service.
| Note: | As a general rule, ALSB 3.0 does not support WS-Security Policy (WSSP) 1.2 assertions. The exception to this rule is the WS transport. |
For WS-SecurityPolicy 1.2 policy statements, your custom policy file needs to comply with the standard format and assertions defined in WS-SecurityPolicy 1.2. Note, however, that release 10.0 of WebLogic Server (used with version 3.0 of ALSB) does not completely implement WS-SecurityPolicy 1.2. For more information, see
Unsupported WS-SecurityPolicy 1.2 Assertions. The root element of your WS-SecurityPolicy file must be <Policy> and include the following namespace declarations:
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512"
>
You can also use the pre-packaged WS-SecurityPolicy files as templates to create your own custom files. See Using WS-SecurityPolicy 1.2 Policy Files.
AquaLogic 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:
<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, AquaLogic Service Bus ignores any WS-Policy statements in the WSDL.
For the AquaLogic Service Bus WS-Policy statements, the URIs are always as follows:
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 Listing 6-2.
For WS-Policy statements that you created in a separate XML file and added as resources to AquaLogic 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"/>
<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 6-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 AquaLogic Service Bus does not support the attachment of WS-Policy statements.
BEA recommends that you attach WS-Policy statements to any of the following elements or its descendants:
BEA recommends that you do not attach WS-Policy statements to the following elements:
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:
Sign.xml and Auth.xml files. See Listing 6-1.
Because the AquaLogic 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.
Listing 6-1 shows a WSDL with references to the AquaLogic 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>
Listing 6-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>
This section describes best practices you should follow when using security policy assertions written under the WS-Policy specification, using the proprietary BEA 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. |
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.
Sign.xml policy follows this best practice. 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.
| 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, BEA recommends that you do not use the Auth.xml policy file: use the Sign.xml and Encrypt.xml policies whenever possible.
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 AquaLogic Service Bus Console displays the effective policy (read only) when configuring a business or proxy service with WS-Policy statements, as shown in the following figure.
|