Programming Web Services for WebLogic Server

Configuring Security

The following sections describe how to configure security for your Web Service:

Overview of Web Services Security

To secure your WebLogic Web Service, you configure one or more of three different types of security:

What Type of Security Should You Configure?

Access control security answers the question “who can do what?” First you specify the security roles that are allowed to access a Web Service; a security role is a privilege granted to users or groups based on specific conditions. Then, when a client application attempts to invoke a Web Service operation, the client authenticates itself to WebLogic Server, and if the client has the authorization, it is allowed to continue with the invocation. Access control security secures only WebLogic Server resources. That is, if you configure only access control security, the connection between the client application and WebLogic Server is not secure and the SOAP message is in plain text.

With transport-level security, you secure the connection between the client application and WebLogic Server with Secure Sockets Layer (SSL). SSL provides secure connections by allowing two applications connecting over a network to authenticate the other's identity and by encrypting the data exchanged between the applications. Authentication allows a server, and optionally a client, to verify the identity of the application on the other end of a network connection. Encryption makes data transmitted over the network intelligible only to the intended recipient.

Transport-level security, however, secures only the connection itself. This means that if there is an intermediary between the client and WebLogic Server, such as a router or message queue, the intermediary gets the SOAP message in plain text. When the intermediary sends the message to a second receiver, the second receiver does not know who the original sender was. Additionally, the encryption used by SSL is “all or nothing”: either the entire SOAP message is encrypted or it is not encrypted at all. There is no way to specify that only selected parts of the SOAP message be encrypted.

Message-level security includes all the security benefits of SSL, but with additional flexibility and features. Message-level security is end-to-end, which means that a SOAP message is secure even when the transmission involves one or more intermediaries. The SOAP message itself is digitally signed and encrypted, rather than just the connection. And finally, you can specify that only parts of the message be signed or encrypted.

Configuring Message-Level Security (Digital Signatures and Encryption)

Message-level security specifies whether the SOAP messages between a client application and the Web Service it is invoking should be digitally signed or encrypted or both. It also can specify a shared security context between the Web Service and client in the event that they exchange multiple SOAP messages.

WebLogic Web Services implement the following OASIS Standard 1.0 Web Services Security (WS-Security) specifications, dated April 6, 2004:

These specifications provide security token propagation, message integrity, and message confidentiality. These mechanisms can be used independently (such as passing a username token for user authentication) or together (such as digitally signing and encrypting a SOAP message and specifying that a user must use X.509 certificates for authentication).

WebLogic Web Services also implement the Web Services Trust Language (WS-Trust) and Web Services Secure Conversation Language (WS-SecureConversation) specifications which together provide secure communication between Web Services and their clients (either other Web Services or standalone Java client applications.) In particular, the WS-SecureConversation specification defines mechanisms for establishing and sharing security contexts, and deriving keys from security contexts, to enable a secure conversation. Together, the security context and derived keys potentially increase the overall performance and security of the subsequent exchanges.This functionality is missing from the WS-Security specifications, which focus primarily on the message authentication model and consequently are subject to various security attacks.

You configure message-level security for a Web Service by attaching one or more WS-Policy files that contain security policy statements, as specified by the WS-Policy (dated September 2004) specification. See Using WS-Policy Files for Message-Level Security Configuration for detailed information about how the Web Services runtime environment uses these files.

See Configuring Simple Message-Level Security: Main Steps for the basic steps you must perform to configure simple message-level security. This section discusses configuration of the Web Services runtime environment, as well as configuration of message-level security for a particular Web Service and how to code a client application to invoke the service.

You can also configure message-level security for a Web Service at runtime, after a Web Service has been deployed. See Associating WS-Policy Files at Runtime Using the Administration Console for details.

Main Use Cases of Message-Level Security

The BEA implementation of the Web Services Security: SOAP Message Security specification supports the following use cases:

Using WS-Policy Files for Message-Level Security Configuration

You specify the details of message-level security for a WebLogic Web Service with one or more WS-Policy files. The WS-Policy specification provides a general purpose model and XML syntax to describe and communicate the policies of a Web Service.

The WS-Policy files used for message-level security are XML files that describe whether and how the SOAP messages resulting from an invoke of an operation should be digitally signed or encrypted. They can also specify that a client application authenticate itself using a username, SAML, or X.509 token.

You use the @Policy and @Policies JWS annotations in your JWS file to associate WS-Policy files with your Web Service. You can associate any number of WS-Policy files with a Web Service, although it is up to you to ensure that the assertions do not contradict each other. You can specify a WS-Policy file at both the class- and method-level of your JWS file.

WebLogic Server WS-Policy Files

WebLogic Server includes a set of WS-Policy files that you can specify in your JWS file if you do not want to create your own WS-Policy files; BEA recommends that unless you have specific security needs, you use these pre-packaged files as often as possible. These WS-Policy files are all abstract; see Abstract and Concrete WS-Policy Files for details.

The pre-packaged WS-Policy files are:

Auth.xml

The WebLogic Server Auth.xml file, shown below, specifies that the client application invoking the Web Service must authenticate itself with one of the tokens (username or X.509) that support authentication.

Because the pre-packaged WS-Policy files are abstract, there is no specific username or X.509 token assertions in the Auth.xml file at development-time. Depending on how you have configured security for WebLogic Server, either a username token, an X.509 token, or both will appear in the actual runtime-version of the Auth.xml WS-Policy file associated with your Web Service. Additionally, if the runtime-version of the WS-Policy file includes an X.509 token and it is applied to a client invoke, then the entire body of the SOAP message is signed.

If you want to specify that only X.509, and never username tokens, be used for identity, or want to specify that, when using X.509 for identity, only certain parts of the SOAP message be signed, then you must create a custom WS-Policy file. For details, see Using Only X.509 Certificate Tokens for Identity.

<?xml version="1.0"?>

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

  >

  <wssp:Identity/>

</wsp:Policy>

Sign.xml

The WebLogic Server Sign.xml file specifies that the body and WebLogic-specific system headers of the SOAP message be digitally signed. It also specifies that the SOAP message include a Timestamp, which is digitally signed, and that the token used for signing is also digitally signed. The token used for signing is included in the SOAP message.

The following headers are signed when using the Sign.xml WS-Policy file:

The WebLogic Server Sign.xml file is shown below:

<?xml version="1.0"?>

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

  <wssp:Integrity>

    <wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>

    <wssp:CanonicalizationAlgorithm 
          URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>

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

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

Encrypt.xml

The WebLogic Server Encrypt.xml file specifies that the entire body of the SOAP message be encrypted. By default, the encryption token is not included in the SOAP message.

<?xml version="1.0"?>

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

  <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://schemas.xmlsoap.org/2002/12/wsse#part">
         wsp:Body()
      </wssp:MessageParts>
    </wssp:Target>
    <wssp:KeyInfo/>
  </wssp:Confidentiality>

</wsp:Policy>

Wssc-dk.xml

Specifies that the client and Web Service share a security context, as described by the WS-SecureConversation specification, and that a derived key token is used. This ensures the highest form of security.

This WS-Policy file provides the following configuration:

If you need to change the default security context and derived key behavior, you will have to create a custom WS-Policy file, described in later sections.

<?xml version="1.0"?>

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

  <wssp:Integrity SupportTrust10="true">
    <wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#hmac-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://www.bea.com/wls90/security/policy/wsee#part">
          wls:SystemHeaders()
      </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(wsu:Timestamp)
      </wssp:MessageParts>
    </wssp:Target>

    <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://schemas.xmlsoap.org/ws/2005/02/sc/dk"
        DerivedFromTokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
        <wssp:Claims>
          <wssp:Label>WS-SecureConversationWS-SecureConversation</wssp:Label>
          <wssp:Length>16</wssp:Length>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>

  </wssp:Integrity>

  <wssp:Confidentiality SupportTrust10="true">

    <wssp:Target>
      <wssp:EncryptionAlgorithm URI="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
      <wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()</wssp:MessageParts>
    </wssp:Target>

    <wssp:KeyInfo>
      <wssp:SecurityToken IncludeInMessage="true"
        TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk"
        DerivedFromTokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
        <wssp:Claims>
          <wssp:Label>WS-SecureConversationWS-SecureConversation</wssp:Label>
          <wssp:Length>16</wssp:Length>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:KeyInfo>

  </wssp:Confidentiality>

  <wssp:MessageAge/>

</wsp:Policy>

Wssc-sct.xml

Specifies that the client and Web Service share a security context, as described by the WS-SecureConversation specification. In this case, security context tokens are used to encrypt and sign the SOAP messages, which differs from Wssc-dk.xml in which derived key tokens are used. The Wssc-sct.xml WS-Policy file is provided to support all the use cases of the specification; for utmost security, however, BEA recommends you always use Wssc-dk.xml when specifying shared security contexts due to its higher level of security.

This WS-Policy file provides the following configuration:

If you need to change the default security context and derived key behavior, you will have to create a custom WS-Policy file, described in later sections.

