Configuring Message-Level Security for Web Services

Message-level security applies security checks to a SOAP message after a Web services client establishes a connection with an AquaLogic Service Bus proxy service or business service and before the proxy service or business service processes the message.

Inbound message-level security applies to messages between clients and AquaLogic Service Bus proxy services. It applies security to both the request from the client and the response message back to the client.

You can think of this as proxy service security.

Outbound message-level security applies to messages between AquaLogic Service Bus proxy services and SOAP-HTTP or SOAP-JMS business services. It applies security to both the request and the response.

You can think of this as business service security.

The following sections describe configuring message-level security for a proxy service or a business service:

About Message-Level Security

AquaLogic Service Bus supports message-level security for SOAP messages that are sent over the HTTP (including HTTPS) or JMS protocols. Usually you use message-level security in addition to the transport-level security that these protocols offer. You can require Web services clients to provide credentials at the transport level, the message level, or both levels. If you require clients to provide credentials at both levels, AquaLogic Service Bus uses the message-level credentials for proxy service authentication and authorization.

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. The Web Services Policy (WS-Policy) framework is described in Configuring Message-Level Security for Web Services.

With message-level security, a proxy service or business service specifies which of its operations are secured and which of the following security measures a Web services client must apply to its SOAP messages, which contain requests to invoke operations:

Authentication

Requires a client to present an identity that can be compared with user accounts in the domain’s authentication provider.

Message integrity through digital signatures

Establishes the identity of the client that is requesting to invoke an operation and guarantees that no intermediary has altered the request. Also guarantees that the return values of the operation are returned to the client without being altered by an intermediary.

Message confidentiality through XML encryption

Encrypts the request and the return value in the response and guarantees that no intermediary has viewed the request or the response.

All of these security measures require a client to encode security tokens in its SOAP messages, and the proxy service or business service specifies which types of security tokens it requires to be encoded in the SOAP messages.

WS-Security 1.0, at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
Web Services Security: Username Token Profile 1.0, at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf
Web Services Security X.509 Token Profile 1.0, at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf
Web Services Security SAML Token Profile 1.0, at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf

Sample Sequence of Actions in Message-Level Security

To send a SOAP message to a proxy service that requires message-level security, the following actions occur:

Message-Level Access Control Policies for Proxy Services

While message integrity and message confidentiality guarantee that intermediaries do not view or modify messages, and while message authentication requires clients to prove that they are known users, they do nothing to specify which known users are allowed (authorized) to invoke proxy service operations.

To limit access to authorized users, you use the AquaLogic Service Bus Console to create message-level access control policies. These policies allow a proxy service to process only those SOAP messages from authorized clients.

Configuring Proxy Service Message-Level Security

You can configure a proxy service to support one of the following techniques for inbound message-level security:

Active-Intermediary

The proxy service processes the header in the client’s SOAP messages and enforces the message-level access control policy on the messages.

For example, a client encrypts and signs its SOAP message and sends it to a proxy service. The proxy service decrypts the message and verifies the digital signature, then routes the message. Before the proxy service sends the response back to the client, the proxy service signs and encrypts the message. The client then decrypts the message and verifies the proxy service’s digital signature.

Pass-Through

Instead of processing the header in the client’s SOAP messages, the proxy service passes the message untouched to a business service. Although the proxy service does not process the secured sections of the SOAP message, it can route the message based on values in the header. When the business service receives the message, it processes the security header and acts on the request. Note that the business service must use the Web Services Policy (WS-Policy) framework to describe which of its operations are secured with message-level security. The business service sends its response to the proxy service, and the proxy service passes the response untouched to the client.

For example, the client encrypts and signs the message and sends it to the proxy service. The proxy service does not decrypt the message or verify the digital signature; it simply routes the message to the business service. The business service decrypts the messages and verifies the digital signature, and then processes the request. The response path is similar.

Creating an Active Intermediary Proxy Service: Main Steps

In a text editor or IDE, create a WSDL document to define the proxy service:

If you plan to bind the policies directly from the console, the WSDL does not need to have policy statements.
If you want the policy to be WSDL-based, attach one or more Web Services Policy (WS-Policy) statements to the WSDL document, including one or more of the predefined policies.

