Programming Web Services for WebLogic Server
You use WS-Policy files to configure the messgae-level security of a WebLogic Web Service. Use the
@Policies JWS annotations in the JWS file that implements the Web Service to specify the name of the WS-Policy file that is associated with a WebLogic Web Service.
A WS-Policy file is an XML file that conforms to the WS-Policy specification. The root element of a WS-Policy file is always
<wsp:Policy>. To configure message-level security, you add policy assertions that specify the type of tokens supported for authentication and how the SOAP messages should be encrypted and digitally signed.
Note: These security policy assertions are based on the assertions described in the December 18, 2002 version of the Web Services Security Policy Language (WS-SecurityPolicy) specification. This means that although the exact syntax and usage of the assertions in WebLogic Server are different, they are similar in meaning to those described in the specification. The assertions in this release of WebLogic Server are not based on the latest update of the specification (13 July 2005.)
WebLogic Server includes three WS-Policy files (
Encrypt.xml) that contain typical security assertions that you can use if you do not want to create your own WS-Policy file. For details about these files, see Using WS-Policy Files for Message-Level Security Configuration.
See Configuring Message-Level Security (Digital Signatures and Encryption) for task-oriented information about creating a message-level secured WebLogic Web Service.
Note: The WebLogic Web Services security runtime does not support specifing an InclusiveNamespaces PrefixList that contains a list of namespace prefixes or a token indicating the presence of the default namespace to the canonicalization algorithm.
>child element to specify whether you want the SOAP messages to use password digests.
>child element to specify the type of SAML confirmation (
Specifies the type of confirmation method that is used when using SAML tokens for identity. You must specify one of the following two values for this element:
holder-of-key. For example:
<ConfirmationMethod> assertion within an
<Integrity> assertion. The reason you put the SAML token in the
<Integrity> assertion for this confirmation method is that the Web Service runtime must prove the integrity of the message, which is not required by
For more information about the two SAML confirmation methods (
holder-of-key), see SAML Token Profile Support in WebLogic Web Services.
Specifies the digest algorithm that is used when digitally signing the specified parts of a SOAP message. Use the <MessageParts> sibling element to specify the parts of the SOAP message you want to digitally sign.
Specifies the encryption algorithm that is used when encrypting the specified parts of a SOAP message. Use the <MessageParts> sibling element to specify the parts of the SOAP message you want to digitally sign.
When you include this security assertion in your WS-Policy file, the Web Services runtime adds a
<Timestamp> header to the request or response SOAP message, depending on the direction (inbound, outbound, or both) to which the WS-Policy file is associated. The
<Timestamp> header indicates to the recipient of the SOAP message when the message expires.
The Web Services runtime, when generating the SOAP message, sets the
<Created> header to the time when the SOAP message was created and the
<Expires> header to the creation time plus the value of the
Age attribute of the
You typically never need to change the values of the preceding timestamp properties. However, if you do need to, you must use the Administration Console to create the
default_wss Web Service Security Configuration, if it does not already exist, and then update its timestamp configuration by clicking on the Timestamp tab. See Create a Web Service security configuration for task information and Domains: Web Services Security: Timestamp for additional reference information about these timestamp properties.
Specifies the parts of the SOAP message that should be signed or encrypted, depending on the grand-parent of the element. You can use either an XPath 1.0 expression or a set of pre-defined functions within this assertion to specify the parts of the SOAP message.
MessageParts assertion is always a child of a
Target assertion. The
Target assertion can be a child of either an
Integrity assertion (to specify how the SOAP message is digitally signed) or a
Confidentiality assertion (to specify how the SOAP messages are encrypted.)
See Using MessageParts To Specify Parts of the SOAP Messages that Must Be Encrypted or Signed for detailed information about using this assertion, along with a variety of examples.
See Using MessageParts To Specify Parts of the SOAP Messages that Must Be Encrypted or Signed for examples of using these dialects.
For example, if this element is defined in the
<Identity> parent element, then is specifies that a client application, when invoking the Web Service, must attach a security token to the SOAP request. For example, a Web Service might require that the client application present a SAML authorization token issued by a trusted authorization authority for the Web Service to be able to access sensitive data. If this element is part of
<Confidentiality>, then it specifies the token used for encryption.
You should never include this security assertion in your custom WS-Policy file; it is described in this section for informational purposes only. The WebLogic Web Services runtime automatically inserts this security assertion in the WS-Policy file that is published in the dynamic WSDL of the deployed Web Service. The security assertion specifies WebLogic Server's public key; the client application that invokes the Web Service then uses it to encrypt the parts of the SOAP message specified by the WS-Policy file. The Web Services runtime then uses the server's private key to decrypt the message.
The child elements also depend on the parent element; for example, when used in
<Integrity>, you can specify the
<MessageParts> child elements. When used in
<Confidentiality>, you can specify the
<MessageParts> child elements.
For detailed information about these transform algorithms, see XML-Signature Syntax and Processing.
When you use either the
Confidentiality assertion in your WS-Policy file, you are required to also use the
Target child assertion to specify the targets of the SOAP message to digitally sign or encrypt. The
Target assertion in turn requires that you use the
MessageParts child assertion to specify the actual parts of the SOAP message that should be digitally signed or encrypted. This section describes various ways to use the
See Example of a Policy File With Security Elements for an example of a complete WS-Policy file that uses the
MessageParts assertion within a
Confidentiality assertion. The example shows how to specify that the entire body, as well as the
Assertion security header, of the SOAP messages should be encrypted.
Be sure that you specify a message part that actually exists in the SOAP messages that result from a client invoke of a message-secured Web Service. If the Web Services security runtime encounters an inbound SOAP message that does not include a part that the WS-Policy file indicates should be signed or encrypted, then the Web Services security runtime returns an error and the invoke fails. The only exception is if you use the WebLogic-specific
wls:SystemHeader() function to specify that any WebLogic-specific SOAP header in a SOAP message should be signed or encrypted; if the Web Services security runtime does not find any of these headers in the SOAP message, the runtime simply continues with the invoke and does not return an error.
This dialect enables you to use an XPath 1.0 expression to specify the part of the SOAP message that should be signed or encrypted. The value of the
Dialect attribute to enable this dialect is
You typically want to specify that the parts of a SOAP message that should be encrypted or digitally signed are child elements of either the
soap:Header elements. For this reason, BEA provides the following two functions that take as parameters an XPath expression:
)—Specifies that the root element from which the XPath expression starts searching is
)—Specifies that the root element from which the XPath expression starts searching is
You can also use a plain XPath expression as the content of the
MessageParts assertion, without one of the preceding functions. In this case, the root element from which the XPath expression starts searching is
The following example specifies that the
AddInt part, with namespace prefix
n1 and located in the SOAP message body, should be signed or encrypted, depending on whether the parent
Target parent is a child of
The preceding example shows that you should define the namespace of a part specified in the XPath expression (
n1 in the example) as an attribute to the
MessageParts assertion, if you have not already defined the namespace elsewhere in the WS-Policy file.
Note: It is beyond the scope of this document to describe how to create XPath expressions. For detailed information, see the XML Path Language (XPath), Version 1.0, specification.
The XPath dialect described in XPath 1.0 is flexible enough for you to pinpoint any part of the SOAP message that should be encrypted or signed. However, sometimes you might just want to specify that the entire SOAP message body be signed or encrypted. In this case using an XPath expression is unduly complicated, so BEA recommends you use the dialect that pre-defines the
wsp:Body() function for just this purpose, as shown in the following example:
BEA provides its own dialect that pre-defines a set of functions to easily specify that some or all of the WebLogic security or system headers should be signed or encrypted. Although you can achieve the same goal using the XPath dialect, it is much simpler to use this WebLogic dialect. You enable this dialect by setting the
Dialect attribute to
wls:SystemHeaders() function specifies that all of the WebLogic-specific headers should be signed or encrypted. These headers are used internally by the WebLogic Web Services runtime for various features, such as reliable messaging and addressing. The headers are: