WebLogic Tuxedo Connector Administration Guide

WebLogic Tuxedo Connector Administration

Note: For more information on the WebLogic Server management, including the WebLogic Tuxedo Connector, see the WebLogic Server Configuration Reference.

The following sections describe how to establish connectivity and provide security between WebLogic Server applications and Tuxedo environments. WebLogic Tuxedo Connector uses attributes that are analogous to the interoperability attributes required for the communication between Tuxedo access points.

The following sections provide WebLogic Tuxedo Connector configuration information:

Configuring the Connections Between Access Points

Note: For more information on Dynamic Status, see How ConnectionPolicy Affects Dynamic Status.

Several options can specify the conditions under which an access point tries to establish a connection with a remote access point. Specify these conditions using the ConnectionPolicy attribute in the Connections tab of the Local Tuxedo Access Points and Remote Tuxedo Access Points configurations of your WTC Service. You can select any of the following connection policies:

For connection policies of On Startup and Incoming Only, Dynamic Status is invoked. Dynamic Status checks and reports on the status of imported services associated with each remote access point.

How to Request a Connection at Boot Time (On Startup)

A policy of On Startup means that an access point attempts to establish a connection with its remote access points at gateway server initialization time. The connection policy retries failed connections at regular intervals determined by the RetryInterval parameter and the MaxRetries parameter. To request a connection at boot time, set the ConnectionPolicy attribute in the Connections tab of your local Tuxedo access point to On Startup.

How to Configure RetryInterval

You can control the frequency of automatic connection attempts by specifying the interval (in seconds) during which the access point should wait before trying to establish a connection again. The minimum value is 0; the default value is 60, and maximum value is 2147483647.

How to Configure MaxRetries

Note: Use only when ConnectionPolicy is set to On Startup. For other connection policies, retry processing is disabled.

You indicate the number of times an access point tries to establish connections to remote access points before quitting by assigning a value to the MaxRetries parameter: the minimum value is 0; the default and maximum value is 2147483647.

If you set MaxRetries to 0, automatic connection retry processing is turned off. The server does not attempt to connect to the remote access point automatically.
If you set MaxRetries to a number, the access point tries to establish a connection the specified number of times before quitting.
If you set MaxRetries to 2147483647, retry processing is repeated indefinitely or until a connection is established.

Table 3-1 Example Settings of MaxRetries and RetryInterval Parameters

If you set ...	Then ...
`ConnectionPolicy: On Startup` `RetryInterval: 30` `MaxRetries: 3`	The access point makes 3 attempts to establish a connection, at 30 seconds intervals, before quitting.
`ConnectionPolicy: On Startup` `MaxRetries: 0`	The access point attempts to establish a connection at initialization time but does not retry if the first attempt fails.
`ConnectionPolicy: On Startup` `RetryInterval: 30`	The access point attempts to establish a connection every 30 seconds until a connection is established.

If you set ...

Then ...

ConnectionPolicy: On Startup

RetryInterval: 30

MaxRetries: 3

The access point makes 3 attempts to establish a connection, at 30 seconds intervals, before quitting.

ConnectionPolicy: On Startup

MaxRetries: 0

The access point attempts to establish a connection at initialization time but does not retry if the first attempt fails.

ConnectionPolicy: On Startup

RetryInterval: 30

The access point attempts to establish a connection every 30 seconds until a connection is established.

How to Request Connections for Client Demands (On Demand)

Note: If the ConnectionPolicy is not specified, the WebLogic Tuxedo Connector uses a ConnectionPolicy of 0n Demand.

A connection policy of 0n Demand means that a connection is attempted only when requested by either a client request to a remote service or an administrative connect command.

Accepting Incoming Connections (Incoming Only)

A connection policy of Incoming Only means that an access point does not establish a connection to remote access points upon starting. The access point is available for incoming connections from remote access points and remote services are advertised when the access point receives an incoming connection.

How to use LOCAL Connection Policy

Note: A ConnectionPolicy of LOCAL is not valid for local access points.

A connection policy of LOCAL indicates that a remote domain connection policy is explicitly defaulted to the local domain ConnectionPolicy attribute value. If the remote access point ConnectionPolicy is not defined, the system uses the setting specified by the associated local access point.

How ConnectionPolicy Affects Dynamic Status

