Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.6.3)

Part Number E15866-08
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

52 Configuring Message-Level Security for Web Services

This chapter describes how to configure message-level security in Oracle Service Bus (OSB).

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

Message-level security is categorized as follows:

This chapter includes the following sections:

52.1 About Message-Level Security

Oracle 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, Oracle 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 Chapter 52, "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:

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.

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

  1. A Web services client generates a SOAP header and adds the header to the SOAP message envelope. The header includes digital signatures, security tokens, and other constructs.

  2. When the proxy service processes the secured envelope, it decrypts the message, which removes the security header.

  3. The proxy service then verifies that the message conforms to its security requirements. For example, the proxy service confirms that the required message parts were signed and/or encrypted and that the required tokens are present with the required claims.

  4. The entire process is repeated in reverse for the response from the proxy service to the client.

52.2 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 Oracle Service Bus Administration Console to create message-level access control policies. These policies allow a proxy service to process only those SOAP messages from authorized clients.

52.3 Configuring Proxy Service Message-Level Security

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

52.3.1 Creating an Active Intermediary Proxy Service: Main Steps

To create a proxy service to act as an active intermediary:

  1. 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 Oracle Service Bus Administration 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.

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

    See "Adding WSDLs" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

  3. If you have not already configured the WebLogic security framework to support Oracle 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:

  4. In the Oracle Service Bus Administration 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 Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

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

  5. In the Oracle Service Bus Administration Console, create a proxy service from the WSDL that you imported. Activate your changes.

  6. 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:

    1. Select From Pre-defined Policy or WS-Policy Resource.

    2. To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.

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

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

    1. Specify the service key provider that you created.

    2. Select Yes for the Process WS-Security Header option.

    3. 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" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

    4. Optionally, modify the proxy service's message-level custom authentication settings.

52.3.2 Creating a Pass-Through Proxy Service: Main Steps

To create a pass-through proxy service:

  1. 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 Section 52.4, "Configuring Business Service Message-Level Security: Main Steps."

  2. 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:

    1. Select From Pre-defined Policy or WS-Policy Resource.

    2. To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.

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

  3. In the Oracle Service Bus Administration 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. Activate your changes.

  4. If you should later edit the proxy service you just created, select No for the Process WS-Security Header option on the Security tab.

  5. Configure the proxy service to route to the business service that you created.

    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 Section 2.3, "Working with Proxy Services."

52.4 Configuring Business Service Message-Level Security: Main Steps

Outbound message-level security applies to messages between Oracle 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:

  1. In a text editor or IDE, create a WSDL document to define the policy.

  2. In the Oracle Service Bus Administration Console, import the Web service's WSDL document into the Oracle Service Bus WSDL repository and resolve any WSDL dependencies.

    See "Adding WSDLs" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

  3. In the Oracle Service Bus Administration 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 Section 2.1.15, "Creating Service Account Resources" andSection 2.2, "Working with Business Services."

    • If any operation request policy requires authentication with a WS-Security Username/Password token with password digest, make sure to enable password digests. See Section 45.7, "Configuring the Oracle 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 Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

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

    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.

  5. 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 Section 53.1, "Mapping Identity to a SAML Token."

  6. Create a business service from the WSDL that you imported. Activate your changes.

    See Section 2.2, "Working with Business Services."

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

    1. Select From Pre-defined Policy or WS-Policy Resource.

    2. To specify policies that apply to the entire service, expand the service name entry. Click Add to search for and select your policies.

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

  8. 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 Section 52.3.1, "Creating an Active Intermediary Proxy Service: Main Steps."

52.5 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 Oracle schema for security policy:

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

Example 52-1 is an abstract WS-Policy statement that does the following:

  • Requires the message from the client to include a user name and password token for authentication

  • Requires the client to encrypt the user name and password 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, Oracle 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 the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Figure 52-1 Binding a Certificate to an Abstract Policy

Description of Figure 52-1 follows
Description of "Figure 52-1 Binding a Certificate to an Abstract Policy"

Also in Example 52-1:

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

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

52.5.2 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 Chapter 52, "Configuring Message-Level Security for Web Services."

Example 52-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 Section 51.4, "Attaching WS-Policy Statements to WSDL Documents."

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

52.5.3 Example: Encrypting a Custom SOAP Header

Example 52-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.

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, Oracle 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 the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Also of note in Example 52-3:

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

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

52.5.4 Example: Signing the Message Body and Headers

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

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

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

Example 52-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.

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 Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server.

The "Oracle WebLogic Server Security Policy Assertion Reference" in the Oracle Fusion Middleware WebLogic Web Services Reference for Oracle WebLogic Server describes the policy elements in detail.

Note the following about this example:

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

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

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

Example 52-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.

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 Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server.

The "Oracle Web Services Security Policy Assertion Reference" in the Oracle Fusion Middleware WebLogic Web Services Reference for Oracle WebLogic Server describes the policy elements in detail.

Note the following about this example:

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

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

52.6 Disabling Outbound WS-Security

Note:

On proxy services that forward to other proxies (such as local proxies) containing Oracle Web Services Manager service policies, outbound WS-Security processing is disabled. OSB handles that behavior automatically and does not use the doOutboundWss property. For more information, see Section 31.5, "Using OWSM Security with Local Proxies."

The remainder of this section describes how to disable outbound WS-Security processing for other design patterns.

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:

For information about the $outbound message context variable, see "Message Context" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

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 Oracle Service Bus Administration 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 Oracle Service Bus startup command so that it sets the following system property to true: com.bea.wli.sb.security.wss.LaxOutboundWssValidation

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

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