In the AquaLogic Service Bus Console, import the WSDL document into the AquaLogic Service Bus WSDL repository and resolve any WSDL dependencies.

See “Adding a WSDL” in WSDLs in the Using the AquaLogic Service Bus Console.

If you have not already configured the WebLogic security framework to support AquaLogic Service Bus, do one or more of the following depending on whether the WS-Policy of any of the operations in the proxy service contains security policy assertions that secure requests from clients to the proxy service:

If you want operation request policies to require authentication with a WS-Security X.509 certificate token, configure the Web Service security configuration named __SERVICE_BUS_INBOUND_WEB_SERVICE_SECURITY_MBEAN__. See step 2 in Configuring the WebLogic Security Framework: Main Steps.
If you want operation request policies to require authentication with a WS-Security Username/Password token with password digest, make sure to enable password digests. See step 5 in Configuring the WebLogic Security Framework: Main Steps.
If you want operation request policies to require the use of SAML tokens, you must configure a SAML asserting party for this proxy service. See Authenticating SAML Tokens in Proxy Service Requests.
If you want operation request policies to require digital signatures, register the accepted client signature verification certificates in the WebLogic Server Certificate Registry. See step 4 in Configuring the WebLogic Security Framework: Main Steps.
If you want operation request policies to require digital encryption, configure a service key provider that contains an encryption credential. The proxy service will use this credential to decrypt the encrypted SOAP message. See “Adding a service key provider” in Service Key Providers in Using the AquaLogic Service Bus Console.

In the AquaLogic Service Bus Console, do one or more of the following depending whether the WS-Policy of any of the operations in the proxy service contains security policy assertions that secure responses from the proxy service to clients:

If any operation response policy requires digital signatures, configure a service key provider that contains a digital signature credential. You can create one service key provider that contains credentials for both encryption and digital signatures. See “Adding a service key provider” in Service Key Providers in Using the AquaLogic Service Bus Console.
If any operation response policy specifies encryption, the client must send its certificate to the proxy service on the request. The proxy service will use the client’s public key to encrypt its response. The client certificate must not be the same as the proxy service’s encryption certificate.

In the AquaLogic Service Bus Console, create a proxy service from the WSDL that you imported in step 1. Activate your changes.
If the WSDL document does not have WS-Policy attachments and you want to add them, or if you want to specify a different WS-Policy from that of the WSDL, edit the proxy service you just created to do the following from the Policies tab:

Select Custom Policy Bindings.
To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.
To specify policies that apply to an operation or the request/response of that operation, expand the operation name entry. Click Add to search for and select your policies.

Update the policy binding.

Edit the proxy service you just created to do the following from the Security tab:

Specify the service key provider that you created in step 4.
Select the Process WS-Security Header check box.
Optionally, modify the proxy service’s default message-level access control policy, which specifies conditions under which users, groups, or roles can invoke the secured operations. See “Editing Message-Level Access Policies” under Security Configuration in Using the AquaLogic Service Bus Console.
Optionally, modify the proxy service’s message-level custom authentication settings. See “Editing Message-Level Access Policies” under Security Configuration in Using the AquaLogic Service Bus Console.

Creating a Pass-Through Proxy Service: Main Steps

Create a business service to which the proxy service will pass the unprocessed SOAP message. There are two configuration methods:

The business service is a Web service that contains WS-Policy statements.
The business service directly binds the WS-Policies. The WSDL on which the service is based should not have any WS-Policy statements.

See Configuring Business Service Message-Level Security: Main Steps.

If the WSDL document does not have WS-Policy attachments and you want to add them, or if you want to specify a different WS-Policy from that of the WSDL, edit the business service you just created to do the following from the Policies tab:

Select Custom Policy Bindings.
To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.
To specify policies that apply to an operation or the request/response of that operation, expand the operation name entry. Click Add to search for and select your policies.

Update the policy binding.

In the AquaLogic Service Bus Console, create a proxy service from a WSDL document. You can use the same WSDL document that you used for the business service that you created in step 1. Activate your changes.
If you should later edit the proxy service you just created, do not select the Process WS-Security Header check box on the Security tab.
Configure the proxy service to route to the business service that you created in step 1.

