Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Programming WebLogic Web Services > Configuring Security

Programming WebLogic Web Services

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Configuring Security

The following sections describe how to configure security for WebLogic Web Services:

 

Overview of Web Services Security

To secure your WebLogic Web Service, you configure one or more of three conceptually 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 list of users, groups, or roles that are allowed to access a Web Service (or the component that implement the Web Service). Then, when a client application attempts to invoke a Web Service operation, the client authenticates itself to WebLogic Server, using HTTP, and if the client has the authorization, it is allowed to continue with the invocation. Access control security secures only WebLogic Server resources. This means that 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.

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

These specifications provide three main mechanisms: security token propagation, message integrity, and message confidentiality. These mechanisms can be used independently (such as passing a username security token for user authentication) or together (such as digitally signing and encrypting a SOAP message.)

The following sections provide information about message-level security:

Main Use Cases

BEA's implemenation of the Web Services Security: SOAP Message Security specification is designed to fully support the following use cases:

Unimplemented Features of the Web Services Security Core Specification

WebLogic Web Services do not implement all features of the Web Services Security Core specification as follows:

Terminology

Note the following terms:

Architectural Overview of Message-Level Security

The <security> element of the web-services.xml deployment descriptor file specifies whether a WebLogic Web Service has been configured for message-level security. In particular, the <security> element describes:

When the Web Service is deployed, the security information specified in the web-services.xml file is published in the WSDL so that client applications that invoke the Web Service know whether they need to digitally sign or encrypt the SOAP messages.

Note: Because WSDL 1.1 does not include a standard for specifying security information, the way that WebLogic Server publishes its message-level security information is proprietary.

The following diagram and paragraphs describe what happens when a message-secured WebLogic Web Service is deployed and a client application invokes it. The paragraphs are broken up according to the actor that performs the action.

Figure 13-1 Message-Secured WebLogic Web Service Architecture

Message-Secured WebLogic Web Service Architecture


 

A. WebLogic Server

  1. Loads the key pairs and certificates from WebLogic Server's identity keystore.
  2. Deploys the message-secured Web Service, using information from the web-services.xml deployment descriptor, such as which operations require what type of message-level security.
  3. Updates the WSDL of the Web service with security information so that client applications that invoke the Web Service know what security processing needs to occur on the SOAP request. This security information includes the certificate for WebLogic Server's encryption key pair, used by the client application to encrypt the SOAP request. WebLogic Server uses the information in the <security> element of the web-services.xml deployment descriptor file to determine how it should update the WSDL.

B. Client Application

The client application loads the signature key pair and certificate from its client keystore and uses the weblogic.webservice.context.WebServiceContext API to add the public key and certificate as attributes to the Web Service session.

Note: The client application uses the key pair and certificate loaded from its client keystore to digitally sign the SOAP request. WebLogic Server later uses the key pair and certificate to encrypt the SOAP response.

C. WebLogic Web Services Client Runtime Environment

When the client application is executed, the Web Services client runtime environment, packaged in the client runtime JAR files, performs the following tasks:

Note: The client runtime performs all encryption and signature tasks directly before it sends the request to WebLogic Server and after all client handlers have executed.

  1. Reads the WSDL of the Web Service being invoked to determine what parts of the SOAP request should be digitally signed or encrypted. The client runtime also gets the certificate for the server encryption key from the WSDL.
  2. Generates the unsecured SOAP message request.
  3. Creates a <Security> element in the header of the SOAP request that will contain the security information.
  4. If required by the WSDL, inserts a username token with the client's username and password into the <Security> header of the SOAP request.
  5. If the WSDL requires that the SOAP request be digitally signed, the Web Services client runtime environment:
    1. Generates a digital signature, according to the WSDL requirements, using the private key from the client's WebServiceContext.
    2. Adds the digital signature to the <Security> header of the SOAP request.
    3. Adds the certificate from the client's WebServiceContext to the <Security> header of the SOAP request. WebLogic Server later uses this certificate to verify the signature.
  6. If the WSDL requires that the SOAP request be encrypted, the Web Services client runtime environment:
    1. Gets WebLogic Server's public encryption key from the certificate published in the WSDL.
    2. Encrypts the SOAP request according to the requirements in the WSDL using WebLogic Server's public encryption key. The WSDL specifies what part of the SOAP message should be encrypted.
    3. Adds a description of the encryption to the <Security> header of the SOAP request. WebLogic Server later uses this description to decrypt the SOAP request.
  7. The Web Services client runtime sends the encrypted and signed SOAP request to WebLogic Server.

D. WebLogic Server

  1. Receives the SOAP request and extracts the <Security> header.
  2. If the SOAP request has been encrypted, WebLogic Server:
    1. Reads the description of the encryption and decrypts the SOAP request using WebLogic Server's private encryption key from its identity keystore.
    2. Removes the encryption description from the <Security> header.
  3. If the SOAP request has been digitally signed, WebLogic Server performs the following tasks to verify the signature:
    1. Extracts the client's certificate from the <Security> header of the SOAP request.
    2. Extracts the digital signature from the <Security> header.
    3. Verifies the signature using the client's public key, obtained from the client's certificate.
    4. Asserts the identity of the client certificate to ensure that it maps to a valid WebLogic Server user.
    5. Removes the signature from the <Security> header.
  4. Extracts, if present, the username token from the <Security> header.
  5. Asserts the identity of the user and verifies their password. The rest of the invocation of the Web Service operation is run as this user.
  6. Removes the <Security> header from the SOAP request.
  7. Saves the client certificate that was included in the SOAP request for encrypting the SOAP response, if required.
  8. Verifies that the specifications in the <Security> header matched the requirements in the WSDL.
  9. Sends the post-processed SOAP request to the Web Services runtime for standard invocation.

When WebLogic Server sends the SOAP response back to the client, and it is required to digitally sign or encrypt the SOAP response, it follows the same steps as the WebLogic Web Services client runtime environment did when it initially sent its SOAP request (see C. WebLogic Web Services Client Runtime Environment), but with the following differences:

Configuring Message-Level Security: Main Steps

Configuring message-level security for a WebLogic Web Service involves some standard security tasks, such as obtaining digital certificates, creating keystores, and users, as well as Web Service-specific tasks, such as updating the web-services.xml file with security information.

To configure message-level security for a WebLogic Web Service and a client that invokes the service, follow these steps. Later sections describe some steps in more detail.

