4 Configuring Oracle User Messaging Service

This chapter describes how to configure and secure Oracle User Messaging Server (UMS) in your environment.

This chapter includes the following topics:

• Section 4.1, "Accessing User Messaging Service Configuration Pages"

• Section 4.2, "Configuring User Messaging Server"

• Section 4.3, "Configuring User Messaging Service Drivers"

• Section 4.4, "Configuring User Messaging Service Access to the LDAP User Profile"

• Section 4.5, "Using Oracle User Messaging Service for Group Messaging"

• Section 4.6, "Configuring Automatic Message Resend"

• Section 4.7, "Securing the Oracle User Messaging Service"

4.1 Accessing User Messaging Service Configuration Pages

You can configure UMS through Oracle Enterprise Manager Fusion Middleware Control. For more information, see Administering Oracle Fusion Middleware with Fusion Middleware Control.

Alternatively, you can also use WebLogic Scripting Tool (WLST) to configure UMS. For more information, see WLST Command Reference for Infrastructure Components.

4.2 Configuring User Messaging Server

UMS is deployed as one enterprise archive for the server and one enterprise archive per driver type. The configuration can be defined at the managed server level or cluster level, where cluster level overrides domain level. It is possible to configure the server and drivers using WebLogic Scripting Tool (WLST) and Enterprise Manager (EM).

If the User Messaging Server configuration is defined at the cluster level, then the cluster name along with all the following properties must be specified.

Table 4-1 Properties for Configuring User Messaging Server

Name	Description	Mandatory
AppReceivingQueuesInfo	The default set of queues from which the application will dequeue received messages.	Y
DuplicateMessageRetryDelay	The delay period for deferring processing of a possible duplicate message	Y
EngineCommandQueuesInfo	The set of queues from which the engine will dequeue command messages sent by other messaging components	Y
EnginePendingReceiveQueueInfo	The queue from which the engine will dequeue pending messages. The format for this value is JNDIQueueConnectionFactoryName:JNDIQueueName	Y
EngineReceivingQueuesInfo	The set of queues from which the engine will dequeue received messages	Y
EngineSendingQueuesInfo	The set of queues from which the engine will dequeue sent messages	Y
JpsContextName	The name of the Java Platform Security (JPS) context to use when getting an Identity Store Service instance. Empty value leads to default JPS context	Y
ReceivedmessageStatusEnabled	Enable received message status reporting - if false, client library does not return delivery status to engine	Y
ResendDefault	The default number of automatic resends upon delivery failure. You can override this property programmatically on a per message basis. The upper limit is the value specified in the configuration parameter ResendMax.	Y
ResendDelay	The delay in seconds between automatic resends	Y
ResendMax	The max number of automatic resends upon delivery failure	Y
SecurityPrincipal	The default system user used	Y
SessionTimeout	The duration to wait before a session timeout when the session flag is set by a Driver or Messaging Client Application	Y
SupportedDeliveryTypes	The set of delivery types supported by this server	Y

4.3 Configuring User Messaging Service Drivers

UMS supports multiple configurations. This means that, one deployed driver instance can handle more than one configuration. This makes it possible to have one instance of a particular driver configured differently in a domain without having to deploy several instances of that driver. All the drivers support multiple configuration. You can create multiple configurations of a single deployment of the drivers using a unique name at each configuration. Though possible, it is recommended not to use the same configuration name while creating multiple configurations for a particular driver instance, as this may lead to unintended results.

Since UMS can be deployed in a cluster or a server, the configuration of drivers can be done at the cluster or server level. It is recommended that the configuration be done at the same level as that of the deployment. However, exceptional scenarios might justify creating configuration at a level different from that of the deployment level.

You can configure UMS drivers by using Oracle Enterprise Manager Fusion Middleware Control. Alternatively, you can configure the UMS drivers by using the WLST command configUserMessagingDriver. For more information about this command, see WLST Command Reference for Infrastructure Components.

This section discusses the following topics:

• Configuring a Driver

• Configuring the Messaging Extension Driver

• Configuring the Email Driver

• Configuring the SMPP Driver

• Configuring the XMPP Driver

• Configuring the Twitter Driver

• Configuring the APNS Driver

Note:

UMS drivers can be configured at the cluster level or server level. For more information, see Section 4.2, "Configuring User Messaging Server" to ensure that you select the appropriate configuration level.

4.3.1 Configuring a Driver

You can navigate to the driver configuration page from any one of the following:

• Associated Drivers table on the User Messaging Service home page

• Driver Properties menu for the driver target in the Target Navigation pane

• Driver Properties menu on the User Messaging Service home page

To configure a driver, perform the following tasks:

1. Log in to Oracle Enterprise Manager Fusion Middleware Control as an administrator.

2. Navigate to the User Messaging Service home page.

   
   Description of the illustration ''ns_login.gif''
   
   

3. Click usermessagingserver(AdminServer). The Associated Drivers page appears as shown in the following figure.

   
   Description of the illustration ''ns_assoc_drv.gif''
   
   

4. 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 they are properly configured. The ALL tab lists all drivers that are deployed in the domain and registered to all the UMS server instances.

