Configuring Security and General Properties

This section discusses how to:

  • Set gateway digital certificate security properties.

  • Specify the gateway version.

  • Specify the gateway class location.

  • Set general connection properties.

  • Set logging properties.

  • Set DTD validation properties.

  • Set Oracle Jolt session pooling parameters.

  • Set the namespace for generic SOAP faults.

  • Display the PeopleTools version of an integration gateway.

You can implement gateway-based digital encryption on the integration gateway. When implemented you must set the integration gateway digital certificate alias, certificate alias password, keystore path, and keystore password in the integration gateway properties file.

At a minimum you must specify the path and password to the integration gateway keystore in the integration gateway properties file. Although highly recommended, you do not need to install digital certificates to meet this requirement. You need only specify the path and password to the keystore.

Use the PSKeyManager utility delivered with PeopleTools to generate the keystore password. See “Understanding PSKeyManager Utility” in Installing Web Server-Based Digital Certificates for information on using the PSKeyManager utility.

Most production environments have SSL/TLS implemented. If the integration gateway is installed on a web server that has SSL/TLS implemented, you can specify the SSL/TLS keystore path and password to meet this requirement.

Important! SSL/TLS encryption applies digital certificates from two keystores to encrypt inbound and outbound messages, respectively. The integration gateway manages the certificates in the keystore that supports outbound messaging. So if you specify the SSL/TLS keystore path and password, be sure to use the proper values.

Use the section labeled Integration Gateway CERTIFICATE Section in the integration gateway properties file to defined the keystore path and encrpyted keystore password.

Warning! Integrations will fail if you do not set the path to the keystore using the secureFileKeystorePath property and enter an encrypted keystore password for the secureFileKeystorePasswd property.

You must set the following properties in integrationGateway.properties so that the gateway can access the encryption certificates.

Property

Description

ig.certificateAlias

(Optional.) If implementing gateway-based digital certificates, enter the name that you provided to identify the encryption key pair that you generated for the keystore on which the gateway's public key certificate is based.

ig.certificatePasswd

(Optional.) If implementing gateway-based digital certificates, enter the password that you provided for the encryption key pair that you generated for the keystore. The certificate password must be encrypted.

See Encrypting Passwords.

secureFileKeystorePath

Enter the full path and file name of the gateway keystore file, which is located in the web server directory structure. The path is <PIA_HOME>\webserv\<DOMAIN>\piaconfig\keystore.

secureFileKeystorePasswd

Enter the keystore password. .

This password must be encrypted.

See Encrypting Passwords.

The gateway version property, ig.version, indicates the version of PeopleTools from which the integration gateway is installed.

The integration gateway version must be the same or higher version than the version of the application server with which you want to communicate. For example, you can use a PeopleTools 8.55 integration gateway to communicate with a PeopleTools 8.55 application server or to communicate with a PeopleTools 8.47 application server.

Integration gateways cannot communicate with application servers on higher versions. For example a PeopleTools 8.47 integration gateway cannot directly communicate with a PeopleTools 8.55 application server. If this kind of communication is required, then the communication should be setup where the 8.47 gateway is set up as a remote gateway.

The version property is located in the integrationGateway.properties file in the section labeled Integration Gateway VERSION Section. Specify the version as follows:

ig.version=version_number

where version_number is the version of PeopleTools with two decimal places; for example, 8.55.

This section discusses:

  • Default connector properties.

  • Node-specific Oracle Jolt connect string properties.

  • Default Oracle Jolt connect string properties.

The general connection properties include default connector properties and Oracle Jolt connect strings for nodes that designate this gateway as their local gateway. You can find these properties in the section of the integrationGateway.properties file labeled DELIVERED CONNECTOR CONFIGURATION Section.

Default Connector Properties

Property

Description

ig.connector.prefix

Identifies the universal resource indicator (URI) prefix added to any target connector name. This property instantiates the connector classes on the system. The default connector prefix is:

com.peoplesoft.pt.integrationgateway.
targetconnector.

Note: Do not change this value.

ig.connector.defaultremoteconnector

Identifies the connector that the gateway uses to send messages to a remote gateway. The default value of this property is:

HttpTargetConnector

Note: Do not change this value.

ig.connector.ibtargetconnector

Identifies the connector that the gateway uses by default to send messages to a PeopleSoft Integration Broker application server node. The gateway uses this connector to link to the integration engine running on the node's application server. When the content of a message reaching the gateway doesn't specify a connector (this is often the case with third-party senders), the gateway automatically uses the connector specified by this property. The default value is:

PeopleSoftTargetConnector