Note: The following procedure assumes that you have already implemented and assembled a WebLogic Web Service and you want to update it to use digital signatures and encryption.

  1. Obtain two sets of key pair and digital certificates to be used by WebLogic Web Services. Although not required, BEA recommends that you obtain key pairs and certificates that will be used only by WebLogic Web Services.

    2. Warning: BEA requires that the key length be 1024 bits or larger.

    For clarity, it is assumed that the key pair/certificate used for digital signatures has a name digSigKey and password digSigKeyPassword and the one used for encryption has a name encryptKey and password encryptKeyPassword.

    You can use the Cert Gen utility or Sun Microsystem's keytool utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.

    For details, see Obtaining Private Keys and Digital Signatures.

  2. Create, if one does not currently exist, a custom identity keystore for WebLogic Server and load the key pairs and digital certificates you obtained in the preceding step into the identity keystore.

    3. If you have already configured WebLogic Server for SSL, then you have already created a identity keystore which you can also use for WebLogic Web Services data security purposes.

    You can use WebLogic's ImportPrivateKey utility and Sun Microsystem's keytool utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.

    For details, see Creating a Keystore and Loading Key Pairs Into the Keystore.

  3. Using the Administration Console, configure WebLogic Server to locate the keystore you created in the preceding step. If you are using a keystore that has already been configured for WebLogic Server, you do not need to perform this step.

    4. For details, see Configuring Keystores.

  4. Create a keystore used by the client application. BEA recommends that you create one client keystore per application user.

    5. You can use the Cert Gen utility or Sun Microsystem's keytool utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.

    Later sections of this document assume you created a client keystore called client_keystore with password client_keystore_password.

    For details, see Obtaining Private Keys and Digital Signatures.

  5. Create a key pair and a digital certificate, and load them into the client keystore. The same key pair will be used to digitally sign the SOAP request and encrypt the SOAP responses. The digital certificate will be mapped to a user of WebLogic Server, created in a later step.

    6. Warning: BEA requires that the key length be 1024 bits or larger.

    You can use Sun Microsystem's keytool utility to perform this step.

    Later sections of this document assume you created a key pair called client_key with password client_key_password.

  6. Using the Administration Console, configure an Identity Asserter provider for your WebLogic Server security realm.

    7. WebLogic Server provides a default security realm, called myrealm, which is configured with a default Identity Asserter provider. Use this default security realm if you do not want to configure your own Identity Asserter provider. You must, however, perform additional configuration tasks to ensure that the default Identity Asserter Provider works correctly with message-secured WebLogic Web Services.

    For details, see Configuring The Identity Asserter Provider for the myrealm Security Realm.

  7. Using the Administration Console, create users for authentication in your security realm.

    8. For details, see Creating Users.

    Later sections of this guide assume you created a user auth_user with password auth_user_password.

  8. Update the build.xml file that contains the call to the servicegen Ant task by adding the <security> child element to the <service> element that builds your Web Service. Specify information such as the encryption key pair, the digital signature key pair, and their corresponding passwords.

    9. Note: The servicegen Ant task offers only course-grained control of the encryption and digital signature configuration for a Web Service. For more fine-grained control of the data in the SOAP message that is encrypted or digitally signed, you must update the web-services.xml file manually. For details, see Updating Security Information in the web-services.xml File.

    For details about using servicegen, see Updating the servicegen build.xml File.

  9. Re-run the servicegen Ant task to re-assemble your Web Service and regenerate the web-services.xml deployment descriptor.
  10. Optionally encrypt the various passwords in the web-services.xml file of the EAR for your domain before deploying the EAR file to WebLogic Server. Typically you perform this step only when you deploy your Web Service in production mode.

    11. For details, see Encrypting Passwords in the web-services.xml File.

  11. Update your client application to invoke the message-secured Web Service.

    12. For details, see Updating a Java Client to Invoke a Data-Secured Web Service.

Configuring The Identity Asserter Provider for the myrealm Security Realm

You can use the default Identity Asserter provider, configured for the default myrealm security realm, with message-secured WebLogic Web Services. You must, however, perform some additional configuration tasks:

  1. In the left pane of the Administration Console, expand the Security—>Realms—>myrealm—>Providers—>Authentication folder.
  2. Click DefaultIdentityAsserter under the Authentication folder. The page to configure the default Identity Asserter appears in the right pane, open to the General tab.
  3. In the right pane, scroll down to the Types box.
  4. Move X.509 from the Available box to the Chosen box.
  5. Click Apply.
  6. Select the Details tab.
  7. Ensure that Use Default User Name Mapper is checked.
  8. Select the Default User Name Mapper Attribute Type used when mapping the X.509 digital certificate to a user name.
  9. Select the Default User Name Mapper Attribute Delimiter.
  10. Click Apply.

For additional information about configuring the Identity Asserter, see:

Updating the servicegen build.xml File

Update the build.xml file that contains the call to the servicegen Ant task by adding a <security> child element to the <service> element that builds your Web Service, as shown in the following example. By default, servicegen specifies that the entire SOAP body will be digitally signed or encrypted, rather than specific elements. Later sections describe how to digitally sign or encrypt specific elements.

Note: For clarity, the following excerpt of servicegen's build.xml file contains passwords in clear text. However, for security reasons, BEA recommends that you update your build.xml file to prompt for the passwords, using the <input> Ant task, rather than actually store the passwords in the file. For details on using the <input> Ant task, see Apache Ant User Manual.

      <servicegen
         destEar="ears/myWebService.ear"
         warName="myWAR.war" 
         contextURI="web_services" >
         <service
             ejbJar="jars/myEJB.jar"
             targetNamespace="http://www.bea.com/examples/Trader"
             serviceName="TraderService"
             serviceURI="/TraderService"
             generateTypes="True"
             expandMethods="True" >
             <security
                     signKeyName="digSigKey"
                     signKeyPass="digSigKeyPassword"
                     encryptKeyName="encryptKey"
                     encryptKeyPass="encryptKeyPassword"
             />
         </service>
     </servicegen>

The preceding build.xml file specifies that servicegen assemble a Web Service that includes the following message-level security information in the web-services.xml deployment descriptor file:

Note: Always encrypt the passwords in the web-services.xml file with the weblogic.webservice.encryptpass utility, described in Encrypting Passwords in the web-services.xml File.

If you use the <security> element of the servicegen Ant task to add security to your Web Service, the entire SOAP body is encrypted and digitally signed for all operations of the Web Service. The encryption and digital signatures occur for both the request and response SOAP messages.

If you want more fine-grained control, such as specifying particular elements of the SOAP message to be digitally signed or encrypted, a subset of operations that have message-level security, and so on, update the web-services.xml file of your WebLogic Web Service manually. For details, see Updating Security Information in the web-services.xml File.

Updating Security Information in the web-services.xml File

The servicegen Ant task adds minimal default message-level security information to the generated web-services.xml deployment descriptor file. In particular, the default information specifies that, for all operations of the Web Service, the entire body of the SOAP messages be digitally signed or encrypted, rather than specific elements. This default behavior is adequate in many cases; however, you might sometimes want to specify just a subset of the elements to be digitally signed or encrypted, as well as specify different security specifications for different operations. In this case, you must update the web-services.xml file manually.

If you use the build.xml file in Updating the servicegen build.xml File to run servicegen, the following example shows the resulting <security> element in the generated web-services.xml file; the sections in bold are described after the example:

<web-service>
...
  <security>
    <signatureKey>
      <name>digSigKey</name>
      <password>digSigKeyPassword</password>
    </signatureKey>
    <encryptionKey>
      <name>encryptKey</name>
      <password>encryptKeyPassword</password>
    </encryptionKey>
    <spec:SecuritySpec xmlns:spec="http://www.openuri.org/2002/11/wsse/spec"
                       Namespace="http://schemas.xmlsoap.org/ws/2002/07/secext"
                       Id="default-spec">
      <spec:BinarySecurityTokenSpec   
                      xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
                      EncodingType="wsse:Base64Binary"
                      ValueType="wsse:X509v3">
      </spec:BinarySecurityTokenSpec>
      <spec:SignatureSpec   
             SignatureMethod="http://www.w3.org/2000/09/xmldsig#rsa-sha1"
             SignBody="true"
             CanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
      </spec:SignatureSpec>
      <spec:EncryptionSpec    
            EncryptBody="true"
            EncryptionMethod="http://www.w3.org/2001/04/xmlenc#tripledes-cbc">
      </spec:EncryptionSpec>
    </spec:SecuritySpec>
  </security>
  ...
  <operations>
      <operation 
             name="myOperation" method="myMethod" component="ejbComp"
             in-security-spec="default-spec" out-security-spec="default-spec">
      ...
      </operation>
  </operations>
  ...