5. Choose a driver from the list, and click the corresponding Configure Driver icon.

   The configuration page that lists all the configurations applied to this driver deployment will be displayed, and the administrator can create, edit, or delete a configuration. User Messaging drivers are configured differently in the following scenarios:

   1. For the email driver (only email driver supports multiple configuration in 12.1.3), the configuration depends on whether the driver is deployed in a clustered or a non-clustered environment.

      • If the driver is deployed in a cluster, for instance a_ums_cluster, then all the email configurations for cluster a_ums_cluster and also for the whole domain will be listed. The cluster-level configuration will override the domain-level configuration, if they have the same configuration name.

      • For a driver deployed in a non-clustered managed server, the configuration will be at the server level.

   For information about support for multiple configuration, and the relationship between cluster level and domain level configuration, refer to Section 4.2, "Configuring User Messaging Server" and Section 4.3, "Configuring User Messaging Service Drivers".

6. Click Create, or select a driver configuration from the list and click Edit. The Driver Properties page is displayed as shown in the following figure. You can create a new configuration or update the existing one.

   
   Description of the illustration ''ns_configdriver_latest.gif''
   
   

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

8. To validate if the configuration properties are in correct format and valid in the deployment environment, you can 'test' the driver configuration parameters that you have entered. Click the Test button on the page. Click OK to continue.

   Note:

   Even if the testing does not succeed, you can still save the configuration.

4.3.1.1 Introduction to Driver Properties

UMS drivers share common properties (listed in Table 4-2) that are used by the Messaging Engine when routing outbound messages.

Table 4-2 Common Driver Properties

Name	Description	Mandatory Property
Capability	Sets the driver's capability to send or receive messages. The values are SEND, RECEIVE, and BOTH.	Yes
Cost	Only used for driver configuration selection between multiple driver configurations of the same type, and only when required by the client application, The cost level of the driver (from 0 - 10). 0 is least expensive; 10 is most expensive. If the value is not in this range, cost is considered to be 0.	No
DefaultSenderAddress	If the UMS Message has no Sender Address of the specific DeliveryType that the driver supports, then the driver may use the DefaultSenderAddress as the Sender Address. The sample DefaultSenderAddress is EMAIL:[e-mail].	No
SenderAddresses	The list of sender addresses that the driver is configured to handle. A driver with specified SenderAdresses will be selected only for an outgoing message that has a matching Sender Address. A driver that has not specified any SenderAdresses is considered to be able to handle any outgoing message regardless of the Sender Address of the message. The list should consist of UMS addresses separated by comma, for example EMAIL:[e-mail] or EMAIL:[e-mail],EMAIL:[e-mail]. The matching is case insensitive.	No
Speed	Only used for driver configuration selection between multiple driver configurations of the same type, and only when required by the client application. The speed level of the driver (from 0-10, with 10 being the fastest).	No
SupportedCarriers	A comma-delimited list of supported carriers.	No
Configuration Level	Enables driver configuration at the server level or at the cluster level. If Server level is selected, then the server name must be specified. If Cluster level is selected, then the cluster name must be specified.	Yes
SupportedContentTypes	The content type supported by the driver.	Yes
SupportedDeliveryTypes	The delivery types supported by the driver.	Yes
SupportedProtocols	A comma-delimited list of supported protocols.	No
SupportedStatusTypes	The status types supported by the driver.	No
Supported Application Names	The application name supported by the driver.	No

4.3.1.2 Securing Passwords

Sensitive driver properties (namely, passwords) can be stored securely in the credential store using Oracle Enterprise Manager Fusion Middleware Control. Properties are marked with the flag Encoded Credential and have a custom entry form field.

To store a sensitive driver property securely, perform the following tasks:

1. Log in to Oracle Enterprise Manager Fusion Middleware Control, and navigate to the driver configuration page of the selected driver.

   The configuration page that lists all the configurations applied to this driver deployment will be displayed, and the administrator can create, edit, or delete a configuration.

2. Click Create to create a new configuration or select a configuration and click Edit to edit an existing configuration.

   The Driver properties page appears.

3. In the Driver-Specific Configuration table, locate the properties with the Encoded Credential flag set.

4. Select the credential type from the Type of Password drop-down list in the adjoining Value column as shown in the following figure.

   
   Description of the illustration ''driver_securingpass.gif''
   
   

5. Depending on the selected credential type, you are prompted to enter the username and/or password. There are the following three options:

   • Indirect password, create new user (default option): specify the username and real password; the password is stored in the credential store with the username as part of the key. The key and a fixed folder (map name) are stored in the driver deployment's file.

   • Indirect password, use existing user: choose an existing indirect username/key in the credential store (to reference the password you stored previously).

   • User a clear text password: specify the password, and it is stored directly in the driver deployment file.

6. Click OK to save changes.

7. Restart the driver application or the container for the changes to take effect.

You can check the password in the driver deployment directory's file. For an indirect password, the format is:

value="->mapName:keyName"    (mapName can be any name of the user's choice, and the key is <parameter_name>.<username>)

4.3.1.3 Configuring the Messaging Extension Driver

The extension driver extends the messaging capability of UMS by enabling support for arbitrary administrator-defined channels (protocols) and delivering the notifications for such channels to an administrator-defined web service listener endpoint.

Note:

An instance of this driver is deployed, but not targeted to any servers in the default. To enable this driver instance, it must be targeted to the appropriate servers where UMS (usermessagingserver) is running.

4.3.1.3.1 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Table 4-3 lists the common properties of the Extension driver. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-3 Extension Driver Common Properties

Name	Mandatory	Default Value
InstanceName	Yes	Extension-Driver
Capability	Yes	SEND
SupportedDeliveryTypes	Yes	URI
SupportedContentTypes	Yes	text/plain, text/html, text/xml
SupportedStatusTypes	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	No
Speed	No
SupportedCarriers	No
Configuration Level	Yes	Server/Cluster
SupportedProtocols	No	popup
SenderAddresses	No
DefaultSenderAddress	No
Supported Application Names	No	Empty

4.3.1.3.2 Custom Properties

Table 4-4 lists properties specific to this driver and generally associated with configuring a remote endpoint at which to deliver extension notifications:

Table 4-4 Extension Driver Custom Properties

Name	Description	Mandatory
Group Name	The name of this extension endpoint configuration group.	Yes
Endpoint URL	Remote endpoint listener URL.	Yes
Mapped Domain	The extension endpoint used to deliver messages where the domain part of the recipient URI matches this value.	No
Protocol	The extension endpoint used to deliver messages where the protocol (scheme) part of the recipient URI matches this value.	Yes
Security Policies	Comma-separated list of WS-Security policies to apply to this endpoint.	No
Username	Username to propagate through WS-Security headers.	No
Keystore Alias	Keystore alias to use for looking up WS-Security policy public keys.	No
Credential Store Key	Key to use for looking up the WS-Security username and password from the Oracle Web Services Management credential store map.	No

4.3.1.3.3 Extension Driver Security

If the remote extension endpoint is secured using WS-Security, then additional configuration of the extension driver is required. There are two typical WS-Security configurations that are supported. The extension driver can either use SAML tokens or username tokens.

To use extension driver security:

1. To use SAML tokens, the Security Policies configuration property should contain value oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy, and the Keystore Alias configuration property should contain a valid alias for keystore entries that is accepted by the remote extension endpoint.

2. To use username tokens, the Security Policies configuration property should contain value oracle/wss11_username_token_with_message_protection_client_policy, and the Credential Store Key configuration property should contain a valid alias for a credential store entry that is accepted by the remote extension endpoint.

For more details about using WS-Security policies and configuring OWSM, see Oracle Fusion Middleware Administering Web Services.

4.3.1.4 Configuring the Email Driver

The email driver both sends and receives messages (that is, its capability property is set to both by default). The email driver sends messages over SMTP and uses either IMAP or POP3 for receiving messages.

4.3.1.4.1 Common Properties

Table 4-5 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-5 Common Email Properties

Name	Mandatory	Default Value
InstanceName	Yes	Email-Driver
Capability	Yes	Both
SupportedDeliveryTypes	Yes	Email
SupportedContentTypes	Yes	text/plain, text/html, multipart/mixed, multipart/alternative, multipart/related
SupportedStatusTypes	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE, USER_REPLY_ACKNOWLEDGEMENT_SUCCESS, USER_REPLY_ACKNOWLEDGEMENT_FAILURE
Cost	No	N/A
Speed	No	N/A
SupportedCarriers	No	N/A
Configuration Level	Yes	Server/Cluster
Supported Protocols	No	N/A
SenderAddresses	No	N/A
DefaultSenderAddress	No	N/A
Supported Application Names	No	Empty

4.3.1.4.2 Email Custom Properties

Table 4-6 lists properties specific to this driver and generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Table 4-6 Custom Email Properties

Name	Description	Mandatory	Default Value
MailAccessProtocol	Email receiving protocol. The possible values are IMAP and POP3. Required only if email receiving is supported on the driver instance.	No	IMAP
AutoDelete	This value indicates if the driver should mark the messages deleted after they have been processed. The default is Disabled. For the POP3 protocol, the messages are always deleted right after they are processed.	No	Disabled
Debug	This value indicates if the driver is running in Debug mode. When enabled, JavaMail prints out requests and responses between the email driver and the mail server to Fusion Middleware Control. The default is Disabled.	No	Disabled
CheckMailFreq	The frequency with which to retrieve messages from the mail server. The unit is in seconds and the default value is 30 seconds.	No	30
ReceiveFolder	The name of the folder from which the driver is polling messages. The default value is INBOX.	No	INBOX
OutgoingMailServer	The name of the SMTP server. This is mandatory only if email sending is required.	No	N/A
OutgoingMailServerPort	The port number of the SMTP server; typically 25.	No	25
OutgoingMailServerSecurity	The security setting used by the SMTP server. Possible values are None, TLS, and SSL. The default value is None.	No	None
OutgoingDefaultFromAddr	The default FROM address (if one is not provided in the outgoing message). Note: The OutgoingDefaultFromAddr property is deprecated, use DefaultSenderAddress instead. For more details about the DefaultSenderAddress property, see Common Properties.	No	N/A
OutgoingUsername	The username used for SMTP authentication. Required only if SMTP authentication is supported by the SMTP server.	No	N/A
OutgoingPassword	The password used for SMTP authentication. This is required only if SMTP authentication is supported by the SMTP server. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.	No	N/A
IncomingMailServer	The hostname of the incoming mail server. Required only if email receiving is supported on the driver instance.	No	N/A
IncomingMailServerPort	Port number of IMAP4 (that is, 143 or 993) or POP3 (that is, 110 or 995) server.	No	N/A
IncomingMailServerSSL	Indication to enable SSL when connecting to IMAP4 or POP3 server. The default is Disabled.	No	Disabled
IncomingMailIDs	The email addresses corresponding to the user names. Each email address is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. Required only if email receiving is supported on the driver instance.	No	N/A
IncomingUserIDs	The list of user names of the mail accounts from which the driver instance is polling. Each name must be separated by a comma, for example, foo,bar. This is required only if email receiving is supported on the driver instance.	No	N/A
IncomingUserPasswords	The list of passwords corresponding to the user names. Each password is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. This is required only if email receiving is supported on the driver instance. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.	No	N/A
ProcessingChunkSize	The number of messages processed during each message polling. The default is 100.	No	100
Disconnect After Poll	Whether or not to disconnect from the email server after message poll. Effective only for IMAP, as POP3 always disconnects.	No	False
ImapAuthPlainDisable	Indication to disable or enable plain text authentication (AUTHENTICATE PLAIN command) for IMAP user authentication. The default is Disabled.	No	Disabled. When this property is disabled, that means that plain text is allowed.

Note:

Multiple Incoming Email IDs/User IDs/Passwords will be added through a popup dialog (import from a CSV file or add in table), so that hundreds of ID/Passwords can be added.

4.3.1.5 Configuring the SMPP Driver

Short Message Peer-to-Peer (SMPP) is a popular GSM SMS protocols. UMS includes a prebuilt implementation of the SMPP protocol as a driver that can send and receive short messages. If the sending feature is enabled, the SMPP driver opens one TCP connection to the Short Message Service Center (SMS-C) as a transmitter for sending. If the driver's receiving feature is enabled, it opens another connection to the SMS-C as a receiver for receiving. Only two TCP connections (both initiated by the driver) are needed for all communication between the driver and the SMS-C.

Note:

The SMPP Driver implements Version 3.4 of the SMPP protocol and only supports connections to an SMS-C or an SMS gateway that supports this version.

4.3.1.5.1 Common Properties

Table 4-7 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-7 Common SMPP Properties

Name	Mandatory	Default Value
InstanceName	Yes	SMPP-Driver
Capability	Yes	Both
SupportedDeliveryTypes	Yes	SMS
SupportedContentTypes	Yes	text/plain
SupportedStatusTypes	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	No	N/A
Speed	No	N/A
SupportedCarriers	No	N/A
Configuration Level	Yes	Server/Cluster
Supported Protocols	No	N/A
SenderAddresses	No	N/A
DefaultSenderAddress	No	N/A
Supported Application Names	No	Empty

4.3.1.5.2 SMPP Custom Properties

Table 4-8 lists properties specific to this driver and generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Table 4-8 Custom SMPP Properties

Name	Description	Mandatory	Default Value
SmsAccountId	This value indicates the addresses that the SMPP driver is requesting messages for from the server. The value is specified as a UNIX Regular Expression. For example, "555" would specify a single address, and "^123|^789" would indicate all addresses starting with 123 or 789.	Yes	N/A
SmsServerHost	The name (or IP address) of the SMS-C server.	Yes	N/A
TransmitterSystemId	The account ID that is used to send messages.	Yes	N/A
ReceiverSystemId	The account ID that is used to receive messages.	Yes	N/A
TransmitterSystemType	The type of transmitter system. The default is Logica.	Yes	The default value is Logica.
ReceiverSystemType	The type of receiver system. The default is Logica.	Yes	The default value is Logica.
TransmitterSystemPassword	The password of the transmitter system. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.	Yes	N/A
ReceiverSystemPassword	The password for the receiver system. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.	Yes	N/A
ServerTransmitterPort	The TCP port number of the transmitter server.	Yes	N/A
ServerReceiverPort	The TCP port number of the receiver server.	Yes	N/A
DefaultEncoding	Used for incoming messages. If the SMS-C specifies the encoding to SMSC Default Alphabet, then this is the encoding that SMPP driver will assume. Choose from the drop-down list among the following: IA5, UCS2, GSM_DEFAULT, ISO-8859-1	No	IA5
PreferredEncoding	Used for outgoing messages. If set, the text will be encoded according to the PreferredEncoding parameter. If the encoding fails (i.e. a character cannot be encoded using the specified encoder) then the driver uses the 16-bit encoding UCS2. If not set, the driver will attempt to derive an encoding from the UMS Message Content-Type header. Choose from the drop-down list among the following: IA5, UCS2, GSM_DEFAULT, ISO-8859-1	No	IA5
LocalSendingPort	The local TCP port used by the SMPP driver to send messages to the SMS-C.	No	N/A
LocalReceivingPort	The local TCP port used by the SMPP driver to receive messages from the SMS-C.	No	N/A
LocalAddress	The hostname (or IP address) of the server that hosts the SMPP driver.	No	N/A
WindowSize	The window size for SMS. This value must be a positive number. Default is 1.	No	1
EnquireInterval	The interval, in seconds, to send an enquire message to the SMS-C. The default is 30 seconds.	No	30
ThrottleDelay	The delay, in seconds, between throttles. Default is 30.	No	30
BindRetryDelay	The minimum delay, in seconds, between bind entry attempts. Default is 30.	No	30
ResponseTimer	Time lapse allowed between SMPP request and response, in seconds. The default is 30.	No	30
RegisteredDeliveryMask	The registered delivery bit mask. The default is 0xFF, which does not change the delivery flag value.	No	0xFF
RangeSetNull	Set to true to set the address range field of BIND_RECEIVER to null. Set to false (the default value) to set the address range field to SmsSystemId. The default is Disabled.	No	Disabled
PriorityAllowed	The highest priority the SMPP Driver will set on a message to the SMS-C. The UMS Message priority set by the client application is translated into SMPP priority, but limited by PriorityAllowed. The range is 0 (normal) to 3 (highest). The default is 0.	No	0
BulkSending	Setting this value to enabled (the default) enables sending messages in bulk to the SMS-C.	No.	Enabled
PayloadSending	If you enable this property, the SMPP driver always uses the message_payload parameter that is defined in the SMPP specification, while sending a message to the SMS-C. The default is Disabled.	No	Disabled
SourceTon	The type of number (TON) for ESME address(es) served through SMPP receiver session. The default is 0.	No	0
SourceNpi	The numbering plan indicator (NPI) for ESME address(es) served through the SMPP receiver session. The default is 0.	No	0
DestinationTon	The TON for destination. The default is 0.	No	0
DestinationNpi	The NPI for destination. The default is 0.	No	0
MaxChunks	The maximum SMS chunks for a message. The default is -1 (no maximum).	No	-1 (no maximum)
ChunkSize	The maximum size of each SMS message chunk. Default is 160.	No	160
LongMessageSending	Supports sending long messages by setting the optional SMPP parameters sar_msg_ref_num, sar_total_segments and sar_segment_seqnum for fragmented messages. The default value is Enabled.	No	Enabled
DatagramMessageMode	Supports datagram message mode. The default is Disabled.	No	Disabled

4.3.1.6 Configuring the XMPP Driver

The XMPP Driver provides unidirectional or bidirectional access from Oracle Fusion Middleware to end users for real-time IM through the Extensible Messaging and Presence Protocol (XMPP). This driver enables end users to receive alert notifications or interactively chat with applications through their IM client of choice.

4.3.1.6.1 Common Properties

Table 4-9 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-9 Common XMPP Properties

Name	Mandatory	Default Value
InstanceName	Yes	XMPP-IM-Driver
Capability	Yes	Both
SupportedDeliveryTypes	Yes	IM
SupportedContentTypes	Yes	text/plain For the XMPP driver to be able to send messages, one part in the multipart/alternative message must be text/plain.
SupportedStatusTypes	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	No	N/A
Speed	No	N/A
SupportedCarriers	No	N/A
Configuration Level	Yes	Server/Cluster
Supported Protocols	No	N/A
SenderAddresses	No	N/A
DefaultSenderAddress	No	N/A
Supported Application Names	No	Empty

4.3.1.6.2 XMPP Custom Properties

The XMPP Driver includes the custom properties shown in Table 4-10.

Table 4-10 Custom XMPP Properties

Name	Description	Mandatory	Default Values
IMServerHost	Jabber/XMPP server hostname.	No	N/A
IMServerPort	Corresponding Jabber/XMPP server port. The default is 5222.	Yes	5222
IMServerUsername	Jabber/XMPP username with which you log in. You may also enter a complete Jabber ID if its domain name is different from the Jabber/XMPP server hostname (for example: myUserName or myUserName@xmpp-domain). Note: An attempt is made to register this user account if it does not exist and the server supports account registration.	No	N/A
IMServerPassword	Corresponding password for the username listed above. Includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, Use Cleartext Password) and Password.	No	N/A
SecurityMode	Security mode to use when making a connection to the server. Available options are: None (Security is disabled and only unencrypted connections are used), TLS (Security through TLS encryption is used whenever it is available), and SSL (Security through SSL encryption is used). The default is TLS.	No	TLS
SASLAuthenticationEnabled	Whether to use SASL authentication when logging into the server. If SASL authentication fails, then the driver tries to use non-SASL authentication. By default, SASL is enabled.	No	Enabled