<?xml version="1.0"?>

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

  <wssp:Integrity SupportTrust10="true">
    <wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#hmac-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://www.bea.com/wls90/security/policy/wsee#part">
         wls:SystemHeaders()
      </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(wsu:Timestamp)
      </wssp:MessageParts>
    </wssp:Target>

    <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://schemas.xmlsoap.org/ws/2005/02/sc/sct">
      </wssp:SecurityToken>
    </wssp:SupportedTokens>

  </wssp:Integrity>

  <wssp:Confidentiality SupportTrust10="true">

    <wssp:Target>
      <wssp:EncryptionAlgorithm URI="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
      <wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()</wssp:MessageParts>
    </wssp:Target>

    <wssp:KeyInfo>
      <wssp:SecurityToken IncludeInMessage="true"
        TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
      </wssp:SecurityToken>
    </wssp:KeyInfo>
  </wssp:Confidentiality>

  <wssp:MessageAge />

</wsp:Policy>

Abstract and Concrete WS-Policy Files

The WebLogic Web Services runtime environment recognizes two slightly different types of WS-Policy files: abstract and concrete. The pre-packaged WS-Policy files described in WebLogic Server WS-Policy Files are all abstract.

Abstract WS-Policy files do not explicitly specify the security tokens that are used for authentication, encryption, and digital signatures, but rather, the Web Services runtime environment determines the security tokens when the Web Service is deployed. Specifically, this means the <Identity> and <Integrity> elements (or assertions) of the WS-Policy files do not contain a <SupportedTokens><SecurityToken> child element, and the <Confidentiality> element WS-Policy file does not contain a <KeyInfo><SecurityToken> child element.

If your Web Service is associated with only the pre-packaged WS-Policy files, then client authentication requires username tokens. Web Services support only one type of token for encryption and digital signatures (X.509), which means that in the case of the <Integrity> and <Confidentiality> elements, concrete and abstract WS-Policy files end up being essentially the same.

If your Web Service is associated with an abstract WS-Policy file and it is published as an attachment to the WSDL (which is the default behavior), the static WSDL file packaged in the Web Service archive file (JAR or WAR) will be slightly different than the dynamic WSDL of the deployed Web Service. This is because the static WSDL, being abstract, does not include specific <SecurityToken> elements, but the dynamic WSDL does include these elements because the Web Services runtime has automatically filled them in when it deployed the service. For this reason, in the code that creates the JAX-RPC stub in your client application, ensure that you specify the dynamic WSDL or you will get a runtime error when you try to invoke an operation:

HelloService service = new HelloService(Dynamic_WSDL);

You can specify either the static or dynamic WSDL to the clientgen Ant task in this case. See Browsing to the WSDL of the Web Service for information on viewing the dynamic WSDL of a deployed Web Service.

Concrete WS-Policy files explicitly specify the details of the security tokens at the time the Web Service is programmed. Programmers create concrete WS-Policy files when they know, at the time they are programming the service, the details of the type of authentication (such as using x509 or SAML tokens); whether multiple private key and certificate pairs from the keystore are going to be used for encryption and digital signatures; and so on.

Configuring Simple Message-Level Security: Main Steps

The following procedure describes how to configure simple message-level security for the Web Services security runtime, a particular WebLogic Web Service, and a client application that invokes an operation of the Web Service. In this document, simple message-level security is defined as follows:

Later sections describe some of the preceding scenarios in more detail, as well as additional Web Services security uses cases that build on the simple message-level security use case.

It is assumed in the following procedure that you have already created a JWS file that implements a WebLogic Web Service and you want to update it so that the SOAP messages are digitally signed and encrypted. It is also assumed that you use Ant build scripts to iteratively develop your Web Service and that you have a working build.xml file that you can update with new information. Finally, it is assumed that you have a client application that invokes the non-secured Web Service. If these assumptions are not true, see:

To configure simple message-level security for a WebLogic Web Service:

See the following sections for information about additional Web Service security uses cases that build on the basic message-level security use case:

See Using System Properties to Debug Message-Level Security for information on debugging problems with your message-secured Web Service.

Ensuring That WebLogic Server Can Validate the Client’s Certificate

You must ensure that WebLogic Server is able to validate the X.509 certificate that the client uses to digitally sign its SOAP request, and that WebLogic Server in turn uses to encrypt its SOAP responses to the client. Do one of the following:

For more information, see SSL Certificate Validation.

Updating the JWS File with @Policy and @Policies Annotations

Use the @Policy and @Policies annotations in your JWS file to specify that the Web Service has one or more WS-Policy files attached to it. You can use these annotations at either the class or method level.

The @Policies annotation simply groups two or more @Policy annotations together. Use the @Policies annotation if you want to attach two or more WS-Policy files to the class or method. If you want to attach just one WS-Policy file, you can use @Policy on its own.

The @Policy annotation specifies a single WS-Policy file, where it is located, whether the policy applies to the request or response SOAP message (or both), and whether to attach the WS-Policy file to the public WSDL of the service.

