Skip Headers
Oracle® Fusion Middleware WebLogic Web Services Reference for Oracle WebLogic Server
11g Release 1 (10.3.6)

Part Number E13750-06
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

6 Oracle Web Services Security Policy Assertion Reference

This chapter provides reference information about the security assertions you can configure in a WebLogic Web services security policy file using the proprietary schema.

Previous releases of WebLogic Server, released before the formulation of the OASIS WS-SecurityPolicy specification, used security policy files written under the WS-Policy specification, using a proprietary schema for Web services security policy. This release of WebLogic Server supports security policy files that conform to the OASIS WS-SecurityPolicy 1.2 specification at http://www.oasis-open.org/committees/download.php/21401/ws-securitypolicy-1.2-spec-cd-01.pdf. It still supports the proprietary Web services security policy files first included in WebLogic Server 9, but this legacy policy format is deprecated and should not be used for new applications.

This chapter includes the following sections:

Overview of a Policy File That Contains Security Assertions

You can use policy files to configure the message-level security of a WebLogic Web service. Use the @Policy and @Policies JWS annotations in the JWS file that implements the Web service to specify the name of the security policy file that is associated with a WebLogic Web service.

A security policy file is an XML file that conforms to the WS-Policy specification at http://www.w3.org/Submission/WS-Policy. 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 are not based on the latest update of the specification (13 July 2005.)

Policy files using the Oracle Web services security policy schema have the following namespace

<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  >

This release of WebLogic Server also includes a large number of packaged policy files that conform to the OASIS WS-SecurityPolicy 1.2 specification. WS-SecurityPolicy 1.2 policy files and Oracle proprietary Web services security policy schema files are not mutually compatible; you cannot use both types of policy file in the same Web services security configuration. For information about using WS-SecurityPolicy 1.2 security policy files, see "Using WS-SecurityPolicy 1.2 Policy Files" in Securing WebLogic Web Services for Oracle WebLogic Server.

See "Configuring Message-Level Security" in Securing WebLogic Web Services for Oracle WebLogic Server for task-oriented information about creating a message-level secured WebLogic Web service.

Graphical Representation

The following graphic describes the element hierarchy of the security assertions in an Oracle security policy file.

Figure 6-1 Element Hierarchy of Oracle Security Policy Assertions

Description of Figure 6-1 follows
Description of "Figure 6-1 Element Hierarchy of Oracle Security Policy Assertions"

Example of a Policy File With Security Elements

<?xml version="1.0"?>
<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
  >
  <wssp:Identity>
    <wssp:SupportedTokens>
      <wssp:SecurityToken TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID">
        <wssp:Claims>
          <wssp:ConfirmationMethod>sender-vouches</wssp:ConfirmationMethod>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>
  </wssp:Identity>
  <wssp:Confidentiality>
    <wssp:KeyWrappingAlgorithm 
           URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
    <wssp:Target>
      <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
      <wssp:MessageParts
           Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
           wls:SecurityHeader(Assertion)
      </wssp:MessageParts>
    </wssp:Target>
    <wssp:Target>
      <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
      <wssp:MessageParts 
           Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
           wsp:Body()</wssp:MessageParts>
    </wssp:Target>
    <wssp:KeyInfo />
  </wssp:Confidentiality>
</wsp:Policy>

Element Description

The following sections describe the elements in detail.

CanonicalizationAlgorithm

Specifies the algorithm used to canonicalize the SOAP message elements that are digitally signed.

Note:

The WebLogic Web services security runtime does not support specifying an InclusiveNamespaces PrefixList that contains a list of namespace prefixes or a token indicating the presence of the default namespace to the canonicalization algorithm.

Table 6-1 Attributes of <CanonicalizationAlgorithm>

Attribute Description Required?

URI

The algorithm used to canonicalize the SOAP message being signed.

You can specify only the following canonicalization algorithm:

http://www.w3.org/2001/10/xml-exc-cl4n#

Yes


Claims