4.3.1.7 Configuring the Twitter Driver

The Twitter driver is a UMS driver that communicates with the Twitter API server. It provides a bi-directional messaging service to/from the Twitter server. Thus, the Twitter driver enables the application users to publish their Twitter feed and receive response for the same.

4.3.1.7.1 Common Properties

Table 4-11 shows common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-11 Common Properties of the Twitter Driver

Name	Mandatory	Default Values
InstanceName	Yes	usermessagingdriver-twitter
Capability	Yes	SEND, RECEIVE
SupportedDeliveryTypes	Yes	URI
SupportedContentTypes	Yes	text/plain, text/html, text/xml
SupportedStatusTypes	Yes	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	No	N/A
Speed	No	N/A
SupportedCarriers	No	N/A
Configuration Level	Yes	Server/Cluster
Supported Protocols	No	N/A
SenderAddresses	No	N/A
DefaultSenderAddress	No	N/A
Supported Application Names	No	Empty

4.3.1.7.2 Twitter Custom Properties

Table 4-12 lists configurable properties specific to the Twitter driver.

Table 4-12 Custom Properties of the Twitter Driver

Name	Description	Mandatory	Default Values
Authentication Mode	This property specifies the authentication mode that the Twitter driver must use. Valid values are OAuth and xAuth.	Yes	xAuth
Username	The user name of the Twitter user.	This field is mandatory if the selected authentication mode is xAuth.
Password	The password of the Twitter user.	This field is mandatory if the selected authentication mode is xAuth.
Consumer Key	The public key of the Twitter user.	This field is mandatory if the selected authentication mode is OAuth.
Consumer Secret	The private key of the Twitter user.	This field is mandatory if the selected authentication mode is OAuth.
Access Token	The public key of a registered Twitter application.	This field is mandatory if the selected authentication mode is OAuth.
Access Token Secret	The private key of a registered Twitter application.	This field is mandatory if the selected authentication mode is OAuth.