Use the uri attribute to specify the location of the WS-Policy file, as described below:

You can also set the following attributes of the @Policy annotation:

The following example shows how to use the @Policy and @Policies JWS annotations, with the relevant sections shown in bold:

package examples.webservices.security_jws;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Policies;
import weblogic.jws.Policy;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

/**
 *
 */
@WebService(name="SecureHelloWorldPortType",
            serviceName="SecureHelloWorldService",
            targetNamespace="http://www.bea.com")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="SecureHelloWorldService",
                 serviceUri="SecureHelloWorldService",
                 portName="SecureHelloWorldServicePort")

@Policies({
    @Policy(uri="policy:Auth.xml", direction=Policy.Direction.inbound),
    @Policy(uri="policy:Sign.xml"),
    @Policy(uri="policy:Encrypt.xml")})

public class SecureHelloWorldImpl {

  @WebMethod()
  public String sayHello(String s) {
    return "Hello " + s;
  }
}

In the example, three WS-Policy files are attached to the Web Service at the class level, which means that all three WS-Policy files are applied to all public operations of the Web Service. The specified WS-Policy files are those pre-packaged with WebLogic Server, which means that the developers do not need to create their own files or package them in the corresponding archive.

The Auth.xml file is applied to only the request (inbound) SOAP message, as specified by the direction attribute. This means that only the client application needs to provide a username token; when WebLogic Server responds to the invoke, it does not provide a username token. The Sign.xml WS-Policy file specifies that the body and WebLogic system headers of both the request and response SOAP message be digitally signed. The Encrypt.xml policy file specifies that the body of both the request and response SOAP messages be encrypted.

Using Key Pairs Other Than the Out-Of-The-Box SSL Pair

In the simple message-level configuration procedure, documented in Configuring Simple Message-Level Security: Main Steps, it is assumed that the Web Services runtime uses the private key and X.509 certificate pair that is provided out-of-the-box with WebLogic Server; this same key pair is also used by the core security subsystem for SSL and is provided mostly for demonstration and testing purposes. In production environments, the Web Services runtime typically uses its own two private key and digital certificate pairs, one for signing and one for encrypting SOAP messages.

The following procedure describes the additional steps you must take to enable this use case.

Setting the SOAP Message Expiration

The <MessageAge> element in the WS-Policy file specifies whether SOAP messages resulting from an invoke of the Web Service associated with the WS-Policy file have an expiration. WebLogic Server rejects SOAP requests that have expired, based on their expiration time and the creation timestamp, which is included in the message. You can further configure expiration of messages by using the Administration Console to create and update the Web Services security configuration that is associated with the service.

The following bullets describe how the WebLogic Web Services runtime determines the expiration of a SOAP message for a particular Web Service:

It is assumed in the following procedure that you have followed the steps in Configuring Simple Message-Level Security: Main Steps and now want to set the message expiration.

To set the SOAP message expiration:

Creating and Using a Custom WS-Policy File

Although WebLogic Server includes five pre-packaged WS-Policy files that typically satisfy the security needs of most programmers, you can also create and use your own WS-Policy file if you need additional configuration. For example, you must create your own WS-Policy file if you want to:

See Using WS-Policy Files for Message-Level Security Configuration for general information about WS-Policy files and how they are used for message-level security configuration.

When you create a custom WS-Policy file, you can separate out the three main security categories (authentication, encryption, and signing) into three separate WS-Policy files, as do the pre-packaged files, or create a single WS-Policy file that contains all three categories. You can also create a custom WS-Policy file that changes just one category (such as authentication) and use the pre-packaged files for the other categories (Sign.xml and Encrypt.xml). In other words, you can mix and match the number and content of the WS-Policy files that you associate with a Web Service. In this case, however, you must always ensure yourself that the multiple files do not contradict each other.

The root element of your WS-Policy file must be <Policy> and include the following namespace declarations:

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

Defining Child Elements in a Custom WS-Policy File

Define the following child elements of the <Policy> root element in your WS-Policy file (see Security Policy Assertion Reference, for complete reference information about the elements):

See Example of a Custom WS-Policy File for an example of a custom WS-Policy file used to specify SAML tokens for identity. Because the <Integrity> and <Confidentiality> elements do not include <KeyInfo> and <SupportedTokens> child elements, respectively, these sections of the file are abstract. The <Identity> element does include the SAML token, so the identity section is concrete.

You can also use the abstract pre-packaged WS-Policy files as templates to create your own custom files. See:

Example of a Custom WS-Policy File