If you route to the business service based on the operation that the client’s SOAP message is requesting to invoke, you must configure the routing so that it specifies an operation selection algorithm other than the SOAP body algorithm. Make sure the actions in the proxy service pipeline do not modify the WS-Security header or any parts of the SOAP envelope that are signed or encrypted. Changes to clear-text message parts covered by digital signatures almost always break the digital signature because the signature cannot be verified later.

See Proxy Services in Using the AquaLogic Service Bus Console.

Configuring Business Service Message-Level Security: Main Steps

Outbound message-level security applies to messages between AquaLogic Service Bus proxy services and SOAP-HTTP or SOAP-JMS business services. It applies security to both the request and the response.

To configure outbound message-level security for a business service that represents a SOAP-HTTP or SOAP-JMS Web service:

In a text editor or IDE, create a WSDL document to define the policy.
In the AquaLogic Service Bus Console, import the Web service’s WSDL document into the AquaLogic Service Bus WSDL repository and resolve any WSDL dependencies.

See “Adding a WSDL” in WSDLs in the Using the AquaLogic Service Bus Console.

In the AquaLogic Service Bus Console, do one or more of the following depending on whether the WSDL document contains WS-Policy statements that secure requests from a proxy service to the business service:

If any operation request policy includes an identity assertion with WS-Security Username Token as one of the supported token types, configure a service account for the business service. In the service account, provide the user name and password that you want the proxy service to send to the business service. Proxy services that route to this business service will get the username and password from this service account. See Service Accounts and Business Services in the Using the AquaLogic Service Bus Console.
If any operation request policy requires authentication with a WS-Security Username/Password token with password digest, make sure to enable password digests. See step 5 in Configuring the WebLogic Security Framework: Main Steps.
If any operation request policy requires digital signatures, configure a service key provider that contains a digital signature credential. You can create one service key provider that contains credentials for both encryption and digital signatures. See “Adding a service key provider” in Service Key Providers in Using the AquaLogic Service Bus Console.

If any operation response policy in the business service requires encryption (that is, the business service encrypts the response with the proxy service’s encryption public key), configure a service key provider and assign an encryption credential to the service key provider. See “Adding a service key provider” in Service Key Providers in Using the AquaLogic Service Bus Console.

Caution:

Encrypted back-end response messages: If the response policy of the business service specifies encryption, the proxy service will send its encryption certificate to the business service on the request. The business service will encrypt its response using the proxy service’s public key. The proxy service encryption credential must not be the same as the business service encryption credential.

If any policy in the business service specifies using SAML assertions, configure a WebLogic SAML Credential Mapping Provider V2 asserting party. For more information, see Configuring SAML Credential Mapping: Main Steps.
In the AquaLogic Service Bus Console, create a business service from the WSDL that you imported in step 2. Activate your changes.

See Business Services in Using the AquaLogic Service Bus Console.

If you want to directly attach the policies to the service, edit the business service you just created to do the following from the Policies tab:

Select Custom Policy Bindings.
To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.
To specify policies that apply to an operation or the request/response of that operation, expand the operation name entry. Click Add to search for and select your policies.

Click Update to update the business service.

Create a proxy service that routes SOAP messages to the business service. You can use either an active-intermediary proxy service or a pass-through proxy service.

See Creating an Active Intermediary Proxy Service: Main Steps.

Examples of Custom WS-Policy Statements

The following sections provide examples of custom WS-Policy statements written under the WS-Policy specification using the proprietary BEA schema for security policy:

Example: Encrypting Part of the SOAP Body and Header

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 must create a custom WS-Policy file.

Requires the message from the client to include a user name and password token for authentication
Requires the client to encrypt the user name token (which is in the security header)
Requires the client to encrypt the /definitions/message/CreditCardNumber element

This policy cannot be used with a business service because it is abstract: its KeyInfo element does not contain the certificate used for encryption. Instead, when you activate a proxy service that uses this WS-Policy statement, AquaLogic Service Bus binds to the WS-Policy statement the encryption certificate from the service key provider that you associate with the proxy service. See Service Key Providers in Using the AquaLogic Service Bus Console.

The KeyWrappingAlgorithm element specifies that the client must use the RSA 1.5 algorithm to wrap symmetric keys.
The EncryptionAlgorithm specifies that the client must use the Triple DES (Data Encryption Standard) algorithm perform encrypt the security header and message body.