Dynamic Status determines the availability of remote services. The connection policy used determines whether the Dynamic Status feature is available for a service. The following table describes how ConnectionPolicy affects Dynamic Status capability.

On Startup	Dynamic Status is on. Services imported from a remote access point are advertised while a connection to that remote access point exists.
0n Demand	Dynamic Status is off. Services imported from remote access points are always advertised.
Incoming Only	Dynamic Status is on. Remote services are initially suspended. The access point is available for incoming connections from remote access points. Remote services are advertised when the access point receives an incoming connection.

Configuring Failover and Failback

Note: In the Tuxedo T/ Domain, there is a limit of two (2) backup remote access points. The WebLogic Tuxedo Connector has no limit to the number of backup access points allowed to be configured for a service.

WebLogic Tuxedo Connector provides a failover mechanism that transfers requests to alternate remote access points when a failure is detected with a primary remote access point. It also provides failback to the primary remote access point when that access point is restored. This level of failover/failback depends on Dynamic Status. The access point must be configured with a connection policy of On Startup or Incoming Only to enable failover/failback.

Prerequisite to Using Failover and Failback

To use failback, you must specify On Startup or Incoming Only as the value of the Connection Policy parameter.

A connection policy of 0n Demand is unsuitable for failback as it operates on the assumption that the remote access point is always available. If you do not specify On Startup or Incoming Only as your connection policy, your servers cannot fail over to the alternate remote access points that you have specified with the Tuxedo RDOM parameter.

Note: A remote access point is available if a network connection to it exists; a remote access point is unavailable if a network connection to it does not exist.

How to Configure Failover

To support failover, you must specify the remote access points responsible for executing a particular service. You must specify the following in your WTC Service:

Create Remote Tuxedo Access Points configurations for each remote access point.
Create Imported Services configurations that specify the service provided by each remote access point.

Suppose a service, TOUPPER, is available from two remote access points: TDOM1 and TDOM3. Your WTC Service would include two Remote Tuxedo Access Point configuratons and two Imported Services configurations in your WTC Service. The WTC Service defined in the config.xml file would contain the following:

<WTCServer Name="WTCsimpapp" 
     <WTCExport EJBName="tuxedo.services.TOLOWERHome"
           LocalAccessPoint="TDOM2" Name="myExportedResources"
          ResourceName="TOLOWER"/>
     <WTCImport LocalAccessPoint="TDOM2" Name="myImportedResources"
          RemoteAccessPointList="TDOM1" ResourceName="TOUPPER"/>
     <WTCImport LocalAccessPoint="TDOM2" Name="2ndImportedResources"
          RemoteAccessPointList="TDOM3" ResourceName="TOUPPER"/>
     <WTCLocalTuxDom AccessPoint="TDOM2" AccessPointId="TDOM2"
          ConnectionPolicy="ON_DEMAND" Interoperate="no"
          NWAddr="//123.123.123.123:5678" Name="myLoclTuxDom" Security="NONE"/>
     <WTCRemoteTuxDom AccessPoint="TDOM1" AccessPointId="TDOM1"
           LocalAccessPoint="TDOM2" NWAddr="//123.123.123.123:1234"
          Name="myRTuxDom"/>
     <WTCRemoteTuxDom AccessPoint="TDOM3" AccessPointId="TDOM3"
           LocalAccessPoint="TDOM2" NWAddr="//234.234.234.234:5555"
          Name="2ndRemoteTuxDom"/>
</WTCServer>

How to Configure Support Failback

Failback occurs when a network connection to the primary remote access point is reestablished for any of the following reasons:

Automatic retries (On Startup only)
Incoming connections

Authentication of Remote Access Points

Note: Tuxedo 6.5 users should set the Interoperate parameter to Yes.

Domain gateways can be made to authenticate incoming connections requested by remote access points and outgoing connections requested by local access points. Application administrators can define when security should be enforced for incoming connections from remote access points. You can specify the level of security used by a particular local access point by setting the Security attribute in the Security tab of the local Tuxedo access point configuration of your WTC Service. There are three levels of password security:

NONE—incoming connections from remote access points are not authenticated.
Application Password— incoming connections from remote access points are authenticated using the application password defined in the Password configuration of your WTC Service. You use the weblogic.wtc.gwt.genpasswd utility to create encrypted application passwords.
Domain Password—this feature enforces security between two or more access points. Connections between the local and remote access points are authenticated using password pairs defined in the Password configuration of your WTC Service. You use the weblogic.wtc.gwt.genpasswd utility to create encrypted local and remote passwords.

