test

Sun Java System Web Server 7.0 Update 2 Developer's Guide to Java Web Applications

Chapter 3 Web Services Overview

This chapter focuses on web services tasks that are performed by developers. For administrator tasks, including configuration and management information, see Appendix C, Web Services, in Sun Java System Web Server 7.0 Update 2 Administrator’s Guide.

Introducing Web Services

Web Services uses a Web Services Description Language (WSDL) file to describe the service and registry service to register and look up the services. The Simple Object Access Protocol (SOAP) binding is the standard interoperable binding for accessing Web Services. Several registry protocols available, but UDDI (Universal Description, Discovery and Integration) is probably the most recognizable based on Java Web Services Developer Pack, Web Server because it supports integrated Java Web Services runtime and tools, and therefore supports portable Web Services implementations, making it interoperable with .NET clients and services using the WS-I Basic Profile. For more information on Web Services, see http://java.sun.com/webservices/docs/2.0/tutorial/doc/index.html.

WS-Security is an OASIS proposal for adding message-layer security to SOAP messages. It defines standardized locations and syntax by which security tokens such as X.509 certificates and Kerberos tickets can be carried within SOAP Headers in order to secure the contents of the SOAP message exchanges. WS-Security leverages the existing XML Digital Signature and XML Encryption specifications for capturing the results of signing and encryption operations in XML syntax. In essence, WS-Security standardizes the XML Signature and XML Encryption data blocks that are carried with a SOAP message. Web Server supports the integrated WS-Security standard. In addition, this release supports JSR-196 as applicable to Web Services. Web Server provides the ability to bind SOAP-layer message-security providers and message-protection policies to the container. This binding allows the container to enforce the security on behalf of the applications.

Technologies Supported in Web Server 7.0

This section describes the technologies supported by Web Server 7.0. For more information, see http://java.sun.com/webservices/docs/2.0/tutorial/doc/index.html.

This section contains the following topics:

Java Web Services Developer Pack 2.0 Technologies

Java Web Services Developer Pack, provides an integrated development and test environment. The technologies included with Web Server are:

Message Security (JSR-196)

In message security, security information is inserted into messages so that it travels through the networking layers and arrives with the message at the message destination. Message security differs from transport layer security. Message security can be used to decouple message protection from message transport so that the message remains protected after transmission. For more information on security, see http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security2.html#wp268799.

JSR-196, as applicable to Web Services, defines a standard service provider interface by which authentication mechanism providers may be integrated with containers. Providers integrated through this interface establish the authentication identities used in container access decisions while servicing the request.

Creating Web Services

Web Services is created in different ways, depending on whether the starting point of development is a Java source file, a Java class file, or a WSDL file.

Web Services Tools

Use different tools is used to generate JAX-WS artifacts, depending on whether the starting point of Web Services development is a Java source file, a Java class file, or a WSDL file.

Note –

After using the tools, the web.xml, sun-jaxws.xml, the implementation class, and the portable JAX-WS artifacts must be bundled into a WAR that can be deployed onto a container.

The following procedures describes how to use these methods.

ProcedureTo Create Web Services from a Java Source

  1. Use apt to generate Java artifacts such as the WSDL file, and schema documents.

  2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.

  3. Deploy the WAR file to Web Server.

ProcedureTo Create Web Services from Java Classes

  1. Use wsgen to generate portable artifacts.

  2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.

  3. Deploy the WAR file to Web Server.

ProcedureTo Create Web Services from a WSDL file

  1. Use wsimport to generate portable artifacts.

  2. Implement the service endpoint.

  3. Package the WSDL file, schema documents, web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.

  4. Deploy the WAR file to a web container.

Securing Web Services

Web Services Security SOAP Message Security (WS-Security) is an international standard for interoperable web services security that was developed in OASIS by a collaboration of all the major providers of web services technology (including Sun Microsystems). WS-Security is a message security mechanism that uses XML Encryption and XML Digital Signature to secure web services messages sent over SOAP. The WS-Security specification defines the use of various security tokens including X.509 certificates, SAML assertions, and username and password tokens to authenticate and encrypt SOAP Web Services messages. This section also includes the following sections:

Understanding Message Security in the Web Server

The Web Server offers integrated support for the WS-Security standard in the server-side container. This functionality is integrated with Web Services security and enforced by the container of the Web Server on behalf of applications. Web Server can protect any web service application without requiring changes to the implementation of the application. The Web Server achieves this effect by providing facilities to bind SOAP layer message security providers and message protection policies to container and to applications deployed in container.

Assigning Message Security Roles