Listing 7-1 Encrypting Part of the SOAP Body and Header

<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:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-secext-1.0.xsd"
   xmlns:m="http://example.org"
   wsu:Id="encrypt-custom-body-element-and-username-token">

    <!-- Require messages to provide a user name and password token 
         for authentication --> 
   <wssp:Identity>
      <wssp:SupportedTokens>
        <wssp:SecurityToken IncludeInMessage="true"
            TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
               wss-username-token-profile-1.0#UsernameToken">
            <wssp:UsePassword Type="http://docs.oasis-open.org/wss/2004/01/
                oasis-200401-wss-username-token-profile-1.0#PasswordText"/>
        </wssp:SecurityToken>
      </wssp:SupportedTokens>
   </wssp:Identity>

   <wssp:Confidentiality>
      <wssp:KeyWrappingAlgorithm
        URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

      <!-- Require the user name and password in the security header
           to be encrypted --> 
      <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(wsse:UsernameToken)
        </wssp:MessageParts>
      </wssp:Target>

      <!-- Require the /definitions/message/CreditCardNumber element to 
           be encrypted --> 
      <wssp:Target>
        <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts>
          wsp:GetBody(.)/m:CreditCardNumber
        </wssp:MessageParts>
      </wssp:Target>

      <!-- This is an abstract policy because the KeyInfo element is
          empty. The KeyInfo data is bound to the policy at runtime --> 
      <wssp:KeyInfo/>
   </wssp:Confidentiality>
</wsp:Policy>

Example: Encryption Policy for a Business Service

If you want messages to a business service to be encrypted, you must create a custom WS-Policy. The policy must be concrete (it must contain the encryption certificate instead of using a certificate from a service key provider) and it must be located directly in a WSDL document instead of being included by reference.

Typically, you would require messages to a business service to be encrypted if the proxy service that sends messages to the business service is a pass-through proxy service. That is, the proxy service that receives messages from a client does not process the SOAP message. Instead, the proxy service routes the message to the business service, and the business service takes on the responsibility of Web Services Security. See Message-Level Access Control Policies for Proxy Services.

Listing 7-2 is a WSDL document that contains a concrete policy. Note the following about this example:

The policy requires clients to encrypt the message body.
The KeyInfo element specifies the type of token that a client must provide to is the parent element that is used to describe and embed the encryption certificate. The BinarySecurityToken element contains the base-64 encoded encryption certificate (the value is truncated in the example). If your certificate is in PEM format, the content of the PEM file (without the PEM prefix and suffix) is the base-64 encoded representation of the certificate. If your encryption certificate is stored in a JDK keystore, you can easily export it to a PEM file.
The policy provides a unique ID and the WSDL uses a URI fragment to refer to the ID. See Attaching WS-Policy Statements to WSDL Documents.

Listing 7-2 Encrypting the Body with a Concrete Policy, Embedding the Policy in the WSDL Document

<definitions name="WssServiceDefinitions"
  targetNamespace="http://com.bea.alsb/tests/wss"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
    wssecurity-utility-1.0.xsd"
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  ...>

  <wsp:UsingPolicy xmlns:n1="http://schemas.xmlsoap.org/wsdl/"
      n1:Required="true"/>

  <!-- The policy provides a unique ID -->
  <wsp:Policy wsu:Id="myEncrypt.xml">
    <wssp:Confidentiality
        xmlns:wssp="http://www.bea.com/wls90/security/policy">
    <wssp:KeyWrappingAlgorithm
        URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

    <!-- Require the user name and password in the security header
         to be encrypted --> 
    <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>

      <!-- Embed the token type and encryption certificate --> 
      <wssp:KeyInfo>
        <wssp:SecurityToken 
            TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
               wss-x509-token-profile-1.0#X509v3"/>
        <wssp:SecurityTokenReference>
          <wssp:Embedded>
            <wsse:BinarySecurityToken
                EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-soap-message-security-1.0#Base64Binary"
                ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-x509-token-profile-1.0#X509v3"
                 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-wssecurity-secext-1.0.xsd">
                 MIICfjCCAeegAwIBAgIQV/PDyj3...
            </wsse:BinarySecurityToken>
          </wssp:Embedded>
        </wssp:SecurityTokenReference>
      </wssp:KeyInfo>
    </wssp:Confidentiality>
  </wsp:Policy>

  <binding name="WssServiceSoapBinding" type="tns:WssService">
    <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getPurchaseOrder">
      <soap:operation soapAction="" style="document"/>
      <input>
        <soap:body parts="parameters" use="literal"/>

        <!-- Use a URI fragment to refer to the unique policy ID -->
        <wsp:Policy>
          <wsp:PolicyReference URI="#myEncrypt.xml"/>
        </wsp:Policy>
      </input>
      <output>
          <soap:body parts="parameters" use="literal"/>
        </output>
      </operation>
    </binding>
    ...
