27 Configuring Oracle User Messaging Service

27.1.1 Components

There are three types of components that make up Oracle User Messaging Service. These components are standard Java EE applications, making it easy to deploy and manage them using the standard tools provided with Oracle WebLogic Server.

• UMS Server: The UMS Server orchestrates message flows between applications and users. The server routes outbound messages from a client application to the appropriate driver, and routes inbound messages to the correct client application. The server also maintains a repository of previously sent messages in a persistent store, and correlates delivery status information with previously sent messages.

• UMS Drivers: UMS Drivers connect UMS to the messaging gateways, adapting content to the various protocols supported by UMS. Drivers can be deployed or undeployed independently of one another depending on what messaging channels are available in a given installation.

• UMS Client applications: UMS client applications implement the business logic of sending and receiving messages. A UMS client application might be a SOA application that sends messages as one step of a BPEL workflow, or a WebCenter Spaces application that can send messages from a web interface.

In addition to the components that make up UMS itself, the other key entities in a messaging environment are the external gateways required for each messaging channel. These gateways are not a part of UMS or Oracle WebLogic Server. Since UMS Drivers support widely-adopted messaging protocols, UMS can be integrated with existing infrastructures such as a corporate email servers or XMPP (Jabber) servers. Alternatively, UMS can connect to outside providers of SMS or text-to-speech services that support SMPP or VoiceXML, respectively.

27.1.2 Architecture

The system architecture of Oracle User Messaging Service is shown in Figure 27-1.

For maximum flexibility, the components of UMS are separate Java EE applications. This allows them to be deployed and managed independently of one another. For example, a particular driver can be stopped and reconfigured without affecting message delivery on all other channels.

Exchanges between UMS client applications and the UMS Server occur as SOAP/HTTP web service requests for web service clients, or through Remote EJB and JMS calls for BPEL messaging activities. Exchanges between the UMS Server and UMS Drivers occur through JMS queues.

Oracle UMS server and drivers are installed alongside SOA or BAM in their respective WebLogic Server instances. A WebCenter installation includes the necessary libraries to act as a UMS client application, invoking a server deployed in a SOA instance.

Figure 27-1 UMS architecture

Description of "Figure 27-1 UMS architecture"

27.3.1 How to Set the Storage Method

Use the Basic Configuration page to set deployment type for the Messaging Server (that is, select the storage method for run time and management data) and add (or remove) the User Messaging Preference Business Terms that are used for creating message filters.

Select Persistent (the default) to enable entries and the Messaging Store to persist when the server has been restarted. In the Transient mode (which is recommended for lightweight deployments), the Messaging Server does not maintain any data stored in the Messaging Store after a restart.

27.3.2 How to Add or Remove User Messaging Preferences Business Terms

The Basic Configuration page enables you to add or remove the business terms used to construct the message filters in User Message Preferences. For more information about building messaging filters with business terms, refer to Adding Business Terms.

27.4.1 How to Configure a Driver

To configure a driver:

1. Log into the Enterprise Manager Fusion Middleware Control console as an administrator.

2. Expand the Fusion Middleware folder (Figure 27-4).

   Figure 27-4 Expanding the UMS Folder

   
   Description of "Figure 27-4 Expanding the UMS Folder"
   
   

3. Navigate to the User Messaging Service Home page.

4. Click usermessagingserver(soa_server1). The Associated Drivers page appears.

   Figure 27-5 Drivers Associated with the UMS Instance

   
   Description of "Figure 27-5 Drivers Associated with the UMS Instance"
   
   

5. Select the Local tab to access the drivers collocated with the UMS server instance. These drivers may or may not be registered with the UMS server depending on whether or not they are properly configured. The ALL tab lists all drivers that are deployed in the domain and registered to all the UMS server instances.