In the Web Server, the system administrator and application deployer roles are expected to take primary responsibility for configuring message security. In some situations, the application developer also contribute, although in the typical case either of the roles might secure an existing application without changing its implementation and therefore without involving the developer. The responsibilities of the various roles are defined in the following sections.

System Administrator Tasks

The system administrator is responsible for the following tasks:

A system administrator uses the Admin Console to manage server security settings. Web Server stores certificates and private keys in an NSS database, the administrator can manage them using certutil. For an overview of message security tasks, see Configuring the Web Server for Message Security.

Application Deployer Tasks

The application deployer is responsible for the following tasks:

The application developer can setup message security but is not responsible for doing so. The system administrator can set the message security so that all Web Services are secured. The application deployer can set the message security when the provider or protection policy bound to the application must be different from that bound to the container.

Application Developer Tasks

The application developer or assembler is responsible for the following tasks:

Security Tokens and Security Mechanisms

The WS-Security specification provides an extensible mechanism for using security tokens to authenticate and encrypt SOAP Web Services messages. Use the SOAP-layer message security providers installed with the Web Server to employ username, password and X.509 certificate security tokens to authenticate and encrypt SOAP Web Services messages.

Username Tokens

The Web Server uses username tokens in the SOAP messages to establish the authentication identity of the message sender. The recipient of a message containing a Username token within an embedded password validates that the message sender is authorized to act as the user (identified in the token) by confirming that the sender knows the users secret password.

When using a Username token, a valid user database must be configured on the Web Server.

Digital Signatures

The Web Server uses XML Digital signatures to bind an authentication identity to the message content. Clients use digital signatures to establish their caller identity, analogous to basic authentication or SSL client certificate authentication. Digital signatures are verified by the message receiver to authenticate the source of the message content, which might be different from the sender of the message. When using digital signatures, valid keystore and truststore files must be configured on the Web Server.

Encryption

The purpose of encryption is to modify the data such that it can only be understood by its intended audience. This modification is accomplished by substituting an encrypted element for the original content. When predicated on public key cryptography, encryption establishes the identity of the parties who can read the message.

Message Protection Policies

Message protection policies are defined for request message processing and response message processing. These policies are expressed in terms of requirements for source or recipient authentication. A source authentication policy requires that the identity of the entity that sent a message or that defined the content of a message be established in the message so that the message receiver can authenticate it. A recipient authentication policy represents a requirement that the message be sent such that the identity of the entities that can receive the message can be established by the message sender. The providers apply specific message security mechanisms so that the message protection policies are in SOAP Web Services messages.

Request and response message protection policies are defined when a provider is configured in a container. You can also configure application-specific message protection policies at the granularity of the web service port or operation within the Sun deployment descriptors of the application or application client. Where message protection policies are defined, the request and response message protection policies of the client must match the request and response message protection policies of the server.

Securing a Web Service

Web Services deployed on the Web Server are secured by binding SOAP-layer message security providers and message protection policies to the container in which the applications are deployed or to web service endpoints served by the applications. When the Web Server is installed, SOAP-layer message security providers are configured in the server-side container of the Web Server. The container or individual applications in the container can bind to them or to individual applications in the container. During installation, the providers are configured with a simple message protection policy that, if bound to a container or to an application, would cause the source of the content in all request and response messages to be authenticated by an XML digital signature.

Use the Admin Console and CLI to perform the following tasks:

By default, message layer security is disabled on the Web Server. For more information about how to configure message layer security for the Web Server, seeConfiguring the Web Server for Message Security. For more information about how to use Web Services security to protect all Web Services applications deployed on the Web Server, see Enabling Providers for Message Security.

Once this security is established, Web Services security will be applied to all Web Services applications deployed on the Web Server.

Configuring Application-Specific Web Services Security

Configure application-specific web services during application assembly by defining message-security-binding elements in the applications Sun deployment descriptors. Use these message-security-binding elements to associate a specific provider or message protection policy with a web services endpoint or service reference. You can also qualify these elements so that they apply to a specific port or method of the corresponding endpoint or referenced service.

Admin Console Tasks for Message Security

All the steps for setting up the Web Server for using message security can be accomplished using the Admin Console or the wadm command-line tool. For more information on message security, see Sun Java System Web Server 7.0 Update 2 Administrator’s Guide.

Support for message-layer security is integrated into the Web Server in the form of pluggable authentication modules. By default, message layer security is disabled on the Web Server. The tasks in this section provide the details for enabling, creating, editing, and deleting message security configurations and providers.

In most cases, you need to restart or reconfigure the Web Server after performing these tasks, especially to apply the change to applications already deployed on Web Server.

Procedure To Create a Message Security Provider