Note: Do not change this value.

Default Oracle Jolt Connect String Properties

Within any inbound message, the integration gateway requires only the names of the message and the requesting node. If the message was sent by a PeopleSoft Integration Broker system, it also includes the name of the target node. The gateway searches the integrationGateway.properties file for the Jolt connect string properties for the specified target node, so it can properly direct the message.

However, the integration gateway cannot determine the target node in the following cases:

  • The Jolt connect string settings for the specified target node are missing from the integrationGateway.properties file.

  • The message format does not include a To node specification.

    This can include general HTTP calls to listening connectors other than the PeopleSoft listening connector.

  • When using Send Master for testing purposes.

To handle these cases, you can specify a default target node for the gateway if no valid target node can be determined.

Note: You can set these properties in the integration gateway properties file or use the PeopleSoft Node Configuration page in PIA.

Use the default Jolt connect string properties:

#ig.isc.serverURL=//<machine name>:<jolt port>
#ig.isc.userid=<database user id>
#ig.isc.password=<database password>
#ig.isc.toolsRel=<peopletools release version>

Uncomment these four lines and enter values to designate a PeopleSoft Integration Broker node as the gateway's default (backup) target node. It typically is one of the nodes for which you already created node-specific Jolt connect string properties.

There's only one set of these default properties. They specify the same parameters as the node-specific properties, except that you don't include a node name; for example: 

ig.isc.serverURL=//MYSERVER01:9000
ig.isc.userid=TOPDOG
ig.isc.password=VOBN5KcQZMg
ig.isc.toolsRel=8.55

You can also specify a comma-separated list of server URLs. Each URL in the string will use the user ID, password, and PeopleTools release defined:

ig.isc.serverURL=//MYSERVER01:9000,//MYSERVER02:9250,//MYSERVER03:9500,//MYSERVER04:9750 
ig.isc.userid=TOPDOG
ig.isc.password=VOBN5KcQZMg
ig.isc.toolsRel=8.55

Oracle Jolt Connect String Properties for Known Nodes

You must set four Oracle Jolt connect string properties for each PeopleSoft Integration Broker application server node with which the integration gateway communicates. The gateway uses this information to access each node's database through a Oracle Jolt connection with its PeopleSoft target connector.

Note: You can set these properties in the integration gateway properties file or use the PeopleSoft Node Configuration page in PIA.

Note: These properties apply only to communications that don't cross a firewall and for which the gateway uses the PeopleSoft target connector.

The integrationGateway.properties file contains a template for these properties:

ig.isc.$NODENAME.serverURL=//<machine name>:<jolt port>
ig.isc.$NODENAME.userid=<application server user id>
ig.isc.$NODENAME.password=<application server password>
ig.isc.$NODENAME.toolsRel=<peopletools release version>

For each node, make a copy of this template and replace $NODENAME with the name of the node definition. Enter appropriate values for each property as described in the following table:

Property

Description

ig.isc.$NODENAME.serverURL

Enter the URL of the application server node, consisting of the machine name and Oracle Jolt port; for example:

ig.isc.MYNODE.serverURL=//MYMACHINE:9000

Note: You can determine the Jolt port of the application server by examining the JOLT Listener section in the psappsrv.cfg file located in <PS_CFG_HOME>\appserv\<DOMAIN_NAME>.

ig.isc.$NODENAME.userid

Enter the UserID that you defined when you created the application server domain; for example:

ig.isc.MYNODE.userid=TOPDOG

ig.isc.$NODENAME.password

Enter UserPswd that you defined when you created the application server domain. This password must be encrypted; for example:

ig.isc.MYNODE.password=VOBN5KcQZMg

See Encrypting Passwords.

ig.isc.$NODENAME.toolsRel

Enter the version number of PeopleTools installed on the application server node to two decimal places; for example:

ig.isc.MYNODE.toolsrel=8.55

You can also specify a comma-separated list of server URLs. Each URL in the string will use the user ID, password, and PeopleTools release defined:

ig.isc.QEDMO.serverURL=//MYSERVER20:9000,//MYSERVER21:9100,//MYSERVER23:9200,//MYSERVER24:9300
ig.isc.QEDMO.userid=BIGCHEESE
ig.isc.QEDMO.password={V1.1}SA9rOgMyTyEbXRM88agEgg==
ig.isc.QEDMO.toolsRel=8.55

This section discusses:

  • General logging properties.

  • Message logging properties.

  • Error logging properties.

  • Overriding the IP address used for gateway logging.

The logging properties specify parameters for logging messaging activity and errors. You can find these properties in the section of the integrationGateway.properties file labeled LOGGING Section.