4.3.1.8 Configuring the APNS Driver

The (Apple Push Notification Service) APNS driver is a UMS driver that communicates with the APNS API server. The certificates that you get from Apple for your application needs to be saved in the WLS server, in the OPSS subsystem. For more information on pre-requisites for configuring the APNS driver, see Section 4.3.1.8.1, "Pre-requisites for configuring APNS driver".

4.3.1.8.1 Pre-requisites for configuring APNS driver

In order to send push notification using the APNS driver, the driver needs access to the iOS application-specific certificates. The certificates (public and private keys) are obtained from Apple's developer portal.

Task 1: Installing a Trust certificate from the Entrust:

To establish a TLS session with APNs, an Entrust CA (2048) root certificate must be installed in the OPSS Keystore trust store in the domain. The missing certificate can be imported from the JDK instead.

WLST command to import the certificate into the keystore service:

import os
connect()
jdkCAcerts = os.path.join(os.getenv("JAVA_HOME"), "jre/lib/security/cacerts")
getOpssService(name='KeyStoreService').importKeyStore(appStripe='system', name='trust', password='changeit', aliases='entrustevca,entrustrootcag2,entrust2048ca', keypasswords='', type='JKS', permission=True, filepath=jdkCAcerts) 
 
syncKeyStores(appStripe='system', keystoreFormat='KSS'

See http://docs.oracle.com/middleware/1212/idm/JISEC/kssadm.htm#JISEC10119

Task 2: Importing the certificate in the domain:

The certificates are packaged in a PKCS #12 file (file extension p12 or pfx). Before the certificates can be imported into the Keystore service, (http://docs.oracle.com/middleware/1212/idm/JISEC/kssadm.htm#JISEC9596) the the archive has to be converted to a JavaKeyStore file (file extension jks).

To convert the archive using the "keytool" command (which is part of the JDK) (https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) use the following command:

JAVA_HOME/bin/keytool -importkeystore -destkeystore <com.example.myapp.jks> -srckeystore <com.example.myapp.p12> -srcstoretype pkcs12 -destalias <com.example.myapp> -deststorepass <mySecret> -srcstorepass <mySecret> -alias <the_friendly_name_in_p12_file>

Replace the parameters with the real values for the application and certificate that is required.

To import the jks file into the Keystore service there are two options:

• Use Fusion Middleware Control - Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services

• Use WLST Infrastructure Security Custom WLST Commands - Oracle Fusion Middleware Infrastructure Security WLST Command Reference

UMS comes with a predefined keystore called 'apns' which should be used for the imported certificates.

Below is a sample using WLST on how the certificate can be imported into the Keystore service:

# use empty string for the password since the keystore is permission protected (permission=true)
connect()
getOpssService(name='KeyStoreService').importKeyStore(appStripe='ums', name='apns', password='', aliases='com.example.myapp', keypasswords='mySecret', type='JKS', permission=True, filepath='path_to/com.example.myapp.jks')

Note:

The value aliases parameter (in the above command) must match the alias property in the APNS driver configuration and, also match the keystore name.

If a different keystore than 'apns' is used, then UMS must be granted additional permission using the same appstripe value used to create the new keystore.

The UMS shared library 'oracle.sdp.client' must be granted the oracle.security.jps.service.keystore.KeyStoreAccessPermission permission using the very same appstripe.

4.3.1.8.2 Common Properties

Table 4-13 shows common driver properties that are indicative of the capabilities of this driver for use by the messaging engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. For detailed description of these properties, refer to Table 4-2. For the complete list of available values, see User Messaging Service Java API Reference.

Table 4-13 Common Properties of the APNS Driver

Name	Mandatory	Default Values
InstanceName	Yes	usermessagingdriver-apns
Capability	Yes	SEND, RECEIVE
SupportedDeliveryTypes	Yes	URI
SupportedContentTypes	Yes	text/plain, application/json
SupportedStatusTypes	Yes	DELIVER_TO_DRIVER, DELIVERY_TO_GATEWAY_FAILURE,DELIVERY_TO_GATEWAY_SUCCESS,DELIVERY_TO_DEVICE_FAILURE
Cost	No	N/A
Speed	No	N/A
SupportedCarriers	Yes	N/A
Configuration Level	Yes	Server/Cluster
Supported Protocols	No	N/A
Supported Application Names	No	Empty
Driver Type	No	False
SenderAddresses	No	N/A
DefaultSenderAddress	No	N/A

4.3.1.8.3 APNS Custom Properties

Table 4-14 lists configurable properties specific to the APNS driver.

Table 4-14 Custom Properties of the APNS Driver

Name	Description	Mandatory	Default Values
Service Mode	Determines the APNs production environment	Yes
Keystore Name	Name of the keystore in KSS which holds the private key and certificated used for communication with APNs.	Yes	apns
Alias	Alias for the private key certificate pair in the keystore.	Yes
Feedback Access Point	Name of the access point used for the inbound feedback messages. Must be of delivery type URI and protocol apns. Recommended value is 'uri:apns:<applicationName>', e.g. 'uri:apns:myapp'.	No	N/A
Feedback Poll Interval	Indicates how often the driver shall poll the feedback service in seconds. Values range from 1-172800 seconds.	No	7200

4.4 Configuring User Messaging Service Access to the LDAP User Profile

As part of the LDAP provider setup in a UMS deployment, you configure the User Name Attribute through the WebLogic Server Administration Console. If you configure that attribute with a value other than the default cn or if the user's email address is stored in an LDAP attribute which is different from mail, you must make an additional configuration change in Oracle Platform Security Services (OPSS) for UMS to successfully access the user profile to obtain the list of communication channels provisioned in LDAP, such as business email.

For more information about Oracle Platform Security Services (OPSS), see Securing Applications with Oracle Platform Security Services.

To configure access to the LDAP user profile, perform the following tasks:

1. Configure the Identity Store to use LDAP by following instructions in http://docs.oracle.com/middleware/11119/bisuite/BIEDG/toc.htm.

   Note:

   You may have other properties defined in the same section.

2. To use the value of the User Name Attribute while searching the back-end LDAP server for user profile, add the following element:

   <property name="username.attr" value="username_attribute_value"/>
   

   where username_attribute_value is the value of the User Name Attribute property in the LDAP provider configuration. For instance, if the value of the User Name Attribute is mail, add the following line:

   <property name="username.attr" value="mail"/> 
   

   The following sample code shows the above line inserted in the jps-config.xml file:

   <!-- JPS WLS LDAP Identity Store Service Instance --> 
     
   <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider"> 
    
     <property name="idstore.config.provider"
   value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvide
   r"/> 
   
     <property name="CONNECTION_POOL_CLASS" 
   value="oracle.security.idm.providers.stdldap.JNDIPool"/> 
    
     <property name="username.attr" value="mail"/> 
    
   </serviceInstance>
    
   

   If the LDAP attribute containing the user's business email addresses is something other than the mail attribute, add the following element:

   <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_EMAIL=attr_containing_email"/>
   

   where attr_containing_email is the attribute name in the LDAP provider that contains the user's email address. For instance, if the user attribute containing the email address is externalEmail, add the following line:

   <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_EMAIL=externalEmail"/>  
   

   The following sample code shows the above line inserted in the jps-config.xml file:

   <!-- JPS WLS LDAP Identity Store Service Instance --> 
     
   <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">  
    
     <property name="idstore.config.provider"
   value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvide
   r"/>  
   
     <property name="CONNECTION_POOL_CLASS"
    value="oracle.security.idm.providers.stdldap.JNDIPool"/>  
    
     <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_
   EMAIL=externalEmail"/> 
    
   </serviceInstance>
    
   

3. Restart your domain.

4.5 Using Oracle User Messaging Service for Group Messaging

In addition to supporting bi-directional mutli-channel messaging through a variety of channels, UMS supports group messaging. This feature includes sending a message to a group of users by sending it to a group URI, or sending a message to LDAP groups (or enterprise roles) and application roles.

The group messaging feature enhances the capability of UMS by providing support for the following:

• Sending messages to a group

• Sending messages to a group through a specific channel

• Sending messages to an application role

• Sending messages to an application role through a specific channel

For more information about sending messages to groups and application roles, see "Sending Group Messages" in Developing Applications with Oracle User Messaging Service.

The group messaging feature does not require any new configuration of UMS. It reuses the UMS utility to access the User Role API. Since the User Role API configuration is not possible in UMS, any such configuration is done outside UMS. The User Role API is automatically configured to use the first Oracle Weblogic Server authenticator and does not require any special configuration.

Note:

For UMS to be able to resolve an application role, specific security grants are required. The application deployer must configure these security grants using WLST commands as shown in the following example:

connect('weblogic','welcome1','t3://host.example.com:7601')
 
grantPermission(codeBaseURL="file:MW_HOME/user_projects/domains/DOMAIN_NAME/servers/SERVER_NAME/tmp/_WL_user/usermessagingserver/-",permClass="oracle.security.jps.service.policystore.PolicyStoreAccessPermission",permTarget="context=APPLICATION,name=<appStripe>",permActions="getApplicationPolicy"
)

For more information about the security commands, see Infrastructure Security WLST Command Reference.

4.6 Configuring Automatic Message Resend

In 12c, the automatic resend feature can be configured to automate the administrator's resend. This means that when a message send attempt is classified as a complete failure, then the message is automatically scheduled for resend. This is repeated until the message is successfully sent or the configured number of resends is achieved. The delay time and the maximum number of resends can be configured. Functionally, this is the same as an administrator manually resending the messages when the delay time has expired. The purpose of the automatic resend is to resolve temporary network problems or temporary unavailability of backend services.

The UMS server configuration parameters, ResendDefault, ResendDelay, and ResendMax have been introduced for configuring this feature. For more information about these parameters, see Table 4-1.

The number of resend attempts is configured for the server, but may be overridden programmatically per message by the client. The client can specify the number of resends to be used per message to override the ResendDefault server configuration parameter. Note that although overridden, it is limited by the ResendMax configuration parameter.

For more information about setting the number of resend attempts programmatically, see sections "Using UMS Java API to Specify Message Resends" and "Using UMS Web Service API to Specify Message Resends" in Developing Applications with Oracle User Messaging Service.

Note:

If message resend fails even after automatically trying to resend the message the maximum number of times, then the administrator can send it manually from the Enterprise Manager. The resend counter will be reset. If the maximum number of resends is configured to 0, then the behaviour will be identical to that in 11g, that is an administrator will have to manually select the failed message and resend it using the Enterprise Manager.

4.7 Securing the Oracle User Messaging Service

The User Communications Preferences User Interface can be secured at the transport-level using Secure Sockets Layer (SSL). By default, all deployed web services are unsecured. Web Service Security should be enabled for any services that are deployed in a production environment.

• To enable SSL in the Oracle WebLogic Server, see "Configure SSL for Oracle WebLogic Server" in the Administering Oracle Fusion Middleware. This step is sufficient to secure the User Communication Preferences User Interface.

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

The recommended security configuration for web services uses Security Assertion Markup Language (SAML) tokens to pass identities between web service clients and UMS. With SAML tokens, instead of the web service client passing a username and password to UMS, a trust relationship is established between the client and UMS because 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 UMS 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)

• oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy (client-side)

  Note:

  The choice of client-side policy depends on the security context in which your application is executing.

  • If the thread that is making the web service call has the intended Subject associated with it (for example, from a web application that performs user authentication, or a Java EE module with a run-as identity defined), then use the policy oracle/wss11_saml_token_with_message_protection_client_policy.

    The current thread Subject is passed through using the SAML Policy WS-Security headers. In this case you should not specify the parameter javax.xml.ws.BindingProvider.USERNAME_PROPERTY when creating your web service client instance.

  • If the thread that is making the web service call has an undefined Subject associated with it, or if you must programmatically supply a different identity, then use the policy oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy, and specify the parameter javax.xml.ws.BindingProvider.USERNAME_PROPERTY when creating your web service client instance. If you want to perform dynamic identity switching, you must grant additional code permissions to your application. For more information, see Administering Web Services.

4.7.1 Web Service Security on Notification

The different web services include corresponding notification web services (MessageNotification) that run on the client side and receive notifications (message delivery status, message receipt, presence status change) when the appropriate event occurs.

4.7.2 Enabling UMS Web Service Security

To enable a policy for a UMS web service, follow the steps in "Attaching OWSM Security Policies Using the Administration Console" in 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.

4.7.3 Enabling Client Security

Web service client security must be enabled programmatically. When using the client libraries described in Developing Applications with Oracle User Messaging Service, 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 4-15) should be added to the configuration map in addition to other required properties such as the endpoint address.