Specifies additional metadata information that is associated with a particular type of security token. Depending on the type of security token, you can or must specify the following child elements:

  • For username tokens, you can define a <UsePassword> child element to specify whether you want the SOAP messages to use password digests. For more information, see UsePassword.

  • For SAML tokens, you must define a <ConfirmationMethod> child element to specify the type of SAML confirmation (sender-vouches or holder-of-key). For more information, see ConfirmationMethod.

By default, a security token for a secure conversation has a lifetime of 12 hours. To change this default value, define a <TokenLifeTime> child element to specify a new lifetime, in milliseconds, of the security token. For more information, see TokenLifeTime.

This element does not have any attributes.

Confidentiality

Specifies that part or all of the SOAP message must be encrypted, as well as the algorithms and keys that are used to encrypt the SOAP message.

For example, a Web service may require that the entire body of the SOAP message must be encrypted using triple-DES.

Table 6-2 Attributes of <Confidentiality>

Attribute Description Required?

SupportTrust10

.

The valid values for this attribute are true and false. The default value is false.

No


ConfirmationMethod

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: sender-vouches or holder-of-key. For example:

<wssp:Claims>
          <wssp:ConfirmationMethod>sender-vouches</wssp:ConfirmationMethod>
  </wssp:Claims>

This element does not have any attributes.

The <ConfirmationMethod> element is required only if you are using SAML tokens.

The exact location of the <ConfirmationMethod> assertion in the security policy file depends on the type configuration method you are configuring. In particular:

sender-vouches:

Specify the <ConfirmationMethod> assertion within an <Identity> assertion, as shown in the following example:

<?xml version="1.0"?>
<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
  >
  <wssp:Identity>
    <wssp:SupportedTokens>
      <wssp:SecurityToken 
        TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID">
        <wssp:Claims>
          <wssp:ConfirmationMethod>sender-vouches</wssp:ConfirmationMethod>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>
  </wssp:Identity>
</wsp:Policy>

holder-of-key:

Specify the <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 sender-vouches.

For example:

<?xml version="1.0"?>
<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part">
  <wssp:Integrity>
    <wssp:SignatureAlgorithm
       URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    <wssp:CanonicalizationAlgorithm
       URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <wssp:Target>
      <wssp:DigestAlgorithm 
         URI="http://www.w3.org/2000/09/xmldsig#sha1" />
      <wssp:MessageParts 
         Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
         wsp:Body()
      </wssp:MessageParts>
    </wssp:Target>
    <wssp:SupportedTokens>
      <wssp:SecurityToken 
          IncludeInMessage="true" 
          TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID">
        <wssp:Claims>
          <wssp:ConfirmationMethod>holder-of-key</wssp:ConfirmationMethod>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>
  </wssp:Integrity>
</wsp:Policy>

For more information about the two SAML confirmation methods (sender-vouches or holder-of-key), see "SAML Token Profile Support in WebLogic Web Services" in Understanding Security for Oracle WebLogic Server.

DigestAlgorithm

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. For more information, see MessageParts.

Table 6-3 Attributes of <DigestAlgorithm>

Attribute Description Required?

URI

The digest algorithm that is used when digitally signing the specified parts of a SOAP message.

You can specify only the following digest algorithm:

http://www.w3.org/2000/09/xmldsig#sha1

Yes


EncryptionAlgorithm

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. For more information, see MessageParts.

Table 6-4 Attributes of <EncryptionAlgorithm>

Attribute Description Required?

URI

The encryption algorithm used to encrypt specified parts of the SOAP message.

Valid values are:

http://www.w3.org/2001/04/xmlenc#tripledes-cbc
http://www.w3.org/2001/04/xmlenc#kw-tripledes
http://www.w3.org/2001/04/xmlenc#aes128-cbc

When interoperating between Web services built with WebLogic Workshop 8.1, you must specify http://www.w3.org/2001/04/xmlenc#aes128-cbc as the encryption algorithm.

Yes


