Configuring Info*Engine Capabilities
The following topics discuss configuring and implementing various Info*Engine functionalities, including those that support messaging, tasks, and user authentication.
Mapping Credentials in Info*Engine Tasks and JSPs
Info*Engine provides the capability of mapping the identity of a user to a specific username and password that is then passed to a back-end system through an adapter or to a Message-Oriented Middleware (MOM) through messaging software or the Info*Engine Web Event Service. This mechanism becomes active when an adapter webject or a webject that accesses the MOM is executed but no username and password information is explicitly provided in the webject.
With a credentials mapping mechanism in place, Info*Engine can dynamically add authentication parameters to these webjects through a site-defined credentials mapping task or a set of credentials files.
The following rules apply to credentials mapping:
• If the author of a task or JSP explicitly specifies DBUSER and PASSWD parameters on a webject, those parameters take precedence over any other authentication information that might be available.
• If DBUSER and PASSWD parameters are not explicitly specified, Info*Engine attempts to provide values for them from the credentials mapping information.
• If no credentials mapping information is available, or if the credentials mapping does not provide valid DBUSER and PASSWD values for the adapter to which a webject is being routed or for the MOM, Info*Engine does not send any DBUSER or PASSWD values. In this case, the adapter obtains default values from its configuration properties. The Info*Engine messaging software or Web Event Service obtains default values from its configuration properties. If no default values are set, Info*Engine attempts anonymous access.
Credentials mapping for adapters uses the following process:
• Windchill is pre-configured to include a credentials mapping task. This task is configured through the Windchill adapter using the wt.federation.task.mapCredentials property value, which is set to /wt/federation/MapCredentials.xml. The contents of this task are dynamically generated, starting with the following file:
<Windchill>/tasks/wt/federation/MapCredentials.xml.template
and uses the property values found in site.xconf. This credentials mapping task has the ability to provide credentials to adapters based on whether the current user is an administrator or a regular user. If you would like to modify mapped credentials, you can set properties in site.xconf. For more information, read the contents of MapCredentials.xml.template. Windchill’s LDAP access for user and group information relies on this credentials mapping task.
 |
