Sun Identity Manager 8.1 Resources Reference

Chapter 47 Top Secret

The Top Secret resource adapter supports management of user accounts and memberships on an OS/390 mainframe using a TN3270 emulator session.

Adapter Details

The Top Secret resource adapter is defined in the com.waveset.adapter.TopSecretResourceAdapter class.

Resource Configuration Notes

The Top Secret Active Sync adapter works by using FTP to retrieve the output from the TSSAUDIT facility. It then parses the output to look for account creations, modifications, and deletions. This facility generates a report from the data in the Top Secret Recovery file. Therefore, the Recovery File must be enabled and large enough to hold all changes that will occur between the Active Sync poll interval. A job should be scheduled to run the TSSAUDIT utility so that the output will be available before the next Active Sync adapter poll.

An optional Generational Data Group (GDG) can be set up to contain the results of the TSSAUDIT output. A GDG stores previous versions of the TSSAUDIT output. The Active Sync adapter supports retrieving from a GDG to help avoid missing events if it is not able to run at its normal time. The adapter can be configured to go back multiple generations to pick up any events that it might have missed

The following sample JCL runs the TSSAUDIT batch job:

//LITHAUS7  <<<< Supply Valid Jobcard >>>>>>
//* ****************************************************************
//* *  THIS JOB RUNS THE TSS AUDIT PROGRAM ’CHANGES’
//* *    & CREATES A GDG MEMBER FOR IDENTITY MANAGER
//* *  You may choose to use standard MVS Delete/Defines or
//* *   request a system programmer to establish a small GDG
//* ****************************************************************
//AUDIT01  EXEC   PGM=TSSAUDIT,
//          PARM=’CHANGES DATE(-01)’
//AUDITOUT DD DSN=auth hlq.LITHAUS.ADMIN.DAILY(+1),
//          DISP=(NEW,CATLG),UNIT=SYSDA,RECFM=FB,LRECL=133,
//          BLKSIZE=2793,SPACE=(CYL,(2,1),RLSE)
//RECOVERY DD   DSN=your.TSS.recovery.file ,DISP=SHR
//AUDITIN  DD DUMMY

Identity Manager Installation Notes

The Top Secret resource adapter is a custom adapter. You must perform the following steps to complete the installation process:

Installing the Top Secret Resource Adapter

To add the Top Secret resource to the Identity Manager resources list, you must add the following value in the Custom Resources section of the Configure Managed Resources page.
com.waveset.adapter.TopSecretResourceAdapter

Copy the appropriate JAR files to the WEB-INF/lib directory of your Identity Manager installation.

Connection Manager	JAR Files
Host On Demand	The IBM Host Access Class Library (HACL) manages connections to the mainframe. The recommended JAR file containing HACL is `habeans.jar`. It is installed with the HOD Toolkit (or Host Access Toolkit) that comes with HOD. The supported versions of HACL are in HOD V7.0, V8.0, V9.0, and V10. However, if the toolkit installation is not available, the HOD installation contains the following JAR files that can be used in place of the `habeans.jar`: `habase.jar` `hacp.jar` `ha3270.jar` `hassl.jar` `hodbase.jar` See http://www.ibm.com/software/webservers/hostondemand/ for more information.
Attachmate WRQ	The Attachmate 3270 Mainframe Adapter for Sun product contains the files needed to manage connections to the mainframe. `RWebSDK.jar` `wrqtls12.jar` `profile.jaw` Contact Sun Professional Services about getting this product.

Connection Manager

JAR Files

Host On Demand

The IBM Host Access Class Library (HACL) manages connections to the mainframe. The recommended JAR file containing HACL is habeans.jar. It is installed with the HOD Toolkit (or Host Access Toolkit) that comes with HOD. The supported versions of HACL are in HOD V7.0, V8.0, V9.0, and V10.

However, if the toolkit installation is not available, the HOD installation contains the following JAR files that can be used in place of the habeans.jar:

habase.jar
hacp.jar
ha3270.jar
hassl.jar
hodbase.jar

See http://www.ibm.com/software/webservers/hostondemand/ for more information.

Attachmate WRQ

The Attachmate 3270 Mainframe Adapter for Sun product contains the files needed to manage connections to the mainframe.