<<?xml version="1.0"?>

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

  <wssp:Identity>
    <wssp:SupportedTokens>
      <wssp:SecurityToken  TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID">
        <wssp:Claims>
          <wssp:ConfirmationMethod>sender-vouches</wssp:ConfirmationMethod>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>
  </wssp:Identity>

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

  <wssp:MessageAge/>

</wsp:Policy>

Configuring and Using Security Contexts and Derived Keys (WS-SecureConversation)

BEA provides two pre-packaged WS-Policy files (Wssc-dk.xml and Wssc-sct.xml) to configure security contexts and derived keys, as described by the WS-SecureConversation specification. It is highly recommended that you always use the pre-packaged files if you want to configure security contexts, because these two files provide most of the required functionality and typical default values. See Wssc-dk.xml and Wssc-sct.xml for the specific configuration provided by these files.

If, however, the values defined in these WS-Policy files are not adequate for your requirements, then you must create your own custom WS-Policy file. The following sections describe how to customize the configuration of secure contexts and derived keys and how a client application negotiates the security contexts with a Web Service.

Using Custom WS-Policy Files To Configure Security Contexts and Derived Keys

If the pre-packaged WS-Policy files to configure security contexts are not adequate for your requirements, then you must create your own custom WS-Policy file and associate it with your Web Service using the @Policy annotation in your JWS file, or at runtime using the Administration Console. See Creating and Using a Custom WS-Policy File for general information about creating custom WS-Policy files; the remainder of this section describes security context-specific information. BEA recommends you use the pre-packaged Wssc-dk.xml WS-Policy file as a guide and then customize it for your needs.

Follow these guidelines to create a custom security context WS-Policy file:

Updating a Client Application to Negotiate Security Contexts

A client application that negotiates security contexts when invoking a Web Service is similar to a standard client application that invokes a message-secured Web Service, as described in Updating a Client Application to Invoke a Message-Secured Web Service. The only real difference is that you can use the weblogic.wsee.security.wssc.utils.WSSCClientUtil API to explicitly cancel the secure context token.

The following client application shows a simple example of invoking a Web Service that is associated with the pre-packaged Wssc-dk.xml WS-Policy file that enables secure conversations; the sections in bold which are relevant to security contexts are discussed after the example:

package examples.webservices.wssc.client;

import weblogic.security.SSL.TrustManager;

import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.bst.StubPropertyBSTCredProv;
import weblogic.wsee.security.wssc.utils.WSSCClientUtil;
import weblogic.wsee.security.util.CertUtils;

import javax.xml.rpc.Stub;
import java.util.List;
import java.util.ArrayList;

import java.security.cert.X509Certificate;

/**
 *  Copyright (c) 2004 by BEA Systems. All Rights Reserved.
 */
public class WSSecureConvClient {
  public static void main(String[] args) throws Throwable {

    String clientKeyStore = args[0];
    String clientKeyStorePass = args[1];
    String clientKeyAlias = args[2];
    String clientKeyPass = args[3];
    String serverCert = args[4];
    String wsdl = args[5];

    WSSecureConvService service = new WSSecureConvService_Impl(wsdl);
    WSSecureConvPortType port = service.getWSSecureConvServicePort();

    //create credential provider and set it to the Stub
    List credProviders = new ArrayList();

    //use x509 to secure wssc handshake
    credProviders.add(new ClientBSTCredentialProvider(clientKeyStore, clientKeyStorePass, clientKeyAlias, clientKeyPass));

    Stub stub = (Stub)port;

    stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);
    stub._setProperty(StubPropertyBSTCredProv.SERVER_ENCRYPT_CERT, CertUtils.getCertificate(serverCert));

    stub._setProperty(WSSecurityContext.TRUST_MANAGER,
        new TrustManager(){
          public boolean certificateCallback(X509Certificate[] chain, int validateErr){
            //need to validate if the server cert can be trusted
            return true;
          }
        }
    );

    System.out.println (port.sayHelloWithWSSC("Hello World, once"));
    System.out.println (port.sayHelloWithWSSC("Hello World, twice"));
    System.out.println (port.sayHelloWithWSSC("Hello World, thrice"));

    //cancel SecureContextToken after done with invocation
    WSSCClientUtil.terminateWssc(stub);
    System.out.println("WSSC terminated!");

  }

}

The points to notice in the preceding example are:

Associating WS-Policy Files at Runtime Using the Administration Console

The simple message-level configuration procedure, documented in Configuring Simple Message-Level Security: Main Steps, describes how to use the @Policy and @Policies JWS annotations in the JWS file that implements your Web Service to specify one or more WS-Policy files that are associated with your service. This of course implies that you must already know, at the time you program your Web Service, which WS-Policy files you want to associate with your Web Service and its operations. This might not always be possible, which is why you can also associate WS-Policy files at runtime, after the Web Service has been deployed, using the Administration Console.