Table 4-15 Client Security Keys

Key	Typical Value
oracle.ucs.messaging.ws.ClientConstants.POLICIES	oracle/wss11_saml_token_ with_message_protection_ client_policy
javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY	Endpoint URL for the remote UMS WS. This is typically "http://<host>:<port>/ucs/messaging/webservice".
javax.xml.ws.BindingProvider.USERNAME_PROPERTY	(Optional) <valid username> Note: Do not specify this key while using oracle/wss11_saml_token_with_message_protection_client_policy.
oracle.wsm.security.util.SecurityConstants.Conf ig.KEYSTORE_RECIPIENT_ALIAS_PROPERTY	(optional) keystore alias for target service. See Client Aliases.
oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY	Used for OWSM policy attachment. Specifies a credential store key to use for looking up remote username/password information from the Oracle Web Services Management credential store map.

Example 4-1 Web Service Client Security

HashMap<String, Object> config = new HashMap<String, Object>();
config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
 "http://example.com:8001/ucs/messaging/webservice");
config.put(oracle.ucs.messaging.ws.ClientConstants.POLICIES, new String[]
 {"oracle/wss11_saml_token_with_message_protection_client_policy"});
 
mClient = new MessagingClient(config);

4.7.4 Keystore Configuration

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" in Securing Web Services and Managing Policies with Oracle Web Services Manager 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.