</web-service>

Note: The spec prefix in the preceding example is a namespace prefix that is required for the security information in the web-services.xml deployment descriptor file. For more information about XML namespaces, see Namespaces in XML.

The <signatureKey> and <encryptKey> elements in the preceding web-services.xml excerpt specify the username and passwords used to retrieve the keys for digital signatures and encryption, respectively, from the server's keystore.

The Id="default-spec" attribute of the <spec:SecuritySpec> element specifies that it is the default security specification. By default, the SOAP requests and responses for invokes of all operations of the Web Service must follow the security information described by this security specification; this is specified with the in-security-spec="default-spec" and out-security-spec="default-spec" attributes of each <operation> element.

The SignBody="true" and EncryptBody="true" attributes of the <spec:SignatureSpec> and <spec:EncryptionSpec> elements specify that the entire body of the SOAP messages for all operations must be digitally signed and encrypted.

The following sections describe how to update the web-services.xml file to specify more fine-grained message-level security:

Digitally Signing or Encrypting a Particular Element in the SOAP Message

To specify particular elements to be digitally signed or encrypted, add one or more <spec:ElementIdentifier> child elements to the <spec:SignatureSpec> or <spec:EncryptionSpec> element, respectively, in the web-services.xml file.

For example, assume that, in addition to the entire SOAP body, you want to digitally sign an element in the SOAP header whose local name is Timestamp. To specify this configuration, add a <spec:ElementIdentifier> child element to the <spec:SignatureSpec> element as shown:

<spec:SignatureSpec   
         SignatureMethod="http://www.w3.org/2000/09/xmldsig#rsa-sha1"
         SignBody="true"
         CanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
      <spec:ElementIdentifier
              LocalPart="Timestamp"
              Namespace="http://www.bea.com/examples/security" />
</spec:SignatureSpec>

The example shows how to identify that the Timestamp element of the SOAP message be digitally signed by using the LocalPart and Namespace attributes of the <spec:ElementIdentifier> element. Set the LocalPart attribute equal to the name of the element in the SOAP message you want to encrypt and the Namespace attribute to its namespace. To get the exact name and namespace of the element, you can:

Specifying a particular element to be encrypted is very similar. For example, to encrypt just the element CreditCardNumber, wherever it appears in the SOAP message (rather than the entire SOAP body), update the <spec:EncryptionSpec> element as shown:

<spec:EncryptionSpec 
     EncryptionMethod="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" > 
       <spec:ElementIdentifier
              LocalPart="CreditCardNumber"
              Namespace="http://www.bea.com/examples/security" />
</spec:EncryptionSpec>

For details about the <security> element, and all its child elements discussed in this section, see WebLogic Web Service Deployment Descriptor Elements.

Associating an Operation with a Particular Security Specification

The <security> element of the web-services.xml deployment descriptor file can contain zero or more <spec:SecuritySpec> elements. These elements specify the security requirements for a particular SOAP message: what should be signed, what should be encrypted, what tokens should be included, and so on.

Each <spec:SecuritySpec> element typically has an Id attribute that uniquely identifies it. In the <operations> section of the web-services.xml file, each <operation> element can reference a specific security specification by setting the operation's in-security-spec or out-security-spec attribute to the relevant Id value. The security specification referenced by the in-security-spec attribute is applied to SOAP requests; the security specification referenced by the out-security-spec attribute is applied to SOAP responses.

If a <spec:SecuritySpec> element contains no Id attribute, or it is assigned the value default-spec, the security specification is treated as the default specification and is applied to all operations that do not explicitly reference a specification. Only one default specification can be defined: if more than one is defined in the web-services.xml file, the Web Service will not deploy.

The servicegen Ant task always generates a default security specification in the generated web-services.xml file (with an Id="default-spec" attribute) and this security specification is applied to all SOAP messages for all operations. The individual <operation> elements do not contain any direct reference to this security specification, since none is needed.

For example, assume you have defined the following two security specifications for a Web Service:

<web-service>
...
  <security>
  ...
  <spec:SecuritySpec xmlns:spec="http://www.openuri.org/2002/11/wsse/spec"
                     Namespace="http://schemas.xmlsoap.org/ws/2002/07/secext"
                     Id="encrypt-only">
       <spec:EncryptionSpec
           ...
       </spec:EncryptionSpec>
  </spec:SecuritySpec>
  <spec:SecuritySpec xmlns:spec="http://www.openuri.org/2002/11/wsse/spec"
                     Namespace="http://schemas.xmlsoap.org/ws/2002/07/secext"
                     Id="sign-only">
      <spec:SignatureSpec
         ...
      </spec:SignatureSpec>
  </security>
  ...
</web-service>

In the example, the encrypt-only security specification requires only encryption and the sign-only security specification requires only digital signatures. You can mix and match these security specifications for particular operations by using the in-security-spec and out-security-spec attributes of the relevant <operation> element, as shown in the following example:

  <operations>
      <operation 
             name="operationOne" method="methodOne" component="ejbComp"
             in-security-spec="encrypt-only"
             out-security-spec="encrypt-only">
      ...
      </operation>
      <operation 
             name="operationTwo" method="methodTwo" component="ejbComp"
             in-security-spec="sign-only">
      ...
      </operation>
 </operations>

The preceding excerpt shows that both the SOAP request and response of the operationOne operation must be encrypted, but not digitally signed. The SOAP request for operationTwo must be digitally signed (although not encrypted), but the SOAP response requires no security at all.

For details about the <security> and <operation> elements, see WebLogic Web Service Deployment Descriptor Elements.

Using Timestamps

When a client application invokes a WebLogic Web Service that has been configured for message-level security, WebLogic Server may also require and add timestamp information in the SOAP request and response. By default, WebLogic Server:

You can change the default timestamp behavior of your WebLogic Web Service by adding a <timestamp> child element to the <security> element in the web-services.xml deployment descriptor.

The following web-services.xml excerpt shows an example of configuring timestamp behavior:

<web-service>
 ...
  <security>
    <timestamp>
       <clocks-synchronized>true</clocks-synchronized>
       <clock-precision>30000</clock-precision>
       <require-signature-timestamp>false</require-signature-timestamp>
       <generate-signature-timestamp>true</generate-signature-timestamp> 
       <inbound-expiry>120000</inbound-expiry>  
       <outbound-expiry>30000</outbound-expiry>
    </timestamp>
    ...
  </security>
  ...
</web-service>

The preceding <timestamp> element specifies the following timestamp behavior when the relevant Web Service operation is invoked:

The value specified for the <clock-precision> element is a reflection of how accurately the clocks are synchronized between WebLogic Server and the client applications that invoke the Web Service operation. WebLogic Server uses the value to round all timestamps in a consistent manner. For example, assume that the clock precision is 30000 milliseconds, or 30 seconds. This means that all timestamps are rounded to the closest 30 second increment. This means that, in this example, WebLogic Server rounds the times 12:00:10 and 11:59:50 to the same time (12:00:00) and thus treats the two timestamps equally.

Each of the timestamp elements of the web-services.xml deployment descriptor has a client-side equivalent system property that you can set in your client application. For details, see Using Web Services System Properties.

For detailed descriptions of the <timestamp> element and all its child elements, see WebLogic Web Service Deployment Descriptor Elements.

Encrypting Passwords in the web-services.xml File

Encrypt the key pair passwords (used for encryption and digital signatures) in the web-services.xml file with the weblogic.webservice.encryptpass utility.

The weblogic.webservice.encryptpass utility updates the specified EAR file (or exploded directory) by editing the <security> element of the web-services.xml file, replacing any plain text passwords with their encrypted equivalents.

Only the WebLogic Server domain you specify to the utility is able to decrypt the passwords. This means that if, for example, you want to deploy the EAR file on a WebLogic Server domain different from the one you specified in the encryptpass utility, you must rerun the utility against the EAR file that contains plain text passwords, specifying the new domain.

To encrypt the passwords:

  1. Set your environment.

    2. On Windows NT, execute the setEnv.cmd command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME\user_projects\domains\domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.

    On UNIX, execute the setEnv.sh command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME/user_projects/domains/domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.

  2. Change to the domain directory of the WebLogic Server domain which will be deploying your EAR file. The domain directory contains the config.xml file for the WebLogic Server.

    3. Warning: Only this WebLogic Server domain will be able to decrypt the encrypted passwords in the web-services.xml file.

  3. Run the utility:
    4. java weblogic.webservice.encryptpass options ear_or_dir

    where

    The following example shows how to encrypt the passwords for the Hello Web Service packaged in the ears/myService.ear file:

java weblogic.webservice.encryptpass -serviceName Hello -verbose ears/myService.ear

Table 13-1 Options for the weblogic.webservice.encryptpass Utility

Option

Description

-help

Prints the usage message for the utility.

-version

Prints the version information for the utility.

-verbose

Enables verbose output.

-warName name

Specifies the name of the Web application WAR file, packaged inside the EAR file, that contains the web-services.xml file.

Default value is web-services.war.

-serviceName name

Specifies the name of the Web Service for which you want to encrypt passwords. The name corresponds to the name attribute of the Web Service's <web-service> element in the web-services.xml file.

Default value is the first Web Service in the web-services.xml file.

-domain directory

Specifies the domain directory of the WebLogic Server to which you want to deploy your Web Service.

Default value is the current directory from which you are running the utility.

Updating a Java Client to Invoke a Data-Secured Web Service

To update a Java client application to invoke either a WebLogic or a non-WebLogic Web Service that uses digital signatures or encryption:

  1. Update your client application's CLASSPATH to include WL_HOME/server/lib/wsse.jar, where WL_HOME refers to the top-level directory of WebLogic Platform. This client JAR file contains BEA's implementation of the Web Services Security (WS-Security) specification.
  2. Update your Java code to load a key pair and digital certificate from the client's keystore and pass this information, along with a username and password for user authentication, to the secure WebLogic Web Service being invoked.

    3. For details, see Writing the Java Code to Invoke a Secure WebLogic Web Service.

    For an example of invoking a secure non-WebLogic Web Service, see Writing the Java Code to Invoke a Secure Non-WebLogic Web Service

  3. Run the client application.

    4. For details about system properties you can set to get more information about the digital signatures and encryption, see Running the Client Application.

Writing the Java Code to Invoke a Secure WebLogic Web Service

The following example shows a Java client application that invokes a message-secured WebLogic Web Service, with the security-specific code in bold (and described after the example):

import java.io.IOException;
import java.io.FileInputStream;
import javax.xml.rpc.ServiceException;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.cert.CertificateException;
import java.security.UnrecoverableKeyException;
import java.security.Key;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.X509Certificate;
import weblogic.webservice.context.WebServiceContext;
import weblogic.webservice.context.WebServiceSession;
import weblogic.webservice.core.handler.WSSEClientHandler;
import weblogic.xml.security.UserInfo;
public class Main{
  private static final String CLIENT_KEYSTORE = "client_keystore";
  private static final String KEYSTORE_PASS = "client_keystore_password";
  private static final String CLIENT_KEYNAME = "client_key";
  private static final String CLIENT_KEYPASS = "client_key_password";
  private static final String AUTHENTICATION_USER = "auth_user";
  private static final String AUTHENTICATION_USER_PASS = "auth_user_password";
  public static void main( String[] args ){
    if( args.length == 1 ){
      new Main( args[0] );
    }else{
      throw new IllegalArgumentException( "URL of the service not specified" );
    }
  }
  public Main( String wsdlUrl ){
    try{
      HelloWorldService service = new HelloWorldService_Impl( wsdlUrl );
      HelloWorldServicePort port = service.getHelloWorldServicePort();
      WebServiceContext context = service.context();
      X509Certificate clientcert = getCertificate(CLIENT_KEYNAME, CLIENT_KEYSTORE);
      PrivateKey clientprivate = (PrivateKey)getPrivateKey(CLIENT_KEYNAME, CLIENT_KEYPASS,CLIENT_KEYSTORE);
      WebServiceSession session = context.getSession();
      session.setAttribute(WSSEClientHandler.CERT_ATTRIBUTE, clientcert);
      session.setAttribute(WSSEClientHandler.KEY_ATTRIBUTE, clientprivate);
      UserInfo ui = new UserInfo(AUTHENTICATION_USER, AUTHENTICATION_USER_PASS);
      session.setAttribute(WSSEClientHandler.REQUEST_USERINFO, ui);
      World world = port.helloComplexWorld();
      System.out.println( world );
    }catch( IOException e ){
      System.out.println( "Failed to create web service client:" + e );
    }catch( ServiceException e ){
      System.out.println( "Failed to create web service client:" + e );
    }catch( KeyStoreException e ){
      System.out.println( "Failed to create web service client:" + e );
    }catch( CertificateException e ){
      System.out.println( "Failed to create web service client:" + e );
    }catch( UnrecoverableKeyException e ){
      System.out.println( "Failed to create web service client:" + e );
    }catch( NoSuchAlgorithmException e ){
      System.out.println( "Failed to create web service client:" + e );
    }
  }
  private Key getPrivateKey( String keyname, String password, String keystore)
      throws IOException, KeyStoreException, NoSuchAlgorithmException,
             CertificateException, UnrecoverableKeyException{
    KeyStore ks = KeyStore.getInstance("JKS");
    ks.load(new FileInputStream(keystore), KEYSTORE_PASS.toCharArray());
    Key result = ks.getKey(keyname, password.toCharArray());
    return result;
  } 
  private static X509Certificate getCertificate(String keyname, String keystore)
     throws IOException, KeyStoreException, NoSuchAlgorithmException,
            CertificateException {
    KeyStore ks = KeyStore.getInstance("JKS");
    ks.load(new FileInputStream(keystore), KEYSTORE_PASS.toCharArray());
    X509Certificate result = (X509Certificate) ks.getCertificate(keyname);
    return result;
  } 
}