You can use no @Policy or @Policies JWS annotations at all in your JWS file and associate WS-Policy files only at runtime using the Administration Console, or you can specify some WS-Policy files using the annotations and then associate additional ones at runtime. However, once you associate a WS-Policy file using the JWS annotations, you cannot change this association at runtime using the Administration Console.

At runtime, the Administration Console allows you to associate as many WS-Policy files as you want with a Web Service and its operations, even if the policy assertions in the files contradict each other or contradict the assertions in WS-Policy files associated with the JWS annotations. It is up to you to ensure that multiple associated WS-Policy files work together. If any contradictions do exist, WebLogic Server returns a runtime error when a client application invokes the Web Service operation.

See Associate a WS-Policy file with a Web Service for detailed instructions on using the Administration Console to associate a WS-Policy file at runtime.

Using Security Assertion Markup Language (SAML) Tokens For Identity

In the simple Web Services configuration procedure, described in Configuring Simple Message-Level Security: Main Steps, it is assumed that users use username tokens to authenticate themselves. Because WebLogic Server implements the Web Services Security: SAML Token Profile of the Web Services Security specification, users can also use SAML tokens in the SOAP messages to authenticate themselves when invoking a Web Service operation, as described in this section.

Use of SAML tokens works server-to-server. This means that the client application is running inside of a WebLogic Server instance and then invokes a Web Service running in another WebLogic Server instance using SAML for identity. Because the client application is itself a Web Service, the Web Services security runtime takes care of all the SAML processing.

When you configure a Web Service to require SAML tokens for identity, you can specify one of the following confirmation methods:

See SAML Token Profile Support in WebLogic Web Services, as well as the Web Services Security: SAML Token Profile specification itself, for details about these confirmation methods.

To use SAML tokens for identity, follow these steps:

Using Only X.509 Certificate Tokens for Identity

In the simple Web Services configuration procedure, described in Configuring Simple Message-Level Security: Main Steps, it is assumed that users use either username tokens, X.509 tokens, or both, to authenticate themselves. This is because it is assumed that users associate the Auth.xml pre-packaged WS-Policy file to their Web Service; because Auth.xml is abstract, the exact tokens that appear in the deployed WS-Policy file depend on how you have configured WebLogic Server, and thus it is undefined at the time you program the Web Service which tokens will actually be used for identity.

If, however, you want to specify that users authenticate themselves using only X.509 certificates when invoking a Web Service, and thus explicitly exclude username tokens from the WS-Policy file, then you cannot use Auth.xml and must instead create a custom WS-Policy file, as described in the following procedure. You must also use this procedure if you want to specify the parts of the SOAP message that are signed; by default, Auth.xml, when using X.509 for identity, also signs the entire SOAP body. Use the <Integrity> assertion to specify parts that should be signed.

Using a Password Digest In the SOAP Message Rather Than Plaintext

By default, the WebLogic Web Services security runtime uses cleartext passwords, rather than the password digest, in the SOAP messages resulting from an invoke of a message-secured Web Service. The following procedure shows how to change this default behavior so that the SOAP messages use the password digest.

It is assumed in the following procedure that you have followed the steps in Configuring Simple Message-Level Security: Main Steps and now want to specify that all SOAP messages use password digest rather than cleartext.

Associating a Web Service with a Security Configuration Other Than the Default

Many use cases previously discussed require you to use the Administration Console to create the default Web Service security configuration called default_wss. After you create this configuration, it is applied to all Web Services that either do not use the @weblogic.jws.security.WssConfiguration JWS annotation or specify the annotation with no attribute.

There are some cases, however, in which you might want to associate a Web Service with a security configuration other than the default; such use cases include specifying different timestamp values for different services.

To associate a Web Service with a security configuration other than the default:

Using System Properties to Debug Message-Level Security

The following table lists the system properties you can set to debug problems with your message-secured Web Service.

Updating a Client Application to Invoke a Message-Secured Web Service

When you update your Java code to invoke a message-secured Web Service, you must load a private key and digital certificate pair from the client’s keystore and pass this information, along with a username and password for user authentication if so required by the WS-Policy, to the secure WebLogic Web Service being invoked.

If the WS-Policy file of the Web Service specifies that the SOAP request must be encrypted, then the Web Services client runtime automatically gets the server’s certificate from the WS-Policy file that is attached to the WSDL of the service, and uses it for the encryption. If, however, the WS-Policy file is not attached to the WSDL, or the entire WSDL itself is not available, then the client application must use a client-side copy of the WS-Policy file; for details, see Using a Client-Side Security WS-Policy File.

