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.

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:

JAX-WS 2.0
(JSR 224)-The Java API for XML-based JAX-WS 2.0 is the key specification for component-based
web service development, and governs the standard mappings between WSDL/XML
schema and the Java platform. It is the next generation of JAX-RPC.

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.

apt— The Annotation Processing Tool
(APT) tool is part of Java SE 5. It programmatically processes the annotations
and generates the JAX-WS portable artifacts from an annotated Java source
file.

wsgen- The wsgen tool reads a service endpoint
implementation class and generates all of the portable artifacts for a JAX-WS
web service.

wsimport- The wsimport tool reads a WSDL
and generates all the required artifacts for web service development, deployment,
and invocation.

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.

To Create Web Services from a Java Source

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

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

Deploy the WAR file to Web Server.

To Create Web Services from Java Classes

Use wsgen to generate portable artifacts.

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

Deploy the WAR file to Web Server.

To Create Web Services from a WSDL file

Use wsimport to generate portable artifacts.

Implement the service endpoint.

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.

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

Securing a web service

Securing a sample application

Configuring the Web Server for message security

Admin Console tasks for message security

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:

Configuring message security providers on the Web Server

Managing user databases

Managing the keystore and truststore files

Deploying the samples program fromwsdl-soap12,
which demonstrates the message layer web services security

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:

Specifying at application assembly any required application-specific
message protection policies if such policies have not already been specified
by upstream roles (the developer or assembler).

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:

Determining whether an application-specific message protection
policy is required by the application. If the policy is required, the developer
or assembler works with the application deployer and ensures that the required
policy is specified during application assembly.

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:

To bind the existing providers for use by the server-side
containers of the Web Server

To modify the message protection policies enforced by the
providers

To create new provider configurations with alternative message
protection policies

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.

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.

To create a message security provider

To enable providers for message security

To delete a message security provider

To enable message security for stand-alone clients

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.

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.

Login to the Admin Console.

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

Click the Java tab.

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

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

Click New to add a provider.

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

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.

Click OK.

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

To Delete a Message Security Provider

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

Click the Java tab.

Click the Authentication tab and scroll down to SOAP Authentication.

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.

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.

To Invoke a Web Service Client

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

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

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.