The main points to note about the preceding code are:

For more information about the WebLogic Web Services APIs discussed in this section, see the Javadoc.

Writing the Java Code to Invoke a Secure Non-WebLogic Web Service

The following example is similar to the one in the previous section, except that it shows how to write a Java client application that invokes a non-WebLogic Web Service, such as .NET.

The example uses the weblogic.xml.security.wsse and weblogic.xml.security.specs APIs to create user Tokens, X.509 Tokens, EncryptionSpecs, and SignatureSpecs which the WebLogic client API uses to create the appropriate <wsse:Security> element in the SOAP message request that invokes the non-WebLogic Web Service. The user Token objects contain username and passwords and X.509 Token objects contain a certificate and an optional private key.

Note: Because there is currently no standard way of specifying security information in the WSDL of a Web Service, consult with the Web Service provider to find out what needs to be signed and encrypted when invoking a non-WebLogic Web Service.

The relevant sections of the example are in bold (and described after the example):

import java.io.IOException;
import java.io.FileInputStream;
import java.util.List;
import java.util.ArrayList;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.cert.X509Certificate;
import java.security.cert.CertificateException;
import javax.xml.rpc.ServiceException;
import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.HandlerRegistry;
import weblogic.webservice.context.WebServiceContext;
import weblogic.webservice.core.handler.WSSEClientHandler;
import weblogic.xml.security.wsse.Security;
import weblogic.xml.security.wsse.Token;
import weblogic.xml.security.wsse.SecurityElementFactory;
import weblogic.xml.security.specs.EncryptionSpec;
import weblogic.xml.security.specs.SignatureSpec;
import weblogic.xml.security.SecurityAssertion;
import examples.security.basicclient.BasicPort;
import examples.security.basicclient.Basic_Impl;
import examples.security.basicclient.Basic;
public class Client {
  private static final String CLIENT_KEYSTORE = "client.keystore";
  private static final String KEYSTORE_PASS = "gumby1234";
  private static final String KEY_ALIAS = "joe";
  private static final String KEY_PASSWORD = "myKeyPass";
  private static final String SERVER_KEY_ALIAS = "myServer";
  private static final String USERNAME = "pete";
  private static final String USER_PASSWORD = "myPassword";
  public static void main(String[] args)
      throws IOException, ServiceException, Exception {
    {
      final KeyStore keystore = loadKeystore(CLIENT_KEYSTORE, KEYSTORE_PASS);
      Basic service = new Basic_Impl();
      WebServiceContext context = service.context();
      // add WSSE Client Handler to the handler chain for the service.
      HandlerRegistry registry = service.getHandlerRegistry();
      List list = new ArrayList();
      list.add(new HandlerInfo(WSSEClientHandler.class, null, null));
      registry.setHandlerChain(new QName("basicPort"), list);
      // load the client credential
      X509Certificate clientcert;
      clientcert = getCertificate(KEY_ALIAS, keystore);
      PrivateKey clientprivate;
      clientprivate = getPrivateKey(KEY_ALIAS, KEY_PASSWORD, keystore);
      // load the server's certificate...
      X509Certificate serverCert = getCertificate(SERVER_KEY_ALIAS, keystore);
      // configure the Security element for the service.
      SecurityElementFactory factory =
                SecurityElementFactory.getDefaultFactory();
      Token x509token = factory.createToken(clientcert, clientprivate);
      Token userToken = factory.createToken(USERNAME, USER_PASSWORD);
      EncryptionSpec encSpec = EncryptionSpec.getDefaultSpec();
      SignatureSpec sigSpec = SignatureSpec.getDefaultSpec();
      Token serverToken = null;
      // create a token for the server's cert... no PrivateKey...
      serverToken = factory.createToken(serverCert, null);
      Security security = factory.createSecurity(/* role */ null);
      //add a Timestamp to the Security header. The creation time will be
      // the current time, and there is no expiration.
      security.addTimestamp();
      //add the username/password to the header as a UsernameToken
      security.addToken(userToken);
      security.addSignature(x509token, sigSpec);
      //add client cert for signature verification and response encryption
      // should be added after the signature....
      security.addToken(x509token);
      security.addEncryption(serverToken, encSpec);
      BasicPort port = service.getbasicPort();
      // add the security element to the request...
      context.getSession().setAttribute("weblogic.webservice.security.request",
                                        security);
      String result = null;
      result = port.helloback();
      System.out.println(result);
      // view the assertions from processing the server's response...
      SecurityAssertion[] assertions = (SecurityAssertion[])
          context.getSession().getAttribute("weblogic.webservice.security.assertions.response");
      for (int i = 0; i < assertions.length; i++) {
        SecurityAssertion assertion = assertions[i];
        System.out.println(assertion);
      }
    }
  }
  private static KeyStore loadKeystore(String filename, String password)
      throws KeyStoreException, IOException, NoSuchAlgorithmException, 
              CertificateException {
    final KeyStore ks = KeyStore.getInstance("JKS");
    ks.load(new FileInputStream(filename), password.toCharArray());
    return ks;
  }
  private static PrivateKey getPrivateKey(String alias, String password, 
         KeyStore keystore)
      throws Exception {
    PrivateKey result =
        (PrivateKey) keystore.getKey(alias, password.toCharArray());
    return result;
  }
  private static X509Certificate getCertificate(String alias, KeyStore keystore)
      throws Exception {
    X509Certificate result = (X509Certificate) keystore.getCertificate(alias);
    return result;
  }
}

The main points to note about the preceding code are:

      context.getSession().setAttribute("weblogic.webservice.security.request",
                                        security);

Keep the following points in mind when using the WebLogic Web Services Security APIs to invoke a secure non-WebLogic Web Service:

Running the Client Application

When you run the client application that uses digital signatures and encryption to invoke a Web Service, you can set the following system properties to view more runtime security information:

 

Configuring Transport-Level Security (SSL): Main Steps

Transport-level security refers to securing the connection between a client application and a Web Service with Secure Sockets Layer (SSL). The following procedure describes the high-level steps; later sections in the chapter describe the steps in more detail.

  1. Configure SSL for WebLogic Server.

    2. You can configure one-way SSL (the default) where WebLogic Server is required to present a certificate to the client application, or two-way SSL where both the client applications and WebLogic server present certificates to each other.

    For details about SSL, the difference between one-way and two-way, and procedures to configure both, see Configuring SSL.

  2. Optionally update the web-services.xml file to specify that the Web Service can be accessed only by HTTPS.

    3. See Specifying the HTTPS Protocol.

  3. Configure SSL for the client application.

    4. See Configuring SSL for a Client Application.

Warning: If you use two-way SSL to secure the connection when invoking a WebLogic Web Service, WebLogic Server uses anonymous identity to authorize access to the Web Service. If this authorization fails, WebLogic Server first asserts the identity of the certificate to ensure that it maps to a valid WebLogic Server user and then uses that user identity to invoke the Web Service, even if the Web Service or the stateless EJB back-end component does not require any special privileges.

Warning: To use the user credentials mapped to the client certificate instead of using the anonymous user identity, you need to disable anonymous access for the Web Service

Warning: WebLogic Server does not assert the identity of the certification in one-way SSL, however, because in that case the client application does not send its certificate.

Implications of Using SSL With Web Services