The Security attribute in the Security tab of the local Tuxedo access point of your WTC Service must match the SECURITY attribute of the *DM_LOCAL_DOMAINS section of the Tuxedo domain configuration file.

If authentication is required, it is done every time a connection is established between the local access point and the remote access point.
If the security type of the local Tuxedo access point in your WTC Service does not match the security type of the *DM_LOCAL_DOMAINS or if the passwords do not match, the connection fails.

Configuring a Password Configuration

Note: For more information on how to assign a PasswordKey, see How to Set WebLogic Tuxedo Connector Properties.

Use weblogic.wtc.gwt.genpasswd to generate encrypted passwords for Local Password, Remote Password, and App Password attributes. The utility uses a key to encrypt a password that is copied into the Password or Resources configuration of your WTC Service.

The Password configuration of your WTC Service does not store clear text passwords.
The key value is a WebLogic Server property.

PasswordKey is the attribute used to assign the key.

      -Dweblogic.wtc.PasswordKey=mykey

where: mykey is the key value

The PasswordKey attribute can only be assigned one key value. This key value is used for all Weblogic Tuxedo Connector passwords generated (local, remote, and application passwords) for use with a specific WebLogic Server.

Usage

Call the utility without any arguments to display the command line options.

Example:

$ java weblogic.wtc.gwt.genpasswd

Usage: genpasswd Key <LocalPassword|RemotePassword|AppPassword> <local|remote|application>

Call the utility with a key value, password to encrypt, and the type of password.

Example:

$ java weblogic.wtc.gwt.genpasswd Key1 LocalPassword1 local

The utility will respond with the encoded password and password IV. Cut and paste the results into the appropriate fields in Password configuation of your WTC Service.

Local Password   : my_password

Local Password IV: my_passwordIV

where

Cut and paste the string of characters represented by my_password into the Password field.
Cut and paste the string of characters represented by my_passwordIV into the PasswordIV field.

Examples

This section provides examples of each of the password element types.

Local Passwords

The following example uses key1 to encrypt "LocalPassword1" as the password of the local access point.

$ java weblogic.wtc.gwt.genpasswd key1 LocalPassword1 local
Local Password : FMTCg5Vi1mTGFds1U4GKIQQj7s2uTlg/ldBfy6Kb+yY=
Local Password IV : NAGikshMiTE=

Your Password attributes are:

Local Password: FMTCg5Vi1mTGFds1U4GKIQQj7s2uTlg/ldBfy6Kb+yY=
Local Password IV: NAGikshMiTE=

Remote Passwords

The following example uses mykey to encrypt "RemotePassword1" as the password for the remote access point.

$ java weblogic.wtc.gwt.genpasswd mykey RemotePassword1 remote
Remote Password : A/DgdJYOJunFUFJa62YmPgsHan8pC02zPT0T7EigaVg=
Remote Password IV : ohYHxzhYHP0=

Your Password attributes are:

Remote Password: A/DgdJYOJunFUFJa62YmPgsHan8pC02zPT0T7EigaVg=
Remote Password IV: ohYHxzhYHP0=

App Passwords

The following example uses mykey to encrypt "test123" as the application password.

$ java weblogic.wtc.gwt.genpasswd mykey test123 application 
App Password : uou2MALQEZgNqt8abNKiC9ADN5gHDLviqO+Xt/VjakE=
App Password IV : eQuKjOaPfCw=

Your Resources attributes are:

Application Password: uou2MALQEZgNqt8abNKiC9ADN5gHDLviqO+Xt/VjakE=
Application Password IV: eQuKjOaPfCw=

User Authentication

Access Control Lists (ACLs) limit the access to local services within a local access point by restricting the remote Tuxedo access point that can execute these services. Inbound policy from a remote Tuxedo access point is specified using the AclPolicy attribute. Outbound policy towards a remote Tuxedo domain is specified using the CredentialPolicy attribute. This allows WebLogic Server and Tuxedo applications to share the same set of users and the users are able to propagate their credentials from one system to the other.

The valid values for AclPolicy and CredentialPolicy are:

