> Security Guide > Configuring Message-Level Security for Web Services

Security Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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. To provide message-level security, AquaLogic Service Bus implements the features that are defined in the OASIS standard for Web Services Security (WS-Security).

In this release of AquaLogic Service Bus, the implementation of message-level security has been expanded to include proxy services that have been configured with message-level custom authentication (either custom token or username/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 Username/Password and Tokens for information about using both types of security.

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

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, 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 inbound authentication and authorization.

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.

AquaLogic Service Bus supports the following WS-Security token profiles:

To send a SOAP message to a proxy service that requires message-level security, 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. When the proxy service processes the secured envelope, it decrypts the message, which removes the security header. 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.

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

For more information about WS-Security (which is the OASIS standard that defines message-level security), see Web Services Security: SOAP Message Security 1.0 (WS-Security 2004) at the following URL:
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

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 that contain tokens that can be mapped to a specific list of authorized users.

 

Configuring Inbound Message-Level Security

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

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. To express the proxy service’s message-level security requirements attach one or more Web Services Policy (WS-Policy) statements to the WSDL document.

    2. A WS-Policy statement is an XML statement that expresses a message-level security requirement (assertion). For example, one WS-Policy statement might contain an assertion that requires clients to supply a digital signature. AquaLogic Service Bus includes a set of WS-Policy statements that you can use.

    If the AquaLogic Service Bus WS-Policy statements do not meet your security needs, you can write your own WS-Policy statements (custom WS-Policy statements) and import them into the AquaLogic Service Bus WS-Policy repository.

    See Using Web Services Policy to Specify Inbound Message-Level Security.

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

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

  3. If you have not already configured the WebLogic security framework to support AquaLogic Service Bus, do one or more of the following depending on the whether the WSDL document contains WS-Policy statements 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 Inbound 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 proxy service provider that contains an encryption credential. The proxy service will use this credential to decrypt the encrypted SOAP message. See “Adding a Proxy Service Provider” in Proxy Service Providers in Using the AquaLogic Service Bus Console.
  4. In the AquaLogic Service Bus Console, do one or more of the following depending whether the WSDL document contains WS-Policy statements that secure responses from the proxy service to clients:
    • If any operation response policy requires digital signatures, configure a proxy service provider that contains a digital signature credential. You can create one proxy service provider that contains credentials for both encryption and digital signatures. See “Adding a Proxy Service Provider” in Proxy Service 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.
  5. In the AquaLogic Service Bus Console, create a proxy service from the WSDL that you imported in step 1. While you are creating the proxy service, do the following:
    • On the General Configuration page, specify the proxy service provider that you created in step 4.
    • On the Message-Level Security Configuration page, select the Process WS-Security Header check box.

      • See Proxy Services in Using the AquaLogic Service Bus Console.

  6. In the AquaLogic Service Bus Console, 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.

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. The business service must be a Web service that contains WS-Policy statements.

    2. See Configuring Outbound Message-Level Security: Main Steps.

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

    3. While you are creating the proxy service:

    • Do not select the Process WS-Security Header check box on the Message-Level Security Configuration page.
    • 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.

  3. In the AquaLogic Service Bus Console, modify the proxy service’s default message-level access control policy, which specifies conditions under which users, groups, or roles can use the proxy service to route to the business service. See “Editing Message-Level Access Policies” under Security Configuration in Using the AquaLogic Service Bus Console.

 

Configuring Outbound 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:

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

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

    The WSDL document must express message-level security requirements with one or more Web Services Policy (WS-Policy) statements. If the Web service requires digital encryption, you must create a custom WS-Policy statement that embeds the encryption certificate and this WS-Policy statement must be located in the Web service’s WSDL document (it cannot be included by reference).

  2. 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 proxy service provider that contains a digital signature credential. You can create one proxy service provider that contains credentials for both encryption and digital signatures. See “Adding a Proxy Service Provider” in Proxy Service Providers in Using the AquaLogic Service Bus Console.
  3. 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 proxy service provider and assign an encryption credential to the proxy service provider. See “Adding a Proxy Service Provider” in Proxy Service Providers in Using the AquaLogic Service Bus Console.
    4. 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.
  4. 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.
  5. In the AquaLogic Service Bus Console, create a business service from the WSDL that you imported in step 1.

    6. See Business Services in Using the AquaLogic Service Bus Console.

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

    7. See Creating an Active Intermediary Proxy Service: Main Steps or Creating a Pass-Through Proxy Service: Main Steps.

Disabling Outbound 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:

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.


  Back to Top       Previous  Next