You should be aware of the following thread safety issues when using SSL with Web Services. The BEA generated JAX-RPC client stubs are thread-safe by default. However, as soon as you enable SSL, the client stubs are no longer thread-safe. To minimize the chances of your Web Service client applications running into threading problems, BEA recommends you do either of the following:

If your client application is not an EJB, you could also use synchronization to handle threading issues. You cannot use synchronization if your client is an EJB, because this would violate the EJB specifiation.

 

Configuring SSL for a Client Application

Configure SSL for your client application by using either:

If you are using two-way SSL, your client application must also present its certificate to WebLogic Server. For details, see Configuring Two-Way SSL For a Client Application.

For additional detailed information about the APIs discussed in this section see the Web Service security Javadocs.

Using the WebLogic Server-Provided SSL Implementation

If you are using a stand-alone client application, WebLogic Server provides an implementation of SSL in the webserviceclient+ssl.jar client runtime JAR file. In addition to the SSL implementation, this client JAR file contains the standard client JAX-RPC runtime classes contained in webservicesclient.jar.

Note: For information about BEA's current licensing of client functionality, see the BEA eLicense Web Site.

To configure basic SSL support for your client application, follow these steps:

  1. Set the filename of the file containing trusted Certificate Authority (CA) certificates. Do this by either:
  2. Run your Java client application, either as a standalone client or on WebLogic Server.

    3. If you are creating a standalone client application:

  3. If you are not using a certificate issued by a CA in your trusted CA file, then disable strict certificate validation by either setting the weblogic.webservice.client.ssl.strictcertchecking System property to false at the command line when you run the standalone application, or programmatically use the BaseWLSSLAdapter.setStrictCheckingDefault() method. Use the second way if your client application is running on WebLogic Server.

By default, client applications that use the WebLogic SSL implementation do not share sockets. If you want to change this behavior, see Using SSL Socket Sharing When Using the WebLogic SSL Implementation.

For detailed information, see the Web Service security Javadocs.

Configuring the WebLogic SSL Implementation Programatically

You can also configure the WebLogic Server-provided SSL implementation programatically by using the weblogic.webservice.client.WLSSLAdapter adapter class. This adapter class hold configuration information specific to WebLogic Server's SSL implementation and allows the configuration to be queried and modified.

The following excerpt shows an example of configuring the WLSSLAdapter class for a specific WebLogic Web Service; the lines in bold are discussed after the example:

    // instantiate an adapter...
    WLSSLAdapter adapter  = new WLSSLAdapter();
    adapter.setTrustedCertifcatesFile("mytrustedcerts.pem");
    // optionally set the Adapter factory to use this
    // instance always...
    SSLAdapterFactory.getDefaultFactory().setDefaultAdapter(adapter);
    SSLAdapterFactory.getDefaultFactory().setUseDefaultAdapter(true);
    //create service factory
    ServiceFactory factory = ServiceFactory.newInstance();
    //create service
    Service service = factory.createService( serviceName ); 
    //create call
    Call call = service.createCall();
    call.setProperty("weblogic.webservice.client.ssladapter",
                      adapter);
    try {
      //invoke the remote web service
      String result = (String) call.invoke( new Object[]{ "BEAS" } );
      System.out.println( "Result: " +result);
    } catch (JAXRPCException jre) {
    ...
    }

The example first shows how to instantiate an instance of the WebLogic Server-provided WLSSLAdapter class, which supports the SSL implementation contained in the webserviceclient+ssl.jar file. It then configures the adapter instance by setting the name of the file that contains the Certificate Authority certificates using the setTrustedCertificatesFile(String) method; in this case the file is called mytrustedcerts.pem.

The example then shows how to set WLSSLAdapter as the default adapter of the adapter factory and configures the factory to always return this default.

Note: This step is optional; it allows all Web Services to share the same adapter class along with its associated configuration.

You can also set the adapter for a particular Web Service port or call. The preceding example shows how to do this when using the Call class to invoke a Web Service dynamically:

call.setProperty("weblogic.webservice.client.ssladapter", adapter);

Set the property to an object that implements the weblogic.webservice.client.SSLAdapter interface (which in this case is the WebLogic Server-provided WLSSLAdapter class.)

The following excerpt shows how to set the adapter when using the Stub interface to statically invoke a Web Service:

((javax.xml.rpc.Stub)stubClass)._setProperty("weblogic.webservice.client.ssladapter", adapterInstance);

You can get the adapter for a specific instance of a Web Service call or port by using the following method for dynamic invocations:

call.getProperty("weblogic.webservice.client.ssladapter");

Use the following method for static invocations:

((javax.xml.rpc.Stub)stubClass)._getProperty("weblogic.webservice.client.ssladapter");

For detailed information, see the Web Service security Javadocs.

Using SSL Socket Sharing When Using the WebLogic SSL Implementation

By default, socket sharing is disabled for SSL client applications that connect to a WebLogic Web Service using the WebLogic Server-provided SSL implemenation.

However, to improve the performance of your client application, you can enable socket sharing for multiple serial invokes of a Web Service. This socket sharing mechanism provides the improved performance of SSL connection reuse, while giving you the ability to enforce any necessary security.

Implications of Enabling SSL Socket Sharing

If your application is actually a server in which multiple clients use SSL authentication to invoke a Web Service, it is your responsibility to prevent access by one client to another client's JAX-RPC stub implementation object (weblogic.webservice.core.rpc.StubImpl).

Because of the security and general thread safety issues (see Implications of Using SSL With Web Services), the socket sharing mechanism is not enabled by default.

Enabling SSL Socket Sharing Using System Properties

To enable, using system properties, socket sharing in your SSL client application, set the Java system property https.sharedsocket to true on the command you use to invoke your client application, as shown in the following example:

java -Dbea.home=/bea_home \
     -Djava.protocol.handler.pkgs=com.certicom.net.ssl  \
     -Dhttps.sharedsocket=true my_app

The default value of the https.sharedsocket system property is false.

You can also specify the timeout value for shared sockets by using the https.sharedsocket.timeout system property to set the number of seconds that shared sockets live, as shown in the following example:

java -Dbea.home=/bea_home \
     -Djava.protocol.handler.pkgs=com.certicom.net.ssl  \
     -Dhttps.sharedsocket=true 
     -Dhttps.sharedsocket.timeout=30 my_app

The default value of https.sharedsocket.timeout is 15 seconds.

Note: This timeout value does nothing to the actual transport layer controlling the socket. The value is used to determine if the SSL socket has not been referenced in the given timeframe and if not, then on this reference, if the time has expired, then the socket is closed and the protocol handshake is restarted.

Enabling SSL Socket Sharing Using the HttpsBindingInfo API

You can also use the weblogic.webservice.binding.https.HttpsBindingInfo SSL binding API, rather than system properties, to programmatically enable socket sharing from within your SSL client application. When you use the WebLogic SSL implementation, you use the public constructor of HttpsBindingInfo to create an HttpsBindingInfo object; the constructor specifies that the client application is using the WLSSSLAdapter subclass of the SSLAdapter class.

To enable socket sharing in your client application with the API, use the HttpsBindingInfo.setSocketSharing(boolean) setter method on the HttpsBindingInfo object, passing it a value of true. To disable socket sharting, pass the method a value of false. The default value, if you do not call this method in your application, is false (no socket sharing).