Identity

Specifies the type of security tokens (username, X.509, or SAML) that are supported for authentication.

This element has no attributes.

Integrity

Specifies that part or all of the SOAP message must be digitally signed, as well as the algorithms and keys that are used to sign the SOAP message.

For example, a Web service may require that the entire body of the SOAP message must be digitally signed and only algorithms using SHA1 and an RSA key are accepted.

Table 6-5 Attributes of <Integrity>

Attribute Description Required?

SignToken

Specifies whether the security token, specified using the <SecurityToken> child element of <Integrity>, should also be digitally signed, in addition to the specified parts of the SOAP message.

The valid values for this attribute are true and false. The default value is true.

No

SupportTrust10

.

The valid values for this attribute are true and false. The default value is false.

No

X509AuthConditional

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.

No


KeyInfo

Used to specify the security tokens that are used for encryption.

This element has no attributes.

KeyWrappingAlgorithm

Specifies the algorithm used to encrypt the message encryption key.

Table 6-6 Attributes of <KeyWrappingAlgorithm>

Attribute Description Required?

URI

The algorithm used to encrypt the SOAP message encryption key.

Valid values are:

  • http://www.w3.org/2001/04/xmlenc#rsa-1_5

    (to specify the RSA-v1.5 algorithm)

  • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

    (to specify the RSA-OAEP algorithm)

Yes


Label

Specifies a label for the security context token. Used when configuring WS-SecureConversation security contexts.

This element has no attributes.

Length

Specifies the length of the key when using security context tokens and derived key tokens. This assertion only applies to WS-SecureConversation security contexts.

The default value is 32.

This element has no attributes.

MessageAge

Specifies the acceptable time period before SOAP messages are declared stale and discarded.

When you include this security assertion in your security 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 security policy file is associated. The <Timestamp> header indicates to the recipient of the SOAP message when the message expires.

For example, assume that your security policy file includes the following <MessageAge> assertion:

<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  >
...
   <wssp:MessageAge Age="300" />
</wsp:Policy>

The resulting generated SOAP message will have a <Timestamp> header similar to the following excerpt:
<wsu:Timestamp
     wsu:Id="Dy2PFsX3ZQacqNKEANpXbNMnMhm2BmGOA2WDc2E0JpiaaTmbYNwT" 
     xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
   <wsu:Created>2005-11-09T17:46:55Z</wsu:Created>
   <wsu:Expires>2005-11-09T17:51:55Z</wsu:Expires>
</wsu:Timestamp>

In the example, the recipient of the SOAP message discards the message if received after 2005-11-09T17:51:55Z, or five minutes after the message was created.

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

The following table describes the attributes of the <MessageAge> assertion.

Table 6-7 Attributes of <MessageAge>

Attribute Description Required?

Age

Specifies the actual maximum age time-out for a SOAP message, in seconds.

No


The following table lists the properties that describe the timestamp behavior of the WebLogic Web services security runtime, along with their default values.

Table 6-8 Timestamp Behavior Properties

Property Description Default Value

Clock Synchronized

Specifies whether the Web service assumes synchronized clocks.

true

Clock Precision

If clocks are synchronized, describes the accuracy of the synchronization.

Note: This property is deprecated as of release 9.2 of WebLogic Web services. Use the Clock Skew property instead. If both properties are set, then Clock Skew takes precedence.

60000 milliseconds

Clock Skew

Specifies the allowable difference, in milliseconds, between the sender and receiver of the message.

60000 milliseconds

Lax Precision

Allows you to relax the enforcement of the clock precision property.

Note: This property is deprecated as of release 9.2 of WebLogic Web services. Use the Clock Skew property instead.

false

Max Processing Delay

Specifies the freshness policy for received messages.

-1

Validity Period

Represents the length of time the sender wants the outbound message to be valid.

60 seconds


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" in the Oracle WebLogic Server Administration Console Help for additional reference information about these timestamp properties.

MessageParts

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.

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

