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.4, "Configuring User Messaging Service Access to the LDAP User Profile"
Section 4.5, "Using Oracle User Messaging Service for Group Messaging"
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.
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 |
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:
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.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:
Log in to Oracle Enterprise Manager Fusion Middleware Control as an administrator.
Navigate to the User Messaging Service home page.
Click usermessagingserver(AdminServer). The Associated Drivers page appears as shown in the following figure.
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.
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:
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".
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.
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."
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.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:alice@example.com. |
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 |
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 |
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 |
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:
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.
Click Create to create a new configuration or select a configuration and click Edit to edit an existing configuration.
The Driver properties page appears.
In the Driver-Specific Configuration table, locate the properties with the Encoded Credential flag set.
Select the credential type from the Type of Password drop-down list in the adjoining Value column as shown in the following figure.
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.
Click OK to save changes.
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>)
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.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 |
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 |
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:
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.
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.
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.
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 |
|
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 |
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 |
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 ( |
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.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.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 |
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 |
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 |
No |
Enabled |
DatagramMessageMode |
Supports datagram message mode. The default is Disabled. |
No |
Disabled |
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.
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 |
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 |
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.
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 |
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. |
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".
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.
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 |
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 |
No |
N/A |
Feedback Poll Interval |
Indicates how often the driver shall poll the feedback service in seconds. Values range from |
No |
7200 |
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:
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.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>
Restart your domain.
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.
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.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.
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.
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.
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) Note: Do not specify this key while using |
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);
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.
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.
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.
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.