You can also specify the timeout value for shared sockets by using the HttpsBindingInfo.setSharedSocketTimeout(long) method on the HttpsBindingInfo object, passing it the number of seconds that shared sockets live. The default value, if you do not set this method, is 15 seconds.

Note: This timeout value does nothing to the actual transport layer controlling the socket. The value is used to determine if the SSL socket has not been referenced in the given timeframe and if not, then on this reference, if the time has expired, then the socket is closed and the protocol handshake is restarted.

To close the shared SSL socket in your client application, use the HttpsBindingInfo.closeSharedSocket() method on the HttpsBindingInfo object. This method takes no parameters. Typically you close the shared socket in the cleanup method of the object from which you created the HttpsBindingInfo object.

Using a Third-Party SSL Implementation

If you want to use a third-party SSL implementation, you must first implement your own adapter class. The following example shows a simple class that provides support for JSSE; the main steps to implementing your own class are discussed after the example:

import java.net.URL;
import java.net.Socket;
import java.net.URLConnection;
import java.io.IOException;
public class JSSEAdapter implements weblogic.webservice.client.SSLAdapter {
  javax.net.SocketFactory factory =
    javax.net.ssl.SSLSocketFactory.getDefault();
  // implements weblogic.webservice.client.SSLAdapter interface...
  public Socket createSocket(String host, int port) throws IOException  {
    return factory.createSocket(host, port);
  }
  public URLConnection openConnection(URL url) throws IOException {
    // assumes you have java.protocol.handler.pkgs properly set..
    return url.openConnection();
  }
  // the configuration interface...
  public void setSocketFactory(javax.net.ssl.SSLSocketFactory factory) {
    this.factory = factory;
  }
  public javax.net.ssl.SSLSocketFactory getSocketFactory() {
    return (javax.net.ssl.SSLSocketFactory) factory;
  }
}

To create your own adapter class:

  1. Create a class that implements the following interface:
    2. weblogic.webservice.client.SSLAdapter
  2. Implement the createSocket method, whose signature is:
    3. public Socket createSocket(String host, int port) 
        throws IOException

    This method returns an object that extends java.net.Socket. The object is connected to the designated hostname and port when a Web Service is invoked.

  3. Implement the openConnection method, whose signature is:
    4. public URLConnection openConnection(URL url) throws IOException

    This method returns an object that extends the java.net.URLConnection class. The object is configured to connect to the designated URL. These connections are used for infrequent network operations, such as downloading the Web Service WSDL.

  4. When you run your client application, set the following System property to the fully qualified name of your adapter class:
    5. weblogic.webservice.client.ssl.adapterclass

    The default SSLAdapterFactory class loads your adapter class and creates an instance of the class using the default no-argument constructor.

  5. Configure your custom adapter class as shown in Configuring the WebLogic SSL Implementation Programatically, substituting your class for WLSSLAdapter and using the configuration methods defined for your adapter.

For detailed information, see the Web Service security Javadocs.

Extending the SSLAdapterFactory Class

You can create your own custom SSL adapter factory class by extending the SSLAdapterFactory class, which is used to create instances of adapters. One reason for extending the factory class is to allow custom configuration of each adapter when it is created, prior to use.

To create a custom SSL adapter factory class:

  1. Create a class that extends the following class:
    2. weblogic.webservice.client.SSLAdapterFactory
  2. Override the following method of the SSLAdapterFactory class:
    3. public weblogic.webservice.client.SSLAdapter createSSLAdapter();

    This method is called whenever a new SSLAdapter, or an adapter that implements this interface, is created by the adapter factory. By overriding this method, you can perform custom configuration of each new adapter before it is actually used.

  3. In your client application, create an instance of your factory and set it as the default factory by executing the following method:
    4. SSLAdapterFactory.setDefaultFactory(factoryInstance);

For detailed information, see the Web Service security Javadocs.

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. The following sample Java code shows one way of doing this where the client application receives the client certificate file as an argument (relevant code in bold):