Table 6-9 Attributes of <MessageParts>

Attribute Description Required?

Dialect

Identifies the dialect used to identity the parts of the SOAP message that should be signed or encrypted. If this attribute is not specified, then XPath 1.0 is assumed.

The value of this attribute must be one of the following:

  • http://www.w3.org/TR/1999/REC-xpath-19991116: Specifies that an XPath 1.0 expression should be used against the SOAP message to specify the part to be signed or encrypted.

  • http://schemas.xmlsoap.org/2002/12/wsse#part: Convenience dialect used to specify that the entire SOAP body should be signed or encrypted.

  • http://www.bea.com/wls90/security/policy/wsee#part: Convenience dialect to specify that the WebLogic-specific headers should be signed or encrypted. You can also use this dialect to use QNames to specify the parts of the security header that should be signed or encrypted.

See Using MessageParts To Specify Parts of the SOAP Messages that Must Be Encrypted or Signed for examples of using these dialects.

Yes


SecurityToken

Specifies the security token that is supported for authentication, encryption or digital signatures, depending on the parent element.

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.

The specific type of the security token is determined by the value of its TokenType attribute, as well as its parent element.

By default, a security token for a secure conversation has a lifetime of 12 hours. To change this default value, add a <Claims> child element that itself has a <TokenLifeTime> child element, as described in Claims.

Table 6-10 Attributes of <SecurityToken>

Attribute Description Required?

DerivedFromTokenType

Specifies what security token it is derived from. For example, a value of "http://schemas.xmlsoap.org/ws/2005/02/sc/sct" specifies that it is derived from an old version of Secure Conversation Token.

No

IncludeInMessage

Specifies whether to include the token in the SOAP message.

Valid values are true or false.

The default value of this attribute is false when used in the <Confidentiality> assertion and true when used in the <Integrity> assertion.

The value of this attribute is always true when used in the <Identity> assertion, even if you explicitly set it to false.

No

TokenType

Specifies the type of security token. Valid values are:

  • http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3 (To specify a binary X.509 token)

  • http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken (To specify a username token)

  • http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID (To specify a SAML token)

Yes


SecurityTokenReference

For internal use only.

You should never include this security assertion in your custom security policy file; it is described in this section for informational purposes only. The WebLogic Web services runtime automatically inserts this security assertion in the security 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 security policy file. The Web services runtime then uses the server's private key to decrypt the message.

SignatureAlgorithm

Specifies the cryptographic algorithm used to compute the digital signature.

Table 6-11 Attributes of <SignatureAlgorithm>

Attribute Description Required?

URI

Specifies the cryptographic algorithm used to compute the signature.

Note: Be sure that you specify an algorithm that is compatible with the certificates you are using in your enterprise.

Valid values are:

http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2000/09/xmldsig#dsa-sha1

Yes


SupportedTokens

Specifies the list of supported security tokens that can be used for authentication, encryption, or digital signatures, depending on the parent element.

This element has no attributes.

Target

Encapsulates information about which targets of a SOAP message are to be encrypted or signed, depending on the parent element.

The child elements also depend on the parent element; for example, when used in <Integrity>, you can specify the <DigestAlgorithm>, <Transform>, and <MessageParts> child elements. When used in <Confidentiality>, you can specify the <EncryptionAlgorithm>, <Transform>, and <MessageParts> child elements.

You can have one or more targets.

Table 6-12 Attributes of <Target>

Attribute Description Required?

encryptContentOnly

Specifies whether to encrypt an entire element, or just its content.

This attribute can be specified only when <Target> is a child element of <Confidentiality>.

Default value of this attribute is true, which means that only the content is encrypted.

No


TokenLifeTime

Specifies the lifetime, in seconds, of the security context token or derived key token. This element is used only when configuring WS-SecurityConversation security contexts.

The default lifetime of a security token is 12 hours (43,200 seconds).

This element has no attributes.

Transform

Specifies the URI of a transformation algorithm that is applied to the parts of the SOAP message that are signed or encrypted, depending on the parent element.

