8 OCMS Parlay X Web Services Architecture

This chapter describes the architecture, security, and installation for the OCMS Parlay X Web Services. This chapter contains the following sections:

• "Architecture of Web Service Client Applications"

• "Web Service Security"

• "Installing the Web Services"

Architecture of Web Service Client Applications

The architecture of client applications is such that one client of a Web service will be acting on behalf of many end users of the system (Figure 8-1).

Multiple users can simultaneously connect to the same Web service client, which will act on behalf of those users when invoking the Web Service. Note the following usage guidelines:

• Security – the OCMS Web server on which the Web services are running authenticates the client and not the end users. The client is a trusted entity and once the client is authenticated it is assumed that all end users of the client are authenticated. This places the task of authenticating end users on the Web service client. For the client to be correctly authenticated, they must connect with pre-determined authentication credentials.

• The Web client need not invoke all the Web services – that is, a web client might invoke methods on the SendMessage Web service only, and therefore has no need to concern itself with the other Web services. However, there are instances where the needs of the client application dictate that it invokes specific methods on the different web services in a specific order to achieve its goals. For example, a client applications for sending messages that also wants to receive message notifications for all the messages sent must first call the startMessageNotification method of the MessageNotificationManager interface before it can receive notifications for messages sent.

Web Service Security

The default deployments of all Web services on the OCMS server require that the clients authenticate themselves using DIGEST authentication (requires username and password). To support this, the parlayxclient-10.1.3.4.jar includes runtime xml descriptors (<interface-name>Binding_Stub.xml) that are configured to support inclusion of the required headers for DIGEST authentication from the clients. Therefore, clients using the OCMS parlayxclient-10.1.3.4.jar need only set the username and password for the specific Web service client they are using. For instance:

SendMessageClient smc = new SendMessageClient();
...
smc.setUsername(Òoracle-ws-clientÓ);
smc.setPassword(ÒsecretÓ);

The username and password used for authentication must be pre-determined and configured on the OCMS web server in order for authentication to succeed. Configuring the correct username and password on the server depends on the choice of security provider to be configured. For instance, consider configuring the username and password of the multimedia messaging web services (this includes SendMessge, ReceiveMessage and MessageNotificationManager services) to use a file based security provider (the simplest). Perform the following steps on the OCMS server:

1. Log onto Application Server Control Enterprise Manager.

2. Select Administration > Security > Security Providers and edit the messagingwebservice security provider.

3. Verify that the default security provider is a File-Based Security Provider. To modify it, select Change Security Provider > File-Based Security Provider, select "Use the OC4J instance default file based security provider" and click OK.

4. Select the Realms and click the Users link by the default realm (jazn.com).

5. Choose Create to add a new user.

6. Enter the user name (for example, oracle-ws-client), password (for example, secret) and add the users user role. Select OK. You can now connect to any of the multimedia messaging web services as user "oracle-ws-client" with password "secret", using the following code on the client side:

smc.setUsername("oracle-ws-client");
    smc.setPassword("secret");

Typically, client application developers do not need to know the details of setting up authentication credentials on the server side, since that would be handled by the server administrator.

If the server administrator chooses to change the authentication requirements on the Web services (for instance, to use a PLAINTEXT username and password instead of DIGEST), they will provide instructions on new requirements. This typically requires unpacking the parlayxclient-10.1.3.4.jar, modifying <interface-name>Binding_Stub.xml, and re-packaging the updated parlayxclient-10.1.3.4.jar for use when running your application. The instructions provided by your server administrator should include the relevant details.

Web Service Security on Notification

The different Web services include corresponding notification Web services (MessageNotification, PresenceNotification) that run on the client side and receive notifications (message delivery status, message receipt, presence status change) when the appropriate event occurs. This implementation does not provide for the use of Web Service security (WS-Security) by default during notification of the clients. That is, the server assumes that the notification Web services running on the client side do not use WS-Security, and makes no attempt to authenticate itself when sending notifications. If you do enable WS-Security on the client side, the notification from the server will fail because the notification SOAP request will be missing the required headers.

Installing the Web Services

The Web services are packaged as a standard .ear file and can be deployed the same as any other Web services through Enterprise Manager. The .ear file contains two .war files that implement the two interfaces. If the Web services are deployed on the same server as the presence server, they must be a child application of the presence server.

Your client applications need to import (and be compiled against) the parlayx libraries that are provided with OCMS. This consists of importing the following jars into your projects:

• parlayx-10.1.3.4.jar – this jar contains all the 'unmodified' classes – classes that are generated by the oracle web services assembler and are not to be modified/customized. This includes the types (common types as well as the types for different web services), runtime classes, and local classes.

• parlayxclient-10.1.3.4.jar – this jar contains all the modified <interface-name>Client classes (for instance, PresenceConsumerClient, and SendMessageClient) that have been specialized to work with the corresponding Web services deployed with Oracle Communication and Mobility Server.

In addition to compiling against these jar files, they should be also included in the runtime configuration of the client (this might mean, for instance, setting the classpath in case of a console client, or including the jars in the deployed war/ear in a client application deployed into a J2EE container).

In addition to the jars above, the OCMS installation contains war files for the notification Web services. These war files contain all the necessary jar files that developers need to import to enable notification for the different Web services:

• messagingwsnotification-10.1.3.4.war – deployable war file that contains jars that should be imported when building a client intends to receive notifications for message delivery status and message reception. This war should also be deployed along with the client application in order for the OCMS server to be able to invoke the messaging notification Web service.

• presencewsnotification-10.1.3.4.war – deployable war file that contains jars that should be imported when building a client intends to receive notifications for presence status changes. This war should also be deployed along with the client application so that the OCMS can invoke the presence notification Web service.