RWebSDK.jar
wrqtls12.jar
profile.jaw

Contact Sun Professional Services about getting this product.

Add the following definitions to the Waveset.properties file to define which service manages the terminal session:
serverSettings.serverId.mainframeSessionType=Value serverSettings.default.mainframeSessionType=Value
Value can be set as follows:
- 1 indicates IBM Host On-Demand (HOD)
  - 3 indicates Attachmate WRQ
    
    If these properties are not explicitly set, then Identity Manager attempts to use WRQ, then HOD.

When the Attachmate libraries are installed into a WebSphere or WebLogic application server, add the property com.wrq.profile.dir=LibraryDirectory to the WebSphere/AppServer/configuration/config.ini or startWeblogic.sh file.

This allows the Attachmate code to find the licensing file.

Restart your application server so that the modifications to the Waveset.properties file can take effect.

See Chapter 53, Mainframe Connectivity for information about configuring SSL connections to the resource.

Usage Notes

This section provides information related to using the Top Secret resource adapter, which is organized into the following sections:

Administrators

TSO sessions do not allow multiple, concurrent connections. To achieve concurrency for Identity Manager Top Secret operations, you must create multiple administrators. Thus, if two administrators are created, two Identity Manager Top Secret operations can occur at the same time. You should create at least two (and preferably three) administrators.

CICS sessions are not limited to one session per admin; however, you can define more than one admin if desired.

If you are running in a clustered environment, you must define an admin for each server in the cluster. This applies even if (as in the case of CICS) it is the same admin. For TSO, there must be a different admin for each server in the cluster.

If clustering is not being used, the server name should be the same for each row (the name of the Identity Manager host machine).

Note –

Host resource adapters do not enforce maximum connections for an affinity administrator across multiple host resources connecting to the same host. Instead, the adapter enforces maximum connections for affinity administrators within each host resource.

If you have multiple host resources managing the same system, and they are currently configured to use the same administrator accounts, you might have to update those resources to ensure that the same administrator is not trying to perform multiple actions on the resource simultaneously.

Resource Actions

The Top Secret adapter requires login and logoff resource actions. The login action negotiates an authenticated session with the mainframe. The logoff action disconnects when that session is no longer required.

See Mainframe Examples for more information about creating login and logoff resource actions.

SSL Configuration

Identity Manager uses TN3270 connections to communicate with the resource.

See Chapter 53, Mainframe Connectivity for information about setting up an SSL connection to a RACF LDAP resource.

Provisioning Notes

The following table summarizes the provisioning capabilities of this adapter.

Feature	Supported?
Enable/disable account	Yes
Rename account	No
Pass-through authentication	No
Before/after actions	Yes
Data loading methods	Import directly from resource Reconciliation Active Sync

Security Notes

This section provides information about supported connections and privilege requirements.

Supported Connections

Identity Manager uses TN3270 to communicate with the Top Secret adapter.

Required Administrative Privileges

Administrators must have the following privileges:

ACID(CREATE) authority, through the TSS ADMIN function, to CREATE ACIDs under their administrative scope
RESOURCE(OWN) authority, through the TSS ADMIN function, to assign resource ownership to ACIDs within their scope
MISC1, MISC2 and MISC9 authorities, through the TSS ADMIN function, to assign many of the security attributes

Account Attributes

The following table provides information about the default Top Secret account attributes.

Identity System Attribute Name	Resource Attribute Name	Data Type	Description
`Profiles`	PROFILE	String	The profile assigned to the user. This attribute is capable of having multiple values.
`accountId`	ACID	String	Required. Account ID
`fullname`	NAME	String	The user’s first and last name
`Installation Data`	INSTDATA	String	Installation data
`TSOO Access`	TSO_ACCESS	Boolean	Indicates whether the user has TSO access
`TSOLPROC`	TSO.TSOLPROC	String	TSO login procedure
`OMVS Access`	OMVS_ACCESS	Boolean	Indicates whether the user has OMVS access
`Groups`	GROUP	String	A list of groups assigned to the user
`Default Group`	DFLTGRP	String	The user’s default group
`UID`	OMVS.UID	String	OMVS User ID
`OMVSPGM`	OMVS.OMVSPGM	String	The user’s initial OMVS program
`HOME`	OMVS.HOME	String	The user’s OMVS home directory
`Attributes`	ATTRIBUTE	String	A list of account attributes