...
SSLAdapterFactory factory = SSLAdapterFactory.getDefaultFactory();
WLSSLAdapter adapter = (WLSSLAdapter) factory.getSSLAdapter();
if (argv.length > 1 ) {
  System.out.println("loading client certs from "+argv[1]);
FileInputStream clientCredentialFile  = new FileInputStream (argv[1]);
String pwd = "clientkey";
adapter.loadLocalIdentity(clientCredentialFile, pwd.toCharArray());
javax.security.cert.X509Certificate[] certChain = adapter.getIdentity("RSA",0);
factory.setDefaultAdapter(adapter);
factory.setUseDefaultAdapter(true);
...

Using a Proxy Server

If your client application is running inside a firewall, for example, and needs to use a proxy server, set the host name and the port of the proxy server using the following two System properties:

For more information on these System properties, see Using Web Services System Properties.

 

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, to the Web Service when the client invokes one of its operations.

The following procedure describes the high-level steps; later sections in the chapter describe the steps in more detail.

  1. Control access to either the entire Web Service or some of its components by creating roles, mapping the roles to principals in your realm, then specifying which components are secured and accessible only by the principals in the role.

    2. See Controlling Access to WebLogic Web Services.

  2. Optionally update the web-services.xml file to specify that the Web Service can be accessed only by HTTPS.

    3. See Specifying the HTTPS Protocol.

  3. Code your client to authenticate itself using HTTP when invoking a WebLogic Web Service.

    4. See Coding a Client Application to Authenticate Itself to a Web Service.

Controlling Access to WebLogic Web Services

WebLogic Web Services are packaged as standard J2EE Enterprise applications. Consequently, to secure access to the Web Service, you secure access to some or all of the following components that make up the Web Service:

You can use basic HTTP authentication or SSL to authenticate a client that is attempting to access a WebLogic Web Service. Because many of the preceding components are standard J2EE components, you secure them by using standard J2EE security procedures. The following sections describe how to secure each of these components.

Note: If the back-end component that implements your Web Service is a Java class or a JMS listener, the only way to secure the Web Service is by adding security constraints to the entire Web Service or to the URL that invokes the Web Service. In other words, you cannot secure just the back-end component that implements the Web Service.

For additional and detailed information about configuring, programming, and managing WebLogic security, see the security documentation.

Securing the Entire Web Service and Its Operations

You secure an entire Web Service by creating a security policy through the Administration Console and assigning it to a WebLogic Web Service. You can also use the Administration Console to secure a subset of the Web Service operations. Security policies answer the question "who has access" to a WebLogic resource, in this case a Web Service or a subset of its operations. A security policy is created when you define an association between a WebLogic resource and a user, group, or role. A WebLogic resource has no protection until you assign it a security policy.

You assign security policies to an individual resource or to attributes or operations of a resource. If you assign a security policy to a type of resource, all new instances of that resource inherit that security policy. Security policies assigned to individual resources or attributes override security policies assigned to a type of resource.

To use a user or group to create a security policy, the user or group must be defined in the Authentication provider configured in the default security realm. To use a role to create a security policy, the role must be defined in the Role Mapping provider configured in the default security realm. By default, the WebLogic Authentication and Role Mapping providers are configured.

For more information and procedures about setting protections for a WebLogic Web Service or a subset of its operations using the Administration Console, see Securing WebLogic Resources.

Securing the Web Service URL

Client applications use a URL to access a Web Service, as described in WebLogic Web Services Home Page and WSDL URLs. An example of such a URL is:

http://ariel:7001/web_services/TraderService

You can restrict access to the entire Web Service by restricting access to its URL. To do this, update the web.xml and weblogic.xml deployment descriptor files (in the Web application that contains the web-services.xml file) with security information.

For detailed information about restricting access to URLs, see Securing WebLogic Resources.

Securing the Stateless Session EJB and Its Methods

If you secure the stateless session EJB that implements a Web Service, client applications that invoke the service have access to the Web application, the WSDL, and the Web Service Home Page, but might not be able to invoke the actual method that implements an operation. This type of security is useful if you want to closely monitor who has access to the business logic of the EJB but do not want to block access to the entire Web Service.

You can also use this type of security to decide at the method-level who has access to the various operations of the Web Service. For example, you can specify that any user can invoke a method that views information, but only a certain subset of users are allowed to update the information.

For more information and procedures about securing EJBs and individual methods of an EJB using the Administration Console, see Securing WebLogic Resources.

Securing the WSDL and Home Page of the Web Service

You can restrict access to either the WSDL or Home Page of a WebLogic Web Service by updating the web-services.xml deployment descriptor that describes the service, as described in the following procedure:

  1. Open the web-services.xml file in your favorite editor.

    2. The web-services.xml file is located in the WEB-INF directory of the Web application of the Web Services EAR file. See The Web Service EAR File Package for more information on locating the file.

  2. To restrict access to the WSDL, add the exposeWSDL="False" attribute to the <web-service> element that describes your Web Service. To restrict access to the Home page, add the exposeHomePage="False" attribute. The following excerpt shows an example:
    3.      <web-service 
            name="stockquotes" 
            uri="/myStockQuoteService"
            exposeWSDL="False"
            exposeHomePage="False"     >
             ...
         </web-service>

    The default value of the exposeWSDL and exposeHomePage attributes is True.

  3. Re-deploy your Web Service for the change to take affect. The WSDL and Home Page of the Web Service will be inaccessible to all users.

Specifying the HTTPS Protocol

You make a Web Service accessible only through HTTPS by updating the protocol attribute of the <web-service> element in the web-services.xml file that describes the Web Service, as shown in the following excerpt:

<web-services>
  <web-service name="stockquotes"
               targetNamespace="http://example.com"
               uri="/myStockQuoteService"
               protocol="https" >
     ...
  </web-service>
</web-services>

Note: If you configure SSL for WebLogic Server and you do not specify the HTTPS protocol in the web-services.xml file, client applications can access the Web Service using both HTTP and HTTPS. However, if you specify HTTPS access in the web-services.xml file, client applications cannot use HTTP to access the Web Service.

If you use the servicegen Ant task to assemble the Web Service, use the protocol attribute of the <service> element to specify the HTTPS protocol, as shown in the following sample build.xml file:

<project name="buildWebservice" default="ear">
  <target name="ear">
    <servicegen
       destEar="ws_basic_statelessSession.ear"
       contextURI="WebServices"
       <service
         ejbJar="HelloWorldEJB.jar"
         targetNamespace="http://www.bea.com/webservices/basic/statelesSession"
         serviceName="HelloWorldEJB"
         serviceURI="/HelloWorldEJB"
         protocol="https"
         generateTypes="True"
         expandMethods="True">
       </service>
     </servicegen>
  </target>
</project>

Coding a Client Application to Authenticate Itself to a Web Service

When you write a JAX-RPC client application that invokes a Web Service, you use the following two properties to send a user name and password to the service so that the client can authenticate itself:

The following example, taken from the JAX-RPC specification, shows how to use these properties when using the javax.xml.rpc.Stub interfaces to invoke a secure Web Service:

StockQuoteProviderStub sqp = // ... get the Stub;
sqp._setProperty ("javax.xml.rpc.security.auth.username", "juliet");
sqp._setProperty ("javax.xml.rpc.security.auth.password", "mypassword");
float quote sqp.getLastTradePrice("BEAS");

If you use the WebLogic-generated client JAR file to invoke a Web Service, the Stub classes are already created for you, and you can pass the user name and password to the Service-specific implementation of the getServicePort() method, as shown in the following example taken from the JAX-RPC specification:

StockQuoteService sqs = // ... Get access to the service;
StockQuoteProvider sqp = sqs.getStockQuoteProviderPort ("juliet", "mypassword");
float quote = sqp.getLastTradePrice ("BEAS");

In this example, the implementation of the getStockQuoteProvidePort() method sets the two authentication properties.

For additional information on writing a client application using JAX-RPC to invoke a secure Web Service, see http://java.sun.com/xml/jaxrpc/index.html.

 

Testing a Secure WebLogic Web Service From Its Home Page

The section Deploying and Testing WebLogic Web Services describes how to invoke and test a non-secure WebLogic Web Service from its Home page.

Testing a secure WebLogic Web Service from its Home Page requires additional configuration of WebLogic Server, because in this case the server itself is acting as a secure client to the Web Service. In particular, you must configure WebLogic Server to use a trusted certificate authority (CA) file called trusted-ca.pem, which the Home Page is hard-coded to use when invoking the secure Web Service; the Home Page does not use the server keystore. This is because the Home Page uses the standard WebLogic Web Services client JAR file, which, with the aim of keeping the JAR file as thin as possible, does not include the security APIs needed to extract certificates from a keystore.

Note: You cannot use two-way SSL when testing a secure Web Service from its Home Page.

To test a secure WebLogic Web Service from its Home Page, follow these steps.

  1. If not already configured, configure SSL for WebLogic Server.

    2. For more information, see Configuring the SSL Protocol.

  2. Add the following flags to the script that starts up this instance of WebLogic Server:
-Dweblogic.webservice.client.ssl.strictcertchecking=false
-Dweblogic.security.SSL.ignoreHostnameVerification=true
  1. Create a trusted certificate authority (CA) file called trusted-ca.pem by following these steps:
    1. Open a command window and set your environment.

      2. On Windows NT, execute the setEnv.cmd command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME\user_projects\domains\domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.

      On UNIX, execute the setEnv.sh command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME/user_projects/domains/domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.

    2. Move to the WL_HOME\server\lib directory, where WL_HOME refers to the top-level WebLogic Platform installation directory.
    3. Use the utils.der2pem WebLogic Server Java utility to convert the WL_HOME\server\lib\CertGenCA.der trusted certificate authority file from DER format to PEM:
      4. java utils.der2pem CertGenCA.der

      The utility generates a file called CertGenCA.pem.

    4. Rename the generated CertGenCA.pem to trusted-ca.pem.
  2. Move the trusted-ca.pem file you created in the preceding step to the domain directory of WebLogic Server.
  3. Restart WebLogic Server for the startup flags to take effect.
  4. Invoke the secure WebLogic Web Service's Home Page in your browser. The browser will return a message saying the certificate is not trusted.
  5. Load the trusted certificate in your browser. You may need to restart your browser for it to take effect.
  6. Invoke the secure WebLogic Web Service's Home Page again in your browser. You should now be able to test your secure Web Service as described in Deploying and Testing WebLogic Web Services.

 

Skip navigation bar  Back to Top Previous Next