You can add or edit or modify the message protection policy. The provider type, implementation class, and provider-specific configuration properties should be modified.

  1. Login to the Admin Console.

  2. Select the configuration you want to modify and click Edit Configuration.

  3. Click the Java tab.

  4. Click the Authentication tab and scroll down to the SOAP Authentication.

    • To modify an existing provider, select the provider name and edit the values.

  5. Click New to add a provider.

  6. Add the new provider information

    In this page, following information is available for modification.

    Note –

    Only Name and class Name are required. If these two fields are not specified, no authentication is applied to request or response messages. All other values are optional.

    • Name: Identifier for this provider. You can use this identifier name to specify the default provider when using wadm.

    • Class Name: The Java implementation class of the provider. Server-side providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface.

      The request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Type the policies in message-sender order. For example, a requirement that encryption occur after content means that the message receiver expects to decrypt the message before validating the signature.

    • Request Authentication Source— Possible values are:

      • sender: Message-layer sender authentication, such as username and password

      • content: Content authentication, for example, digital signature

      • null: Source authentication of the request is not required

  7. Click the Add Property button to add additional properties.

    The provider shipped with the Web Server requires the server-config property. If other providers are used, refer to their documentation for more information on properties and valid values.

    • server.config: The directory and file name of an XML file that contains the server configuration information. This file is in the following location install_dir/samples/java/webapps/webservices/security/etc/wss-server-config-2.0.xml.

  8. Click OK.

Example 3–1 To set the response policy, replace the word request in the following commands with response.

Enabling Providers for Message Security

You can enable the message security Web Services endpoints by specifying the default provider on the server side or by specifying in the message-binding element in sun-web.xml.

If you enable a default provider for message security, you also need an appropriate message security on the client side.

Note –

You cannot specify a default provider using the Admin Console. You have to specify the default provider through the wadm command-line interface.

../bin/wadm set-config-prop --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test default-soap-auth-provider-name=msgsecurity-provider

ProcedureTo Delete a Message Security Provider

  1. Login to the Admin Console.

  2. Select the configuration you want to modify and click Edit Configuration.

  3. Click the Java tab.

  4. Click the Authentication tab and scroll down to SOAP Authentication.

  5. Click Delete.

Example 3–2 To Delete a Message Provider

To delete a message security provider through the command-line interface, type the following command:wadm delete-soap-auth-provider --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test msgsecurity-provider

Enabling Message Security Clients

Configure the message protection policies of client so that they are equivalent to the message protection policies of the server-side providers with which they interact. A typical stand-alone client is illustrated by the bundled sample fromwsdl-soap12.

Deploying Web Services

You deploy a web service endpoint to the Web Server just as you would deploy any servlet or application. You can use the wadm deploy command to publish the web service. The Sun sun-web.xml deployment descriptor file provides optional web service enhancements using webservice-endpoint. For more information, see Deploying the Server Configuration in Sun Java System Web Server 7.0 Update 2 Administrator’s Guide and Java Web Services Developer Pack 2.0.

Testing Web Services

To test Web Services you invoke a web service endpoint deployed on a web service client. A web service client is a Java program that makes a request to the service through a stub that acts as a proxy for the remote service. This stub is generated by the wsimport tool based on the WSDL file of the service.

ProcedureTo Invoke a Web Service Client

  1. WSDL of the deployed web service from URL http://host:port/context-root/endpoint?wsdl

  2. Call wsimport to generate the client-side artifacts using the deployed Web Services's WSDL.

  3. Implement the client to invoke the web service.

    Clients can run a deployed web service by accessing its service-endpoint-address URL, which has the following format:

    http://host:port/context-root/servlet-mapping-url-pattern

    The context-root is defined in the web.xml file. The servlet-mapping-url-pattern is defined in the web.xml file.

    In the following example, the context-root is my-ws and the servlet-mapping-url-pattern is /simple. You can view the WSDL file of the deployed service in a browser by adding ?WSDL to the end of the URL, for example,

    http://localhost:8080/my-ws/simple?WSDL.

Web Services Samples

The fromwsdl-soap1 application features a simple web service that is implemented by a Java Servlet endpoint. The service endpoint interface defines a single operation, addNumbers, which takes two positive integers, and returns an integer that is the sum of the two input integers.

The fromwsdl-soap12 sample application demonstrates how to use the WS-Security functionality to secure an existing Web Services application. The instructions helps you to enable the WS-Security functionality of the Web Server so that it is used to secure the fromwsdl-soap12 application.

The fromwsdl-soap12 sample application is installed in the install_dir/samples/java/webapps/webservices/security/fromwsdl-soap12/ directory.