The following example shows a Java client application that invokes the message-secured WebLogic Web Service described by the JWS file in Updating the JWS File With the Security-Related Annotations. The client application takes five arguments:

The security-specific code in the sample client application is shown in bold (and described after the example):

package examples.webservices.security_jws.client;

import weblogic.security.SSL.TrustManager;

import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;

import javax.xml.rpc.Stub;
import java.util.List;
import java.util.ArrayList;

import java.security.cert.X509Certificate;

/**
 *  Copyright (c) 2005 by BEA Systems. All Rights Reserved.
 */
public class SecureHelloWorldClient {
  public static void main(String[] args) throws Throwable {

    //username or password for the UsernameToken
    String username = args[0];
    String password = args[1];

    //client private key file
    String keyFile = args[2];

    //client certificate
    String clientCertFile = args[3];

    String wsdl = args[4];

    SecureHelloWorldService service = new SecureHelloWorldService_Impl(wsdl + "?WSDL" );

    SecureHelloWorldPortType port = service.getSecureHelloWorldServicePort();

    //create credential provider and set it to the Stub
    List credProviders = new ArrayList();

    //client side BinarySecurityToken credential provider -- x509
    CredentialProvider cp = new ClientBSTCredentialProvider(clientCertFile, keyFile);
    credProviders.add(cp);

    //client side UsernameToken credential provider
    cp = new ClientUNTCredentialProvider(username, password);
    credProviders.add(cp);

    Stub stub = (Stub)port;
    stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);

    stub._setProperty(WSSecurityContext.TRUST_MANAGER,
      new TrustManager(){
         public boolean certificateCallback(X509Certificate[] chain, int validateErr){
           return true;
         }
       } );

    String response = port.sayHello("World");
    System.out.println("response = " + response);
  }
}

The main points to note about the preceding code are:

Invoking a Message-Secured Web Service From a Client Running in a WebLogic Server Instance

In the simple Web Services configuration procedure, described in Configuring Simple Message-Level Security: Main Steps, it is assumed that a stand-alone client application invokes the message-secured Web Service. Sometimes, however, the client is itself running in a WebLogic Server instance, as part of an EJB, servlet, or another Web Service. In this case, you can use the core WebLogic Server security framework to configure the credential providers and trust manager so that your EJB, servlet, or JWS code contains only the simple invoke of the secured operation and no other security-related API usage. The following procedure describes the high level steps you must perform to make use of the core WebLogic Server security framework in this use case.

You are not required to configure the core WebLogic Server security framework, as described in this procedure, if your client application does not want to use the out-of-the-box credential provider and trust manager. Rather, you can override all of this configuration by using the same APIs in your EJB, servlet, and JWS code as in the stand-alone Java code described in Updating a Client Application to Invoke a Message-Secured Web Service. However, using the core security framework standardizes the WebLogic Server configuration and simplifies the Java code of the client application that invokes the Web Service.

Configuring Transport-Level Security

Transport-level security refers to securing the connection between a client application and a Web Service with Secure Sockets Layer (SSL).

See Secure Sockets Layer (SSL) for general information about SSL and the implementations included in WebLogic Server.

To configure transport-level Web Services security:

Configuring Two-Way SSL for a Client Application

If you configured two-way SSL for WebLogic Server, the client application must present a certificate to WebLogic Server, in addition to WebLogic Server presenting a certificate to the client application as required by one-way SSL. You must also follow these requirements:

Additional Web Services SSL Examples

The dev2dev CodeShare is a community of developers that share ideas, code and best practices related to BEA technologies. The site includes code examples for a variety of BEA technologies, including using SSL with Web Services.

To view and download the SSL Web Services code examples on the dev2dev site, go to the main Projects page and click on Web Services in the By Technology column.

Configuring Access Control Security: Main Steps

Access control security refers to configuring the Web Service to control the users who are allowed to access it, and then coding your client application to authenticate itself, using HTTP/S or username tokens, to the Web Service when the client invokes one of its operations.

You specify access control security for your Web Service by using one or more of the following annotations in your JWS file:

The following procedure describes the high-level steps to use these annotations to enable access control security; later sections in the chapter describe the steps in more detail.

Updating the JWS File With the Security-Related Annotations

Use the WebLogic-specific @weblogic.jws.security.RolesAllowed annotation in your JWS file to specify an array of @weblogic.jws.security.SecurityRoles annotations that list the roles that are allowed to invoke the Web Service. You can specify these two annotations at either the class- or method-level. When set at the class-level, the roles apply to all public operations. You can add additional roles to a particular operation by specifying the annotation at the method level.

The @SecurityRole annotation has the following two attributes:

The @RolesAllowed annotation does not have any attributes.