General Logging Properties

Property

Description

ig.log.level

Enter a numeric value to specify the desired level of gateway logging and exception handling.

Values are:

  • −100: Suppresses message logging. The property is preset to this value.

  • −1: Logs language exceptions only.

  • 1: Logs language and standard exceptions.

  • 2: Logs all errors and warnings.

  • 3: Logs errors, warnings, and important information. This is the default if you don't specify a value for this property.

  • 4: Log errors, warnings, and important and standard information.

  • 5: Logs errors, warnings, and important, standard, and low-importance information.

Note: Set the log level to 5 to capture the entire contents of incoming HTTP requests, including HTTP headers, in the integration gateway message log file.

ig.log.backgroundImage

Specify the background image to use when displaying error and message log documents. The image must be in jpg format. The default location and image name PSbackground.jpg.

By default it is located in <PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war.

Images in the default location don't require a path, but you can specify a full path to an image file in any other location.

Message Logging Properties

Property

Description

ig.messageLog.filename

Enter the full path and file name of an HTML file to use as a message log. This property is preset to <PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB_INF\msgLog.html.

ig.messageLog.maxSize

Specify the maximum size of the message log, in kilobytes (KB). This property is preset to 10000, or 10 megabytes (MB). When this limit is reached, the log is archived, and a timestamp is appended to the file name.

ig.messageLog.maxNbBackupFiles

Specify the number of archived files to keep on disk. Use the value 0 to retain all backed up files. This property is preset to 5.

Error Logging Properties

Property

Description

ig.errorLog.filename

Enter the full path and file name of an HTML file to use as an error log. This property is preset to <PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\errorLog.html.

ig.errorLog.maxSize

Specify the maximum size of the error log in kilobytes (KB). This property is preset to 1000, or 1 MB. When this limit is reached, the log is archived, and a timestamp is appended to the file name.

ig.errorLog.maxNbBackupFiles

Specify the number of archived error files to keep on disk. Use the value 0 to retain all backed up files. This property is preset to 5.

The gateway captures its own IP address and returns this information in responses sent to the application server. The application server uses the address to locate the physical machine where the gateway runs; this is where the various gateway logs are stored.

In certain instances, the value of the IP address captured may be incorrect, due to issues with the underlying web server. For example, the address may show up as 127.0.0.1, which from the gateway's perspective is correct (since that's the IP loopback address ) but this value is not useful to the application server as it needs the actual IP of the gateway.

PeopleSoft provides the following property that enables you to override the IP address that the gateway captures and hardcode the IP address used for gateway logging:

ig.GatewayIPAddressOverride

This property is located in the Gateway IP Address Override section in the integrationGateway.properties file.

To use the property, set it equal to the IP address of the machine running the integration gateway.

Note that the actual machine that writes the logs does not change. If set the value to one that is not the IP address of the machine that the gateway is actually on, when the application server creates links to display log info, those links will not point to the actual log files.

You can validate XML request messages and response messages against associated document type definitions (DTD) by enabling DTD validation on the integration gateway.

When you set the ig.dtdLookup property equal to True (default), request and response messages are validated against any associated DTD.

References to DTDs may be inline pointers to files or references to URLs.

When you set the ig.dtdLookup property equal to False, no validation takes place—even if a DTD reference is supplied.

If the ig.dtdLookup property is removed or otherwise missing from the integrationGateway.properties file, the system responds as if the property is set to True, and request and response messages are validated against any associated DTD.

The integration gateway maintains a pool of jolt sessions to handle requests between itself and the integration engine. The integration gateway issues a jolt session from the pool, uses it for the connection, and then returns the session to the pool once it receives the response from the integration engine.

The number of sessions to maintain in the session pool is defined in the integrationGateway.properties file using the following property:

ig.connection

Set this property equal to the maximum number of sessions to maintain in the pool. The default value is 10.

The system generates generic SOAP faults for framework-level errors, such as when it cannot find a routing for an integration.

To specify the namespace to use for generic SOAP faults, set the following property in the integrationGateway.properties file equal to the namespace to use:

ig.GenericFaultNamespace

You can enable the display of the PeopleTools version of an integration gateway as part of the information that displays when the gateway is pinged using the Ping Gateway button on the Gateways page.

Set the following property equal to True to enable the display of the PeopleTools version of a integration gateway:

ig.Gateway.showDetails

By default the property is set to False and the PeopleTools version of the gateway does not display when you ping the gateway.

Note: After you change the value for this property you must restart the web server for the new setting to take effect.