LOCAL
GLOBAL

ACL Policy is LOCAL

If the WebLogic Tuxedo Connector ACL Policy is set to Local, access to local services does not depend on the CredentialPolicy. The Tuxedo remote domain DOMAINID is authenticated as a local WebLogic Server user. To allow WebLogic Tuxedo Connector to authenticate a DOMAINID as a local user, use the WebLogic Server Console to complete the following steps:

Click on the Security node.

Click on Realms.

Select your default security Realm.

Click on Users.

Click the Configure a new User text link.

In the General tab, do the following:

Add the Tuxedo DOMAINID in the Name field.

Enter and validate a password.

Click apply.

ACL Policy is GLobal

If the WebLogic Tuxedo Connector ACL Policy is GLOBAL, access to local services depends on the CredentialPolicy.

Credential Policy is Global

If a remote domain is running with the CredentialPolicy set to GLOBAL, the request has the credentials of the caller.

CredentialPolicy is Local

If a remote domain is running with the CredentialPolicy set to LOCAL, the result depends on the user configuration that initiated the call.

User Authenticaion for Tuxedo 6.5

Tuxedo 6.5 users should set the Interoperate parameter to Yes. The AclPolicy and CredentialPolicy elements are ignored and the Tuxedo remote domain DOMAINID is authenticated as a local WebLogic Server user. If you require User Security features and use the WebLogic Tuxedo Connector, you will need to upgrade to Tuxedo 7.1 or higher.

How to Configure WebLogic Tuxedo Connector to Provide Security between Tuxedo and WebLogic Server

The following sections provide information on how to configure WebLogic Tuxedo provide user security information to Tuxedo:

TpUsrFile Plug-in

The TpUsrFile plug-in provides traditional Tuxedo TpUserFile functionality for users who do not need single point security administration or custom security authentication. Use the following steps to configure WebLogic Tuxedo Connector to provide security between Tuxedo and WebLogic Server applications using the TpUsrFile plug-in AppKey Generator:

Configuring the Local Tuxedo Access Point for the TpUsrFile Plug-in

Set the security attribute in the Security tab of the local Tuxedo access point of your WTC Service to match the SECURITY parameter of the *DM_LOCAL_DOMAINS section of the Tuxedo domain configuration file.

Configure the Remote Tuxedo Access Point for the TpUsrFile Plug-in

Configure the Security tab of the remote Tuxedo access point of your WTC Service to establish an inbound and outbound Access Control List (ACL) policy.

Perform the following steps to prepare the WebLogic Server environment:

Set the AclPolicy attribute to GLOBAL.

Set the CredentialPolicy attribute to GLOBAL.

Set the Allow Anonymous attribute for your environment. If you select to allow anonymous users to access Tuxedo, you must set the value of the Default AppKey to be used by anonymous users. For more information on anonymous users, see Anonymous Users.

Select TpUsrFile from the AppKey Generator dropdown box.

Set the value of the Tp Usr File attribute to the full path to the user password file.

You must have a copy of the Tuxedo tpusr file in your WebLogic Server environment. Copy the tpusr file from TUXEDO to the WebLogic Server application environment or generate your own tpusr file. For more information on how to create a Tuxedo tpusr file, see How to Enable User-Level Authentication.

Using the Resources TpUsrFile attribute

The location of the TpUsrFile can be specified from your remote Tuxedo access point configurations or from your Resources configuration. You may find it convenient assign the value of the TpUsrFile attribute globally at the WTC Service level, rather than by assigning it individually on all of your remote Tuxedo access point configurations. Use the following guidelines to help you determine where to best configure the TpUsrFile attribute:

All TpUsrFile attribute values are ignored if the TpUsrFile Plug-in is not selected as the AppKey Generator, regardless of location.
If the Resources configuation does not have TpUsrFile attribute values, the TpUsrFile attribute value must be specified in the remote Tuxedo access point configurations. The cached user record information is ignored.
If the Resources and remote Tuxedo access point configurations contain TpUsrFile attribute values, the attribute values in the remote Tuxedo access points are used. The cached user record information is ignored.
If the remote Tuxedo access point configuations do not have TpUsrFile attribute values, the TpUsrFile attribute value must be specified in the Resources configuration. The cached user record is used, which improves system performance. However, this restricts the user to have the same identity in all remote Tuxedo access points.

