18 Parlay X Web Services Architecture

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

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

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 OWLCS 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 application 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.

18.2 Web Service Security

By default, all deployed OWLCS web services are unsecured. Web Service Security should be enabled for any services that will be deployed in a production environment.

OWLCS supports the use of Oracle Web Services Manager WS-Security policies to protect OWLCS web services. For more information about Oracle Web Services Manager, see "Using Oracle Web Service Security Policies", in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

The recommended security configuration for OWLCS web services uses Security Assertion Markup Language (SAML) tokens to pass identities between web service clients and OWLCS. With SAML tokens, instead of the web service client passing a username and password to OWLCS, a trust relationship is established between the client and OWLCS by means of exchanging certificates. Once this keystore configuration is in place, the web service client passes only the user identity, and vouches for the fact that it has authenticated the user appropriately.

The recommended policies to use for OWLCS web services are:

  • oracle/wss11_saml_token_with_message_protection_service_policy (server-side)

  • oracle/wss11_saml_token_with_message_protection_client_policy (client-side)

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

18.2.2 Enabling OWLCS Service Security

To enable a policy for an OWLCS web service, follow the steps in "Configuring Oracle WSM Security Policies in Administration Console" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server, selecting policy oracle/wss11_saml_token_with_message_protection_service_policy. This configuration must be repeated for each service that you wish to secure.

18.2.3 Enabling Client Security

Web service client security must be enabled programmatically. When using the client libraries described in Oracle WebLogic Communication Services Developer's Guide, WS-Security policy configuration is provided when a client object is constructed. The client constructors take an argument of type Map<String, Object>. In general when using SAML authentication, the key/value pairs (Table 18-1) should be added to the configuration map in addition to other required properties such as the endpoint address.

Table 18-1 Client security keys

Key Type Typical Value

oracle.sdp.parlayx.ParlayXConstants.POLICIES

String[]

oracle/wss11_saml_token_with_message_protection_client_policy

javax.xml.ws.BindingProvider.USERNAME_PROPERTY

String

<valid username>

oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY

String

(optional) keystore alias for target service. See Client Aliases.


Example 18-1 Web Service Client Security

import oracle.sdp.parlayx.presence.consumer.PresenceConsumerClient;
 
...
 
Map<String, Object> config = new HashMap<String, Object>();
config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, owlcs_url);
config.put(oracle.sdp.parlayx.ParlayXConstants.POLICIES, new String[] {"oracle/wss11_saml_token_with_message_protection_client_policy"});
config.put(javax.xml.ws.BindingProvider.USERNAME_PROPERTY, "test.user1");
 
PresenceConsumerClient presenceClient = new PresenceConsumerClient(config);

18.2.4 Keystore Configuration

In order to use the recommended WS-Security policy, you must configure a keystore containing the public and private key information required by OWSM. Refer to "Configuring the Credential Store Using WLST" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for information on how to configure the keystore and corresponding credential store entries.

  • If both your web service client and OWLCS server are in the same domain, then they share a keystore and credential store.

  • If your web service client and OWLCS server are in different domains, then you must import the OWLCS public key into your client domain's keystore, and must import your client domain's public key into the OWLCS keystore.

18.2.5 Client Aliases

When using certain WS-Security policies such as the SAML policy recommended here, the client must use the server's public key to encrypt the web service request. However, there is generally only one keystore configured per domain. Therefore, if you have a domain in which there are web service clients that communicate with web services in multiple other domains, then you may need to override the default keystore entry used by OWSM.

For example, if you have a domain in which application "A" is a web service client to a SOA web service, and application "B" is a web service client to an OWLCS web service, then A's requests must be encrypted using the public key of the SOA domain, and B's requests must be encrypted using the public key of the OWLCS domain. You can accomplish this goal by overriding the keystore alias used by OWSM for each request.

  • Import the two server domain's public keys into the client domain's keystore using different keystore aliases. For example, import the OWLCS public key with alias "owlcs_public_key", and the SOA public key with alias "soa_public_key".

  • When creating an OWLCS web service client, specify the recipient keystore alias parameter, setting the key to oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY and the value to "owlcs_public_key" as shown in Example 18-2.

    Example 18-2 Client Aliases

    import oracle.sdp.parlayx.presence.consumer.PresenceConsumerClient;
     
    ...
     
    Map<String, Object> config = new HashMap<String, Object>();
    config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, owlcs_url);
    config.put(oracle.sdp.parlayx.ParlayXConstants.POLICIES, new String[] {"oracle/wss11_saml_token_with_message_protection_client_policy"});
    config.put(javax.xml.ws.BindingProvider.USERNAME_PROPERTY, "test.user1");
    config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY, "owlcs_public_key")
    PresenceConsumerClient presenceClient = new PresenceConsumerClient(config);
    
  • The SOA or other web service client will similarly need to override the keystore alias, but the exact mechanism may differ. For example if using a JAX-WS client stub directly, then you can add the override property to the JAX-WS request context. See "Policy Configuration Overrides for the Web Service Client" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for more details.

18.3 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. The web services are dependent on the following shared libraries: oracle.sdp.client, oracle.sdp.platform, oracle.sdp.presencecommons.

Your client applications need to import (and be compiled against) the oracle.sdp.client shared library that is provided with OWLCS. This consists of importing parlayx.jar into your projects.

In addition to compiling against the oracle.sdp.client shared library, this shared library should also be available in the target runtime environment (that is, oracle.sdp.client is deployed as a shared library in your target Weblogic Server).

In addition to the shared library above, the OWLCS 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-<version>.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 OWLCS server to be able to invoke the messaging notification Web service.

  • presencewsnotification-<version>.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 OWLCS server can invoke the presence notification Web service.