How to use the Teradata JDBC Driver with WebSphere Java2 Security

Additional configuration is required in order to use the Teradata JDBC Driver when WebSphere Java 2 security is enforced. For reference, instructions are provided to enable WebSphere Java2 security.

The Teradata JDBC Driver provides the same Communication Processor (COP) discovery behavior as Network CLIv2. The Teradata JDBC Driver first finds all defined COPs. Starting with "COP1", which is appended to the database hostname, and then proceeds with "COP2", "COP3", ..., "COPn" until an undefined name is reached.

The COP discovery approach used by Teradata JDBC Driver requires security permissions to be defined in WebSphere dynamic policy files, including app.policy and was.policy. The permission definitions in these dynamic policy files will be described below.

Defining permissions in app.policy

The app.policy file is located in the following WebSphere directory location for WebSphere 5.1:

<WebSphere-Installation-Root>/config/cells/<cell-name>/nodes/<node-name>

The app.policy file is located in the following WebSphere directory location for WebSphere 6.0 and later:

<WebSphere-Installation-Root>/profiles/<profile-name>/config/cells/<cell-name>/nodes/<node-name>

The app.policy file contains default permissions for all of the enterprise applications in the cell. If security permissions are required for all of the enterprise applications in the cell, these permissions can be defined in app.policy, however, if some security permissions only apply to some specific WebSphere Application Server enterprise application, those permissions must be defined in was.policy, which will be described in the following section.

WebSphere Application Server has the following default permission defined in the app.policy file:

This permission is included in the following segment in app.policy:

The Teradata JDBC Driver's COP discovery technique is compatible with the default permission in the default app.policy file. However, when a site removes that default permission in order to tighten security, then additional specific permissions are required to support the Teradata JDBC Driver's COP discovery.

Assume there are n nodes of the database system, then the following permissions are required:

These permissions must be inserted into app.policy like:

NOTE: If these permissions apply to a specific application only, they should not be defined in app.policy and instead they must be defined in was.policy. The permission definition in was.policy is described below.

Defining permissions in was.policy

The was.policy file is packaged in an enterprise archive (EAR) file. The was.policy file contains application-specific permissions for an WebSphere Application Server enterprise application.

The following permissions will be required in was.policy to meet the requirements for the COP discovery approach of Teradata JDBC Driver. It should be noted that these permissions in was.policy are for the specific application only where it is packaged.

Assume there are n nodes of the database system, then following permissions must be defined:

These permissions must be inserted into was.policy like:

Note: When more nodes are added to the database system, for example, m more nodes, the following additional permissions must be added to was.policy (if these permissions need to apply to all the applications in the cell, then they must be defined in the app.policy file):

Besides the above SocketPermissions, RuntimePermission and FilePermission may also be needed. Depending upon WebSphere application server configurations and the enterprise application structures, the following permissions may be required in was.policy (if these permissions need to apply to all the applications in the cell, then they must be defined in the app.policy file).

Note that you need to substitute the actual directory where the Teradata JDBC Driver is located for "C:/teradatajdbcdriver" shown in the examples below.

Beginning with Teradata JDBC Driver 16.20.00.11, tdgssconfig.jar is no longer used. With older versions of the Teradata JDBC Driver, an additional permission must be granted for tdgssconfig.jar.

In WebSphere Application Server 6.0 and later, applications must have the appropriate thread permissions specified in the was.policy or app.policy file. Without the thread permissions specified, the application cannot manipulate threads and WebSphere Application Server throws a java.security.AccessControlException. Therefore, the following code must be added to was.policy or app.policy file for an application to manipulate threads:

Expected java.security.AccessControlException in WebSphere SystemOut.log file

The COP discovery approach used by Teradata JDBC Driver first finds all defined COPs. Starting with "COP1", which is appended to the database hostname, and then proceeds with "COP2", "COP3", "..., COPn" until an undefined name is reached. When this undefined name is encountered, a java.security.AccessControlException is thrown by WebSphere Java 2 security permission configuration. The Teradata JDBC Driver handles this Java 2 security exception properly so the COP discovery process will be completed successfully and the application will be able to use the data source without any issues.

However, the above Java 2 security exception will still be logged into WebSphere SystemOut.log file since this AccessControlException is generated by WebSphere Java 2 security configuration and the Teradata JDBC Driver has no control over WebSphere Java 2 security configuration.

Assume there are 4 nodes of the database system, and the following permissions have been defined in was.policy:

The WebSphere Java 2 security exception similar to the following contents will be logged into SystemOut.log file:

NOTE: Since the Teradata JDBC Driver COP discovery logic handles this Java 2 security exception properly so the application will be able to use the data source without any issues.