</definitions>

Example: Encrypting a Custom SOAP Header

Listing 7-3 is an abstract WS-Policy statement that encrypts a custom header named CreditCardNumber.

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 must create a custom WS-Policy file.

The KeyWrappingAlgorithm element specifies that the client must use the RSA 1.5 algorithm to wrap symmetric keys.
The EncryptionAlgorithm specifies that the client must use the Triple DES (Data Encryption Standard) algorithm perform encrypt the security header.

Listing 7-3 Encrypting a Custom SOAP Header

<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"
   wsu:Id="dig-sig-for-get-header">
   <wssp:Confidentiality>
     <wssp:KeyWrappingAlgorithm
       URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

     <!-- Require the custom CreditCardNumber header to be encrypted --> 
     <wssp:Target>
        <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts
           Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">
           wsp:GetHeader(.)/n:CreditCardNumber
         </wssp:MessageParts>
     </wssp:Target>
     <wssp:KeyInfo/>
  </wssp:Confidentiality>
</wsp:Policy>

Example: Signing the Message Body and Headers

Listing 7-4 is a WS-Policy statement that requires a digital signature to access the following in the SOAP message:

A custom header named header1
All system headers
The timestamp security header
The message body

Listing 7-4 Requiring a Signature for SOAP Headers and Body

<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"
   wsu:Id="sign-custom-header-policy">

   <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#"/>

     <!-- Require the custom header header1 to be signed --> 
     <wssp:Target>
       <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
       <wssp:MessageParts
         Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"
         xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
           wssecurity-secext-1.0.xsd"
         xmlns:n="http://example.org">
         wsp:GetHeader(.)/n:header1
       </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the system headers to be signed --> 
     <wssp:Target>
        <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
           <wssp:MessageParts
              Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
              wls:SystemHeaders()
           </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the Timestamp header to be signed --> 
     <wssp:Target>
        <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <wssp:MessageParts
          Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
          wls:SecurityHeader(wsu:Timestamp)
        </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the message body to be signed --> 
     <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:Integrity>
<wssp:MessageAge/>
</wsp:Policy>

Example: Signing a SOAP Body with SAML Holder-of-Key

Listing 7-5 is a WS-Policy statement that requires the SAML asserter to use the holder-of-key method to sign the message body. The purpose of a SAML token with "holder-of-key" subject confirmation is to allow the subject to use an X.509 certificate that may not be trusted by the receiver to protect the integrity of the request messages.

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.
SignatureAlgorithm specifies the cryptographic algorithm used to compute the digital signature.
CanonicalizationAlgorithm specifies the algorithm used to canonicalize (use in simple or standard form) the SOAP message elements that are digitally signed. You can specify only http://www.w3.org/2001/10/xml-exc-cl4n#.
DigestAlgorithm specifies the digest algorithm that is used when digitally signing the specified parts of a SOAP message. You can specify only http://www.w3.org/2000/09/xmldsig#sha1 .
MessageParts specifies the parts of the SOAP message that should be signed, in this case the body.
Dialect identifies the dialect used to identify the parts of the SOAP message that should be signed.
SupportedTokens specifies the list of supported security tokens that can be used for digital signatures.
SecurityToken specifies the security token that is supported for digital signatures.
IncludeInMessage specifies whether to include the token in the SOAP message. Valid values are true or false. The default value of this attribute is true when used in the <Integrity> assertion.