The following table lists account attributes that are supported, but are not listed in the schema map by default. The data type for these attributes is string.

Resource Attribute Name	Description
`CICS.OPTIME`	Controls the period of time allowed before CICS considers a terminal user to be timed-out.
`CICS.OPID`	Specifies the CICS operator ID.
`DEPT`	Specifies the department name.
`DIV`	Specifies the division name.
`ZONE`	Specifies the zone name.
`FACILITY`	Specifies a list of facilities an ACID may or may not access.
`DATASET`	Specifies a list of datasets for the user.
`CORPID`	Specifies a list of corporate IDs.
`OTRAN`	Specifies a list of ownable transactions.
`TSOACCT`	Specifies a list of TSO account numbers.
`SOURCE`	Specifies a list of source readers or terminal prefixes through which the associated ACID may enter the system.
`TSO.TRBA`	Specifies the relative block address (RBA) of the user’s mail directory entry in the broadcast data set
`TSO.TSOCOMMAND`	Provides a default command to be issued at TSO logon.
`TSO.TSODEFPRFG`	Assigns a default TSO performance group.
`TSO.TSODEST`	Provides a default destination identifier for TSO generated JCL for TSO users.
`TSO.TSOHCLASS`	Assigns a default hold class for TSO generated JCL for TSO users.
`TSO.TSOJCLASS`	Assigns a default job class for TSO generated job cards from TSO users.
`TSO.TSOLACCT`	Provides a default account number to be used for TSO logon.
`TSO.TSOLSIZE`	Assigns a default region size (in kilobytes) for TSO.
`TSO.TSOMCLASS`	Assigns a default message class for TSO generated JCL for TSO users.
`TSO.TSOMSIZE`	Defines the maximum region size (in kilobytes) that a TSO user may specify at logon.
`TSO.TSOOPT`	Assigns default options that a TSO user may specify at logon.
`TSO.TSOSCLASS`	Assigns a default SYSOUT class for TSO generated JCL for TSO users.
`TSO.TSOUDATA`	Assigns a site-defined data field to a TSO user.
`TSO.TSOUNIT`	Assigns a default unit name to be used for dynamic allocations under TSO.
`TSO.TUPT`	Specifies the value of the user profile table.

Contact your services organization for details about supporting other Top Secret resource attributes.

Identity Template

$accountId$

Sample Forms

Built-In

None

Also Available

TopSecretUserForm.xml

Troubleshooting

Use the Identity Manager debug pages to set trace options on the following classes:

com.waveset.adapter.HostAccess
com.waveset.adapter.TopSecretResourceAdapter

The hostAccess object may be traced in Identity Manager. The class to trace through the debug pages is com.waveset.adapter.HostAccess. Trace level 3 is sufficient to identify which keystrokes and wait messages were sent to the mainframe; trace level 4 will display the exact message sent and the response from the mainframe.

Note –

Verify that the Trace File location is meaningful. By default the trace file is placed in the application directory under InstallDir/idm/config. If the application is deployed from a WAR, the path may need to be hard-coded with an absolute directory path. In a clustered environment, the trace file should be written to a network share.

In addition to source tracing, it may also be useful to log the screen text before each attempt to send keystrokes. This can be accomplished through a file writer. The sequence of commands is:

Logging Screen Text Before Each Attempt to Send Keystrokes

var file = new java.io.File(”<filename>’);var writer = new java.io.BufferedWriter(new java.io.FileWriter(file));writer.write(hostAccess.getScreen());writer.flush();

hostAccess.sendKeysAndWait(<cmd>,<msg>);

writer.newLine();

writer.write(hostAccess.getScreen());

writer.flush();

writer.close();

<filename> should reference a the location of a file on the local file system of the application server. The writer will open a handle to that location and write what is stored in it’s buffer when the flush() method is invoked. The close() method releases the handle to the file. The getScreen() method is useful to pass to this function to get a dump of the screen contents for debugging purposes. This tracing should, of course, be removed once the screens are successfully navigated and login / logout is performed successfully.