LDAP Plug-in

The LDAP plug-in provides single point security administration that allows you to maintain user security information in a WebLogic Server embedded LDAP server and use the WebLogic Server Console to administer the security information from a single system. Requires Tuxedo 8.1 and higher.Use the following steps to configure WebLogic Tuxedo Connector to provide security between Tuxedo and WebLogic Server applications using the LDAP Plug-in AppKey Generator:

Implementing Single Point Security Administration

Detailed information on how to implement single point security administration, see Implementing Single Point Security Administration. For information on WebLogic Security, see Introduction to WebLogic Security.

Configure the Local Tuxedo Access Point for the LDAP Plug-in

Configure the Remote Tuxedo Access Point for the LDAP Plug-in

Configure the Security tab of the remote Tuxedo access point of your WTC Service to establish an inbound and outbound Access Control List (ACL) policy.

Perform the following steps to prepare the WebLogic Server environment:

Set the AclPolicy attribute to GLOBAL.

Set the CredentialPolicy attribute to GLOBAL.

Select LDAP from the AppKey Generator dropdown box.

If necessary, set the value of the Tuxedo UID Keyword attribute and Tuxedo GID attribute. Default values are provided. These keywords for the Tuxedo user ID (UID) is used to extract the Tuxedo UID and GID in the user record of the embedded LDAP database.

Custom Plug-in

Note: For information on how to create a Custom Plug-in, see How to Create a Custom AppKey Plug-in.

The Custom plug-in provides the ability for you to create customized security authentication. Use the following steps to configure WebLogic Tuxedo Connector to provide security between Tuxedo and WebLogic Server applications using the Custom Plug-in AppKey Generator:

Configure the Local Tuxedo Access Point for the Custom Plug-in

Configure the Remote Tuxedo Access Point for the Custom Plug-in

Configure the Security tab of the remote Tuxedo access point of your WTC Service to establish an inbound and outbound Access Control List (ACL) policy.

Perform the following steps to prepare the WebLogic Server environment:

Set the AclPolicy attribute to GLOBAL.

Set the CredentialPolicy attribute to GLOBAL.

Select Custom from the AppKey Generator dropdown box.

Set the value of the Custom AppKey Class attribute to the full pathname to your Custom AppKey generator class. This class is loaded when the WTC Service is started.

Set the value of the Custom AppKey Param attribute to the optional parameters that you may require to use your Custom AppKey class when it is initialized when the WTC Service starts.

Anonymous Users

The Allow Anonymous attribute on the Security tab of a remote Tuxedo access point specifies whether the anonymous user is allowed to access Tuxedo. If the anonymous user is allowed to access Tuxedo, the value of the Default AppKey attribute is used for TpUsrFile and LDAP AppKey plug-ins. The TpUsrFile and LDAP plug-ins do not allow users that are not defined in user database to access Tuxedo unless the Allow Anonymous attribute is enabled. Interaction with the Custom AppKey plug-in depends on the design of the Custom AppKey generator.

The default value of the Default AppKey is -1. If you wish to use this value, you must make sure that your Tuxedo environment has a user assigned to that key value. You should avoid assigning the Default AppKey value to 0. In some systems, this specifies the user as root.

Anonymous Users and CORBA Services

It is important to understand the differences between how ATMI services and CORBA services authenticate an anonymous user. ATMI services rely on the Default AppKey value sent with the message. Corba services use the default WebLogic Server anonymous user name <anonymous> to identify the user credential defined in the Tuxedo tpusr file. CORBA users must configure the anonymous user using one of the following methods to become an authenticated user:

Add <anonymous> to the Tuxedo tpusr file.
Define anonymous as a user in the WebLogic Authentication provider. You do this by setting the following argument when starting a WebLogic Server instance:

-Dweblogic.security.anonymousUserName=anonymous

Link-Level Encryption

You can use encryption to ensure data privacy. In this way, a network-based eavesdropper cannot learn the content of messages or application-generated messages flowing from one domain gateway to another. You configure this security mechanism by setting the MINENCRYPTBITS and MAXENCRYPTBITS attributes of the Security tab in the local Tuxedo access points and remote Tuxedo access points configurations of your WTC Service.

Note: Encryption requires appropriate licensing. For more information on license requirements, see Licensing.