You can specify zero or more transforms, which are executed in the order they appear in the <Target> parent element.

Table 6-13 Attributes of <Transform>

Attribute Description Required?

URI

Specifies the URI of the transformation algorithm.

Valid URIs are:

  • http://www.w3.org/2000/09/xmldsig#base64 (Base64 decoding transforms)

  • http://www.w3.org/TR/1999/REC-xpath-19991116 (XPath filtering)

For detailed information about these transform algorithms, see XML-Signature Syntax and Processing at http://www.w3.org/TR/xmldsig-core/#sec-TransformAlg.

Yes


UsePassword

Specifies that whether the plaintext or the digest of the password appear in the SOAP messages. This element is used only with username tokens.

Table 6-14 Attributes of <UsePassword>

Attribute Description Required?

Type

Specifies the type of password. Valid values are:

  • http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText: Specifies that cleartext passwords should be used in the SOAP messages.

  • http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest: Specifies that password digests should be used in the SOAP messages.

Note: For backward compatibility reasons, the two preceding URIs can also be specified with an initial "www." For example:

  • http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText

  • http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest

Yes


Using MessageParts To Specify Parts of the SOAP Messages that Must Be Encrypted or Signed

When you use either the Integrity or Confidentiality assertion in your security 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 MessageParts assertion.

See Example of a Policy File With Security Elements for an example of a complete security 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.

You use the Dialect attribute of MessageParts to specify the dialect used to identify the SOAP message parts. The WebLogic Web services security runtime supports the following three dialects:

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

XPath 1.0

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 http://www.w3.org/TR/1999/REC-xpath-19991116.

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:Body or soap:Header elements. For this reason, Oracle provides the following two functions that take as parameters an XPath expression:

  • wsp:GetBody(xpath_expression)—Specifies that the root element from which the XPath expression starts searching is soap:Body.

  • wsp:GetHeader(xpath_expression)—Specifies that the root element from which the XPath expression starts searching is soap:Header.

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 soap:Envelope.

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 Integrity or Confidentiality assertion:

<wssp:MessageParts 
     Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"
     xmlns:n1="http://www.bea.com/foo">
        wsp:GetBody(./n1:AddInt)
</wssp:MessageParts>

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 security policy file.

The following example is similar, except that the part that will be signed or encrypted is wsu:Timestamp, which is a child element of wsee:Security and is located in the SOAP message header:

<wssp:MessageParts 
     Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">
        wsp:GetHeader(./wsse:Security/wsu:Timestamp)
</wssp:MessageParts>

In the preceding example, it is assumed that the wsee: and wse: namespaces have been defined elsewhere in the security 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, at http://www.w3.org/TR/xpath specification.

Pre-Defined wsp:Body() Function

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 Oracle recommends you use the dialect that pre-defines the wsp:Body() function for just this purpose, as shown in the following example:

<wssp:MessageParts
     Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
       wsp:Body()
</wssp:MessageParts>

WebLogic-Specific Header Functions

Oracle 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 http://www.bea.com/wls90/security/policy/wsee#part.

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

  • wsrm:SequenceAcknowledgement

  • wsrm:AckRequested

  • wsrm:Sequence

  • wsa:Action

  • wsa:FaultTo

  • wsa:From

  • wsa:MessageID

  • wsa:RelatesTo

  • wsa:ReplyTo

  • wsa:To

  • wsax:SetCookie

The following example shows how to use the wls:SystemHeader() function:

<wssp:MessageParts
     Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
        wls:SystemHeaders()
</wssp:MessageParts>

Use the wls:SecurityHeader(header) function to specify a particular part in the security header that should be signed or encrypted, as shown in the following example:

<wssp:MessageParts
    Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
        wls:SecurityHeader(wsa:From)
</wssp:MessageParts>

In the example, only the wsa:From security header is signed or encrypted. You can specify any of the preceding list of headers to the wls:SecurityHeader() function.