50 Configuring Message-Level Security for Web Services

This chapter describes how to configure message-level security in Service Bus.

Message-level security applies security checks to a SOAP message after a web services client establishes a connection with a 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:

  • Inbound message-level security applies to messages between clients and 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 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.

This chapter includes the following sections:

For instructions on configuring message-level security for proxy services, see Configuring Service Bus Client Access Security.

Note:

The implementation of message-level security includes proxy services that have been configured with message-level custom authentication (either custom token or user name/password).

The message-level security mechanisms described in this section work alone or in concert with the message-level custom authentication mechanism, which is described in Configuring Custom Authentication. See Combining WS-Security with Custom User Name/Password and Tokens for information about using both types of security.

50.1 About Message-Level Security

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

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.

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

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

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

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

50.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 Console, the WSDL file 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 Console, import the WSDL document into the Service Bus WSDL repository and resolve any WSDL dependencies.

    For more information about WSDL files, see Working with WSDL Documents.

  3. If you have not already configured the WebLogic security framework to support 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 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. For information about service key providers, see Working with Service Key Providers

    • 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 Console, create a proxy service from the WSDL file that you imported. Activate your changes.

  6. To attach OWSM policies to the proxy service, see one of the following sections:

  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. 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. For more information, see How to Configure Message-Level Access Policies.

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

50.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 file on which the service is based should not have any WS-Policy statements.

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

  2. To attach OWSM policies to the proxy service, see one of the following sections:
  3. In the Oracle 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. Activate your changes.
  4. If you do not want the proxy service to enforce the security policies associated with it, select Passive Security Intermediary under Security Settings 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.

50.4 Configuring Business Service Message-Level Security: Main Steps

Outbound message-level security applies to messages between 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 Console, import the web service's WSDL document into the Service Bus WSDL repository and resolve any WSDL dependencies.

    For more information about WSDL files, see Working with WSDL Documents.

  3. In the Oracle 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 user name and password from this service account. See Working with Service Accounts and Creating and Configuring 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 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. For information about service key providers, see Working with Service Key Providers

  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 Mapping Identity to a SAML Token.
  6. Create a business service from the WSDL file that you imported. Activate your changes.
  7. To attach OWSM policies to the business service, see one of the following sections:
  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.

50.5 Using the Service Identity Certificate Extensions

Service Bus supports publishing and consuming certificate ID extensions for WSDL SOAP proxy and business services attached with OWSM message protection policies.

50.5.1 Publishing Certificate Identity Extension in a Proxy Service Effective WSDL

WSDL SOAP proxy services that implement an OWSM message-protection policy publish the base64-encoded public certificate for the service in the WSDL file. The certificate is included for message protection policies regardless of whether the policy encrypts or decrypts data.

The certificate is based on the encryption key configured for the attached policy. Proxy service clients can use the certificate embedded in the WSDL file for encryption purposes.

For more information, see "Using the Service Identity Certificate Extensions" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

In prior releases of OWSM, business services and clients of proxy services needed to store the proxy service's public certificate in their domain-level keystore.

The client then used the keystore.recipient.alias property to identify the certificate in the keystore.

50.5.2 Consuming Certificate Identity Extension in a Business Service

WSDL SOAP business services that implement an OWSM message-protection policy consume the certificate ID extension from the WSDL file. If the public key certificate is not found in the WSDL file, then the keystore.recipient.alias property is used and the certificate must be in the business service's domain-level keystore.

The hostname verification feature ensures that a certificate retrieved from a WSDL file was not the subject of a substitution attack or "man in the middle" attack and is indeed the expected certificate.

To verify the hostname, OWSM validates that the common name (CN) or the subject Group Base Distinguished Name (DN) in the certificate matches the hostname of the service. This feature depends upon the subject DN of the certificate.

OWSM provides domain configuration properties that enable you to specify whether to enforce web service policies by publishing the X509 certificate in the WSDL file and whether to use the hostname verification feature. For details about setting these properties, see "Configuring Identity Extension Properties Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

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

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

The example is this section 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, Service Bus binds to the WS-Policy statement the encryption certificate from the service key provider that you associate with the proxy service. For more information, see Working with Service Key Providers.

Figure 50-1 Binding a Certificate to an Abstract Policy

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

Also in the example:

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

50.6.2 Example: Encryption Policy for a Business Service

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 Configuring Message-Level Security for Web Services.

The example in this section 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 file uses a URI fragment to refer to the ID.

Example - Encrypting the Body with a Concrete Policy Embedded 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>

50.6.3 Example: Encrypting a Custom SOAP Header

The example in this section 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, Service Bus binds to the WS-Policy statement the encryption certificate from the service key provider that you associate with the proxy service.For more information, see Working with Service Key Providers.

Also of note in this example:

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

50.6.4 Example: Signing the Message Body and Headers

The example in this section 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 - 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>

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

The example in this section 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 Understanding Security for Oracle WebLogic Server.

The "Oracle WebLogic Server Security Policy Assertion Reference" in the 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 - 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>

50.6.6 Example: Authenticating, Signing, and Encrypting with SAML Sender Vouches

The example in this section 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 Understanding Security for Oracle WebLogic Server.

The "Oracle Web Services Security Policy Assertion Reference" in the 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 - 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>

50.7 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. Service Bus handles that behavior automatically and does not use the doOutboundWss property. For more information, see Using OWSM Security with Local Proxy Services.

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

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

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

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