6. Find the Email driver in the list, and then click the adjacent Configure Driver icon.

   The configuration page displays (Figure 27-6).

   Figure 27-6 The Basic Configuration Page for a Selected Driver

   
   Description of "Figure 27-6 The Basic Configuration Page for a Selected Driver"
   
   

7. If needed, expand the Driver-Specific Configuration section and configure the driver parameters. For more information, see Section 27.4.1.1, "About Driver Properties".

value="->mapName:keyName"    (mapName is the driver target name, and the key is <parameter_name>.<username>)

<Property value="-&gt;
/Farm_base_domain/base_domain/server_soa/usermessagingdriver-email:
OutgoingPassword.ouser" encodedCredential="true" 
type="java.lang.String" mandatory="no" name="OutgoingPassword" description="oracle.sdp.messaging.EmailDriverConfig.outgoingPassword"/>

http://<host>:<port>/sdpmessaging/parlayx/SendMessageService

27.5.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 fails because the notification SOAP request is missing the required headers.

27.5.2 Enabling UMS Service Security

To enable a policy for an UMS 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 want to secure.

27.5.3 Enabling Client Security

Web service client security must be enabled programmatically. When using the client libraries described in Parlay X Messaging Client API and Client Proxy Packages (in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite), 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 27-25) should be added to the configuration map in addition to other required properties such as the endpoint address.

import oracle.sdp.parlayx.multimedia_messaging.send.SendMessageClient
 
...
 
Map<String, Object> config = new HashMap<String, Object>();
config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ums_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");
 
SendMessageClient sendClient = new SendMessageClient(config);

27.5.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 UMS server are in the same domain, then they share a keystore and credential store.

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

27.5.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 be required 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 UMS web service, and application "B" is a web service client to a web service in another domain, then A's requests must be encrypted using the public key of the UMS domain, and B's requests must be encrypted using the public key of the other domain. You can accomplish this goal by overriding the keystore alias used by OWSM for each request:

• Import (for example) the UMS public key with alias "ums_public_key", and the other public key with alias "other_public_key".

• When creating an UMS 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 "ums_public_key" as shown in Example 27-2.

  Example 27-2 Client Aliases

  import oracle.sdp.parlayx.multimedia_messaging.send.SendMessageClient
   
  ...
   
  Map<String, Object> config = new HashMap<String, Object>();
  config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ums_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, "ums_public_key")
  SendMessageClient sendClient = new SendMessageClient(config);
  

• The other web service client similarly must 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.

27.5.6 Securing JMS Resources

This (optional) procedure enables administrators to restrict access to the Oracle User Messaging Service's JMS resources (such as queues) for enhanced security.

To secure the JMS system resources, lock all JMS sub-deployments that start with the name UMSJMSSystemResource (there may be multiple automatically-created resources for UMS in a multi-server or cluster deployment) with the role OracleSystemRole. Do this using the WebLogic Console, or you may run a WLST script (available at $ORACLE_HOME/communications/bin/secure_jms_system_resource.py) as follows:

$ORACLE_HOME/common/bin/wlst.sh
$ORACLE_HOME/communications/bin/secure_jms_system_resource.py
--username=<admin_username> --password=<password>
--url=t3://<admin-host>:<admin-port> --jmsSystemResource
<UMSJMSSystemResource> --role OracleSystemRole

For example:

$ORACLE_HOME/common/bin/wlst.sh
$ORACLE_HOME/communications/bin/secure_jms_system_resource.py
--username=weblogic --password=<password> --url=t3://localhost:7001
--jmsSystemResource UMSJMSSystemResource --role OracleSystemRole

By default, the UMS system runs as the user OracleSystemUser for accessing JMS resources. If the user OracleSystemUser does not exist, or you secure the UMS JMS resources with any other role that some other user has been granted, you must override the default user identity used by the UMS system by specifying an alternate username for the following JVM system property when you start the container:

oracle.ums.system.user=<username>

For example, if the user is MySystemUser, you can pass the JVM system property on command line as: -Doracle.ums.system.user=MySystemUser