You can also use the @weblogic.jws.security.RolesReferenced annotation to specify an array of @weblogic.jws.security.SecurityRoleRef annotations that list references to existing roles. For example, if the role manager is already allowed to invoke the Web Service, you can specify that the mgr role be linked to the manager role and any user mapped to mgr is also able to invoke the Web Service. You can specify these two annotations only at the class-level.

The @SecurityRoleRef annotation has the following two attributes:

The @RolesReferenced annotation does not have any attributes.

The following example shows how to use the annotations described in this section in a JWS file, with the relevant sections shown in bold:

package examples.webservices.security_roles;

import javax.jws.WebMethod;
import javax.jws.WebService;

// WebLogic JWS annotations

import weblogic.jws.WLHttpTransport;

import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.RolesReferenced;
import weblogic.jws.security.SecurityRole;
import weblogic.jws.security.SecurityRoleRef;

@WebService(name="SecurityRolesPortType",
            serviceName="SecurityRolesService",
            targetNamespace="http://example.org")

@WLHttpTransport(contextPath="security", 
                 serviceUri="SecurityRolesService",
                  portName="SecurityRolesPort")

@RolesAllowed (  {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )

@RolesReferenced (
    @SecurityRoleRef (role="mgr", link="manager")
)

/**
 * This JWS file forms the basis of simple Java-class implemented WebLogic
 * Web Service with a single operation: sayHello
 *
 */

public class SecurityRolesImpl {

  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";

  }

}

The example shows how to specify that only the manager, vp, and mgr roles are allowed to invoke the Web Service. The mgr role is actually a reference to the manager role. The users juliet and amanda are mapped to the manager role within the context of the Web Service. Because no users are mapped to the vp role, it is assumed that the mapping occurs externally, typically using the Administration Console to update the WebLogic Server security realm.

See JWS Annotation Reference, for reference information on these annotations.

Updating the JWS File With the @RunAs Annotation

Use the WebLogic-specific @weblogic.jws.security.RunAs annotation in your JWS file to specify that the Web Service is always run as a particular role. This means that regardless of the user, and the role to which the user is mapped, initially invokes the Web Service, the service is internally executed as the specified role.

You can set the @RunAs annotation only at the class-level. The annotation has the following attributes:

The following example shows how to use the @RunAs annotation in a JWS file, with the relevant sections shown in bold:

package examples.webservices.security_roles;

import javax.jws.WebMethod;
import javax.jws.WebService;

// WebLogic JWS annotations

import weblogic.jws.WLHttpTransport;

import weblogic.jws.security.RunAs;

@WebService(name="SecurityRunAsPortType",
            serviceName="SecurityRunAsService",
            targetNamespace="http://example.org")

@WLHttpTransport(contextPath="security_runas",
                 serviceUri="SecurityRunAsService",
                 portName="SecurityRunAsPort")

@RunAs (role="manager", mapToPrincipal="juliet")

/**
 * This JWS file forms the basis of simple WebLogic
 * Web Service with a single operation: sayHello
 *
 */

public class SecurityRunAsImpl {

  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

Setting the Username and Password When Creating the JAX-RPC Service Object

When you use the @RolesAllowed JWS annotation to secure a Web Service, only the specified roles are allowed to invoke the Web Service operations. This means that you must specify the username and password of a user that maps to the role when creating the JAX-RPC Service object in your client application that invokes the protected Web Service.

WebLogic Server provides the HttpTransportInfo class for setting the username and password and passing it to the Service constructor. The following example is based on the standard way to invoke a Web Service from a standalone Java client (as described in Invoking Web Services) but also shows how to use the HttpTransportInfo class to set the username and password. The sections in bold are discussed after the example.

package examples.webservices.sec_wsdl.client;

import weblogic.wsee.connection.transport.http.HttpTransportInfo;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
 * This is a simple standalone client application that invokes the
 * the <code>sayHello</code> operation of the SecWsdlService Web service.
 *
 * @author Copyright (c) 2004 by BEA Systems. All Rights Reserved.
 */

public class Main {

  public static void main(String[] args)
      throws ServiceException, RemoteException{

    HttpTransportInfo info = new HttpTransportInfo();
    info.setUsername("juliet".getBytes());
    info.setPassword("secret".getBytes());

    SecWsdlService service = new SecWsdlService_Impl(args[0] + "?WSDL", info);
    SecWsdlPortType port = service.getSecWsdlPort();

    try {
      String result = null;
      result = port.sayHello("Hi there!");
      System.out.println( "Got result: " + result );
    } catch (RemoteException e) {
      throw e;
    }
  }

}

The main points to note in the preceding example are as follows:

See Invoking Web Services, for general information about invoking a non-secured Web Service.