4.7.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 4-2.

  Example 4-2 Client Aliases

  HashMap<String, Object> config = new HashMap<String, Object>();
  config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
   "http://example.com:8001/ucs/messaging/webservice");
  config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_saml_token_
  identity_switch_with_message_protection_client_policy"});
  config.put(BindingProvider.USERNAME_PROPERTY, "user1");
  config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_
  LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_
  SUBJECT);
  config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_
  ALIAS_PROPERTY, "ums_public_key");
  config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp");
  mClient = new MessagingClient(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 "Overriding the Policy Configuration for the Web Service Client" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for more details.

4.7.6 Securing JMS Resources

This (optional) procedure enables administrators to restrict access to the UMS' 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 Oracle WebLogic Server Administration Console, or you may run a WLST script (available at MIDDLEWARE_HOME/oracle_common/communications/bin/secure_jms_system_resource.py) as follows:

MIDDLEWARE_HOME/oracle_common/common/bin/wlst.sh
./secure_jms_system_resource.py
-userConfigFile=<UserConfigFile>, -userKeyFile=<UserKeyFile> 
-url=<AdminServer_t3_url> -jmsSystemResource=<JMSSystemResourceName> -role=<SecurityRoleToUse>

The UserConfigFile shall contain encrypted username and password for the AdminUser. The key for the encrypted data shall be in UserKeyFile.

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.