If you need to customize this task you should do so by modifying the MapCredentials.xml.template file. You should also keep a backup copy, because a patch or maintenance release installation may overwrite your customization.
|
• When Info*Engine is called to parse and execute a JSP page or a task that accesses an adapter, it checks to see if a credentials mapping task has been defined. If it discovers that one has been defined, it executes the specified task before executing the JSP page or task originally passed to it. The output group produced by the credentials mapping task is saved as a context group named Auth-Map.
• When Info*Engine encounters a webject that must be routed to an adapter, it checks the webject to see if DBUSER and PASSWD parameters have been specified explicitly. If they have not been specified, it uses the value of the webject INSTANCE parameter as a key to find DBUSER and PASSWD values in the Auth-Map context group. If values are found, it adds them to the webject as if they had been specified explicitly by the author of the task. Otherwise, the webject is routed to the adapter unmodified.
For more information, see Credentials Mapping. For descriptions of the credentials mapping properties, see the Info*Engine properties help that is accessible through the Info*Engine Property Administration utility.
Enabling Task Invocations through URIs
By default, Info*Engine no longer allows tasks to be invoked through URIs. This functionality has been disabled by default because it poses a security threat.
To allow URIs to invoke Info*Engine tasks, set the following property to TRUE in the appropriate form:
<service_name>.taskProcessor.remoteEnabled
Determine which service processes the URI and set the property in that service. You can set this property in either the server or servlet form. When using a Windchill solution, you can set this in the server or Windchill adapter form.
|
|
PTC strongly recommends that you do not enable this functionality.
|
For information on setting additional properties, see Adding Properties to an Existing Form.
Configuring Send-Mail Properties
The Send-Mail webject creates and sends an email message. You can optionally configure some defaults for the Send-Mail webject using the following properties:
|
Property
|
LDAP Entry Field
|
Default
|
|---|---|---|
|
.mail.originator
|
Default Mail Originator
|
There is no default; the webject must include the FROM parameter.
|
|
.mail.smtp.server
|
Default SMTP Server
|
Default is “localhost.”
|
|
.mail.smtp.username
|
Default SMTP User Name
|
Default is to attempt an anonymous binding to the mail server.
|
|
.mail.smtp.password
|
Default SMTP Password
|
There is no default password.
|
To add these property settings, edit the LDAP entries for the Info*Engine server that you want to use to send emails. Use the Info*Engine Property Administration utility to edit LDAP entries.
For information about the Send-Mail webject, see Message Webjects.
Implementing Messaging and the Web Event Service
Implementing the Info*Engine Web Event Service (WES) and/or point-to-point messaging provides the following capabilities:
• Users or applications that interact with Info*Engine can send and retrieve messages to and from a JMS message queue. If the Web Event Service is being used, users or applications can also emit events.
Message and event emission can be from anywhere in the MOM network. Therefore, using WES can connect a separate Info*Engine environment with other JMS-compatible environments, and messaging can send information between those environments.
• By default, events emitted through Info*Engine do not expire. However, WES event authors can specify a time after which the event expires.
• When a WES is used, Info*Engine subscribers to a JMS topic can execute defined tasks when a specified event has occurred.
When interacting with a MOM, Info*Engine needs to translate local Info*Engine data into JMS messages, and then from JMS messages back into Info*Engine data.
In order to perform this two-way translation Info*Engine uses different message processors which are referred to here as “types.” In most cases the type listed corresponds directly to an actual JMS message type, but for types like InfoEngine and Unknown, these simply refer to the name of a message processor that maps onto a JMS message object that can suit the data being transferred. Info*Engine can send and receive JMS messages that are of the following types:
InfoEngine
Used for Info*Engine-to-Info*Engine communication.
If the message type is InfoEngine, then a message sent from Info*Engine can include Info*Engine groups. This provides a way to pass Info*Engine groups between separate Info*Engine environments.
BytesMessage
Used for building and receiving a message that may be specific to a third-party recipient that supports this type of message.
TextMessage
Used to create outgoing and receive incoming string messages.
MapMessage
Used to create messages from values that are in the form of name=data. The name portion of the value is the key used to place data in this type of message.
StreamMessage
Used to create or receive messages specific to a third-party recipient that also supports this type of message.
Unknown
Used to turn BLOB data into a format that can be processed by a third-party recipient that supports BytesMessage.
Info*Engine uses this type for incoming messages that do not have a message type defined. It creates an empty IeRequest and appends the contents of the message as BLOB data.
In addition, if you supply a user-defined message processor, Info*Engine can send and receive JMS messages of the user-defined type.
|
|
The size of the messages that you can send and receive may be dependent on the MOM you are using. For example, persistent messages in WebSphere MQ must be less than 4 MB, by default.
|
The following Info*Engine webjects provide point-to-point messaging capabilities:
Create-Object
Delete-Object
Query-Object
Browse-Queue
Subscribe-Queue
Unsubscribe-Queue
The following Info*Engine webjects support WES capabilities:
Emit-Event
Subscribe-Event
Unsubscribe-Event
For webject examples, see Message Webjects and Web Event Service Webjects.
To implement WES or point-to-point messaging in your Info*Engine environment, complete the following tasks:
• Install a Message-Oriented Middleware (MOM) software product such as WebSphere MQ.
• For point-to-point messaging, configure the JMS queues in the MOM that you want to use, and configure a queue connection factory that is used in conjunction with the queues. The connection factory used for point-to-point messaging is the same connection factory used for task queuing.
For the WES, configure the required JMS topics and a topic connection factory in the MOM. Each topic represents an event.
• Use a MOM-supplied utility or administrative UI to create the necessary administered objects (connection factories, queues, topics) in the JNDI repository. Depending on your MOM, these objects may or may not be independent from those discussed previously.
• Using the Info*Engine Property Administration utility, create a new JMS service property set for your MOM. The name of the property set you create can be passed as input to the SERVICE parameter for any JMS-related webjects. If you do not wish to use the SERVICE parameter on the JMS webjects, then edit the applicable Info*Engine servers or servlets that are used for JMS operations and specify the name of your property set in the Default JMS Service property (.jms.defaultService).
When creating your new JMS service property set, the most commonly set properties can be found under the Core JMS Properties section of the property set form. Other properties can be found in the Additional JMS Properties section.
|
|
The properties that must be set depends upon the MOM to which you are connecting. At a very minimum the .jms.baseUri property and the connection factory properties must be set.
|
The following properties are useful when implementing point-to-point messaging and the WES:
JMS Context Provider Factory
The .jms.CtxFactory property can be used to specify a JNDI context provider factory if your MOM’s administered objects are not stored in the LDAP. This is typically a Java class name provided with the JARs used to connect Info*Engine to your MOM.
JMS Base URI
The .jms.baseUri property specifies the JNDI URL used to discover administered objects.
JMS Base URI Principal
JMS Base URI Password
The .jms.baseUri.principal and .jms.baseUri.password properties specify any necessary JNDI credentials associated with access to the URI specified by the .jms.baseUri property. Whether or not these properties need to be set is based upon the security requirements of your MOM’s JNDI repository.
JMS User
JMS Password
The .jms.username and .jms.password properties can be used to specify default credentials to use when connecting to your MOM. If your MOM requires credentials for connections then you must either specify these properties or use the DBUSER and PASSWD parameters when using JMS webjects.
JMS Queue Connection Factory
Topic Connection Factory
For point-to-point messaging, the .msg.queueConnectionFactory property specifies the JNDI name of the QueueConnectionFactory object used to connect to your MOM.
For WES, the .wes.topicConnectionFactory property specifies the JNDI name of the TopicConnectionFactory object used to connect to your MOM.
JMS Library Directory
The .jms.lib property specifies a directory where the JARs required to connect to your MOM are stored. If you do not specify this property, then the JARs are found within the JVM CLASSPATH (such as JARs stored in <Windchill>/codebase/WEB-INF/lib).
If you are configuring more than one third-party MOM into your system, then you should use the .jms.lib property for each MOM to isolate third-party classes from each other.
WES Subscription Identifier
For WES, the .wes.subscriptionIdentifier property specifies a hard-coded subscription identifier your system should use. Subscribing to an event automatically generates a subscription identifier. These identifiers must be unique. By default, the identifier generated is based on the host name and event name.
Web Event Service Implementation Notes
If you have multiple Info*Engine environments running on the same host and you want to generate multiple subscriptions to the same MOM for the same event, then the automatically-generated subscription identifiers are the same. To make them unique, you must set a unique subscription identifier in all, or all but one, of the environments.
You must create one or more Info*Engine tasks that subscribe to the JMS topics that are used for emitting events. A startup task can be used to generate subscriptions when your system starts. The wt.federation.task.startup property controls the single startup task, or add the task in the Startup Task 1 field on the LDAP entry form for the Info*Engine server or servlet that you want to execute tasks when events occur. By executing the tasks at server startup, the server is always subscribed to the topics.
|
|
The startup task is specified using the wt.federation.task.startup property in wt.properties.
|
For examples of emitting events and setting up tasks to execute when an event occurs, see Info*Engine Tasks.
Implementing Task Queuing
By implementing task queuing in your Info*Engine environment, you can provide the following capabilities:
• Users can submit a long-running task to a message queue for execution by a subscriber to the queue. The subscriber can guarantee the execution of the task and submit the result to a response queue. At a later time, the user can check for the completion of the task and retrieve the resulting data.
• Users can submit a task to a message queue for execution and wait for a response. The response is returned to the user as soon as a response is received. If the user disconnects before the response is received, the task results are queued for later retrieval.
• Users can submit a task to any queue in the message queue network, thus providing interconnection between Info*Engine servers.
• Users can submit a current Info*Engine group to a message queue. This makes the group available to multiple instances of Info*Engine users.
The following Info*Engine webjects provide the capabilities to queue and manage tasks:
Browse-Queue
Delete-Results
Query-Results
Queue-Task
Subscribe-Queue
Unsubscribe-Queue
For webject examples, see the section Info*Engine User’s Guide.
To implement task queuing in your Info*Engine environment, complete the following tasks:
• Install a Message-Oriented Middleware (MOM) software product, such as WebSphere MQ.
• In the MOM, configure the required execution and results queues and also configure a queue connection factory that is used in conjunction with the queues. The connection factory used for task queuing is the same connection factory used for point-to-point messaging.
• Use a MOM supplied utility or administrative UI to create the necessary administered objects (connection factories, queues, topics) in the MOM’s JNDI repository. Depending on your MOM these objects may or may not be independent from those discussed in step above.
• Using the Info*Engine Property Administration utility, create a new “JMS Service” property set for your MOM. For information on how to configure your JMS Service property set to use JMS queues, see the properties configuration step in the section "Implementing Messaging and the Web Event Service".
• Configure the JMS properties in your system in the same manner as described in the section "Implementing Messaging and the Web Event Service".
• Optionally, set the following JMS service property set values, found in the Additional JMS Properties section:
|
Property
|
LDAP Entry Field
|
|---|---|
|
.msg.defaultTaskQueue
|
Default Submit Queue
|
|
.msg.defaultExecutionQueue
|
Default Subscribe Queue
|
|
.msg.defaultResultsQueue
|
Default Results Queue
|
If you do not set defaults for the submit, subscribe, and results queues, the queues must be named in the webjects used for queuing tasks.
You must also create one or more Info*Engine tasks that subscribe to the JMS topics that are used for emitting events. A startup task can be used to generate subscriptions when your system comes up. The wt.federation.task.startup property controls the startup task, or add the task in the Startup Task 1 field on the LDAP entry form for the Info*Engine server or servlet that you want to execute tasks when events occur. By executing the tasks at server startup, the server is always subscribed to the topics.
|
|
In Windchill, the startup task is specified using the wt.federation.task.startup property in wt.properties.
|
For examples of queuing tasks, executing queued tasks, and retrieving the results of queued tasks, see Info*Engine Tasks.
Configuring Request Validation
Info*Engine provides a mechanism for signing and validating requests to process information on remote Info*Engine task processors and out-of-process adapters.
By setting the server or adapter .secret.text or .secret.text2 properties, you provide an arbitrary text string that is used to sign outgoing requests and validate incoming requests. Each request is signed using java.security.MessageDigest and a MessageDigest algorithm. By combining the secret text and the request information, Info*Engine generates a unique fingerprint. This fingerprint is converted into a string of hex characters and inserted into the request as metadata to be read back and verified by the receiving Info*Engine server or out-of-process adapter.
|
|
The .secret.text2 property generates a more comprehensive request signature than the .secret.text property. Use .secret.text2 instead of or in addition to .secret.text for validating with task processors and adapters.
|
The following sections describe how to set these properties for a remote task processor or a remote Windchill adapter.
|
|
If you set the .secret.text and .secret.text2 values in LDAP (instead of using the properties listed), ensure that your LDAP is secure.
|
Task Processor Validation for Remote Task Processors
To use request validation of remote Info*Engine task processors, complete the following steps:
• Use the xconfmanager to specify the following properties on the remote Info*Engine task processor system in the codebase/WEB-INF/ieStructProperties.txt file:
xconfmanager -p -s "<servuce_name>.secret.text=<value>"
-t "codebase/WEB-INF/ieStructProperties.txt"
-t "codebase/WEB-INF/ieStructProperties.txt"
xconfmanager -p -s "<service_name>.secret.text2=<value>"
-t "codebase/WEB-INF/ieStructProperties.txt"
-t "codebase/WEB-INF/ieStructProperties.txt"
where <service_name> is the service name used for the remote task processor (as defined in the Info*Engine Property Administration utility) and <value> is the arbitrary text you are using.
• When a request is made to execute on a remote task processor, the .secret.text and .secret.text2 properties set on the local and the remote task processors must be the same, or the request is rejected.
For details about using the Info*Engine Property Administration utility, see Using the Property Administration Utility. For descriptions of the .secret properties, see the help that is accessible through the Info*Engine Property Administration utility.
Adapter Validation for Out-of-Process Adapters
To use request validation on out-of-process adapters, complete the following steps:
• Use the xconfmanager to specify the following properties on the remote Info*Engine task processor system in codebase/WEB-INF/ieStructProperties.txt file:
xconfmanager -p -s "<adapter_name>.secret.text=<value>"
-t "codebase/WEB-INF/ieStructProperties.txt"
-t "codebase/WEB-INF/ieStructProperties.txt"
xconfmanager -p -s "<adapter_name>.secret.text2=<value>"
-t "codebase/WEB-INF/ieStructProperties.txt"
-t "codebase/WEB-INF/ieStructProperties.txt"
where <adapter_name> is the Windchill adapter instance name used for the remote adapter (as defined in the Info*Engine Property Administration utility) and <value> is the arbitrary text you are using.
• When a request is made to execute an adapter webject, the adapter name specified in the INSTANCE parameter must identify service that has the .secret properties set. If that service does not have the .secret.text and .secret.text2 properties set, it does not give the request access to the adapter.
For details about using the Info*Engine Property Administration utility, see Using the Property Administration Utility. For descriptions of the .secret properties, see the help that is accessible through the Info*Engine Property Administration utility.
Implementing Secure Socket Factories
Secure socket factories allow Info*Engine components to establish secure connections between each other by using the functionality supplied by the Java Secure Sockets Extension (JSSE) of the Java 2 platform. JSSE provides a rich set of APIs that implement various security protocols and encryption algorithms including SSL (Secure Sockets Layer) and TLS (Transport Layer Security).
|
|
Because JSSE is subject to U.S. export restrictions, to use secure socket factories with Windchill you must download or otherwise obtain JSSE from JavaSoft and install it yourself.
|
Additionally, to use secure sockets, the web server you use with Windchill must support the use of secure sockets.
Creating and Configuring Secure Socket Factories
Info*Engine provides the following Java interface classes that can be used in creating socket factories:
com.infoengine.au.SocketFactory
Defines the contract that must be implemented by a factory that creates client-side sockets.
com.infoengine.au.ssl.SimpleServerSocketFactory
Defines the contract that must be implemented by a factory that creates server-side sockets.
To create a custom socket factory, define a Java class that formally declares that it implements the appropriate interface, and determine how to configure the factory for use with Info*Engine services. To view the API documentation for the interface classes, see the Javadoc files.
Simple Secure Socket Factories
As an example implementation, Info*Engine provides the following simple secure socket factories:
com.infoengine.au.ssl.SimpleSocketFactory
com.infoengine.au.ssl.SimpleServerSocketFactory
This implementation assumes that you have identified or created the following items and set the corresponding properties in the task processor, servlet, and out-of-process adapter services:
.ssl.simpleSocket.host.port.protocol
Sets the name of the protocol.
The secure socket protocol to be used. This is usually TLS or SSL. By default, the behavior of the socket is determined entirely through connection handshaking.
.ssl.simpleSocket.host.port.keyFile
Sets the fully-qualified name of the file used to supply the keys for sockets using the specified host and port.
A file containing the keys used by the TLS or SSL protocol. You can use the tools provided with your web server secure socket access to create the key file.
.ssl.simpleSocket.host.port.algorithm
Sets the name of the algorithm.
The security algorithm used by the key manager. By default, this is SunX509.
.ssl.simpleSocket.host.port.keyStoreType
Sets the type of the keystore.
The type of the keystore. By default, this is JKS.
.ssl.simpleSocket.host.port.password
Sets the keystore password (if required).
The password used in verifying and loading the keystore. By default, the keystore is not verified by a password.
|
|
If you specify only host instead of specifying host.port (as shown above), the property applies to all ports on the specified host. If a property is defined using host.port, this property overrides a property that specifies just host.
|
Registering Secure Socket Factories
To use secure socket factories, you must register both the client and server socket factories for each Info*Engine service that uses a socket connection as follows:
• Register a client socket factory, naming the host and port of the specific service.
• Register a server socket factory, naming the port used to listen for connections from remote clients.
You can set the following Info*Engine properties in each task processor, servlet, and out-of-process adapter service to register the factories:
.socketFactory.host.port
Specifies the fully-qualified name of the class that implements the client socket factory and identifies the host and port of a specific service to which the factory will create client sockets. If you omit the port, the property identifies a client socket factory that applies to all services on a specified host.
.serverSocketFactory.port
Specifies the fully-qualified name of the class that implements the server socket factory that creates server sockets for the specified port.
Setting Secure Socket Factory Properties
Info*Engine Property Administration does not include any secure socket factory properties on its forms. However, you can add secure socket factory properties to any form by using the following Additional Properties fields that appear on every form:
Documentation for the secure socket factory properties can be accessed through the help available through the Info*Engine Property Administration utility.