TokenType specifies the type of security token, in this case http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID to specify a SAML token.
Claims specifies additional metadata information that is associated with a particular type of security token. For SAML tokens, you must define a <ConfirmationMethod> child element to specify the type of SAML confirmation (sender-vouches or holder-of-key).
ConfirmationMethod specifies the type of confirmation method, either sender-vouches or holder-of-key, that is used when using SAML tokens for identity.

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.

Listing 7-5 Signing a SOAP Body with SAML Holder-of-Key Method

<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"
   wsu:Id="saml-holder-of-key-signed">

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

Example: Authenticating, Signing, and Encrypting a SOAP Body and Headers with SAML Sender Vouches

Listing 7-6 is a WS-Policy statement that requires the SAML asserter to use the sender-vouches method to sign the message body and headers.

In sender-vouches the asserting party (different from the subject) vouches for the verification of the subject. The receiver must have a trust relationship with the asserting party.

Identity specifies the type of security tokens.
SupportedTokens specifies the list of supported security tokens that can be used for digital signatures.
SecurityToken specifies the security token that is supported for digital signatures.
IncludeInMessage is not specified because the value of this attribute is always true when used in the <Identity> assertion, even if you explicitly set it to false.

TokenType specifies the type of security token, in this case http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID to specify a SAML token.
Claims specifies additional metadata information that is associated with a particular type of security token. For SAML tokens, you must define a <ConfirmationMethod> child element to specify the type of SAML confirmation (sender-vouches or holder-of-key).
ConfirmationMethod specifies the type of confirmation method, either sender-vouches or holder-of-key, that is used when using SAML tokens for identity.
Integrity specifies that part or all of the SOAP message must be digitally signed (in this example both the body and security headers), as well as the algorithms and keys that are used to sign the SOAP message.
SignatureAlgorithm specifies the cryptographic algorithm used to compute the digital signature.
CanonicalizationAlgorithm specifies the algorithm used to canonicalize (use in simple or standard form) the SOAP message elements that are digitally signed. You can specify only http://www.w3.org/2001/10/xml-exc-cl4n#.
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:

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.

DigestAlgorithm specifies the digest algorithm that is used when digitally signing the specified parts of a SOAP message. You can specify only http://www.w3.org/2000/09/xmldsig#sha1.
MessageParts specifies the parts of the SOAP message that should be signed, in this case the body and security header.
Dialect identifies the dialect used to identify the parts of the SOAP message that should be signed.
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. The example requires that the body and security headers must be encrypted using triple-DES.

Listing 7-6 Signing a SOAP Body and Headers with SAML Sender-Vouches Method

<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"
   wsu:Id="samlPolicy-sender-vouches-signed-encrypted">

   <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: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:Target>
         <wssp:DigestAlgorithm
            URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
         <wssp:MessageParts
             Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
             wls:SecurityHeader(Assertion)
         </wssp:MessageParts>
       </wssp:Target>
   </wssp:Integrity>

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

Disabling Business Service Message-Level Security

Some infrequently used design patterns preempt a proxy service from automatically generating the outbound WS-Security SOAP envelope and instead use an XQuery expression to create the envelope. If you use this design pattern, to prevent a proxy service from automatically generating the outbound WS-Security SOAP envelope, you must create an action in the proxy service’s message flow that sets the value of the ./ctx:security/ctx:doOutboundWss element in the $outbound message context variable to xs:boolean("false"). You can create the action in either of the following places:

In a request stage of a pipeline pair. See “Adding a Pipeline Pair Node” under Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.
In a request action of a route node. See “Adding Route Node Actions” under Proxy Services: Message Flow in Using the AquaLogic Service Bus Console.

For information about the $outbound message context variable, see Message Context in AquaLogic Service Bus User Guide.

Under some circumstances, when you attempt to activate a session in which you have created or modified a proxy service with outbound message-level security disabled, the AquaLogic Service Bus Console reports validation errors (you cannot commit a session that contains errors). If your session validation reports errors because you have disabled outbound message-level security, modify the AquaLogic Service Bus startup command so that it sets the following system property to true:
com.bea.wli.sb.security.wss.LaxOutboundWssValidation

Then restart AquaLogic Service Bus. With this property set to true, the AquaLogic Service Bus Console reports warnings instead of errors (you can commit a session that reports warning messages).

Future releases of AquaLogic Service Bus will provide an easier way to disable outbound message-level security.

Security Guide