|
| |
| Sun Java System Identity Manager 6.0 Resources Reference 2005Q4M3 | |
Top SecretThe Top Secret resource adapter supports management of user accounts and memberships on an OS/390 mainframe via the IBM Host Access Class Library APIs. The adapter manages Top Secret over a TN3270 emulator session.
The Top Secret resource adapter is defined in the com.waveset.adapter.TopSecretResourceAdapter class. The adapter supports the following versions of Top Secret:
- 5.3
Note The Top Secret Active Sync adapter (com.waveset.adapter.
TopSecretResourceAdapter has been deprecated as of Identity Manager 5.0 SP1. All features in this adapter are now in the Top Secret adapter. Although existing instances of the Top Secret Active Sync adapter will still function, new instances of these can no longer be created.
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:
- To add a Top Secret adapter to the Identity Manager resources list, you must add one of the following values in the Custom Resources section of the Configure Managed Resources page.
com.waveset.adapter.TopSecretResourceAdapter
com.waveset.adapter.TopSecretActiveSyncAdapter
- The Identity Manager mainframe adapters use the IBM Host Access Class Library (HACL) to connect to the mainframe. The HACL is available in IBM Websphere Host On-Demand (HOD). The recommended jar containing HACL is habeans.jar and 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, and V9.0.
However, if the toolkit installation is not available, the HOD installation contains the following jars that can be used in place of the habeans.jar:
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. We recommend that you 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.
A thin client host access 3270 emulator is provided to the context of the resource action by the resource adapter to simplify execution of commands in the scripted session.
Resource Action Context
Several global variables may be expected within the context of the scripted action.
HostAccess API
The following table describes the methods available on the hostAccess object passed to the resource action.
Mnemonic Keywords for the SendKeys Method
The following table describes the special functions that may be executed through the 3270 emulator to simulate keying the non-alphanumeric values.
Sample Resource Actions
The following code is a complete sample of login and login resource actions. The sample is tailored to a specific customer’s environment. As such, the text of commands, prompt, and command sequences will most likely differ across deployments (for example, Line 32 – “ISPF”). Note that the resource actions wrap Javascript inside of XML.
Login Action
1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
3 <Waveset>
4 <ResourceAction name='ACME Login Action'>
5 <ResTypeAction restype='TopSecret'>
6 <act>
7 var TSO_MORE = " ***";
8 var TSO_PROMPT = " READY";
9 var TS_PROMPT = " ?";
10 hostAccess.waitForString("ENTER YOUR APPLICATION NAME");
11 hostAccess.sendKeys("tso[enter]");
12 hostAccess.waitForString("ENTER USERID –");
13 hostAccess.sendKeys(user + "[enter]");
14 hostAccess.waitForString("TSO/E LOGON");
15 hostAccess.sendKeys(password.decryptToString() + "[enter]");
16 hostAccess.sendKeys(password.decryptToString());
17 var pos = hostAccess.searchText(" -Nomail", false);
18 if (pos != 0) {
19 hostAccess.setCursorPos(pos);
20 hostAccess.sendKeys("S");
21 }
22 pos = hostAccess.searchText(" -Nonotice", false);
23 if (pos != 0) {
24 hostAccess.setCursorPos(pos);
25 hostAccess.sendKeys("S");
26 }
27 hostAccess.sendKeys("[enter]");
28 hostAccess.waitForStringAndInput(TSO_MORE);
29 hostAccess.sendKeys("[enter]");
30 hostAccess.waitForStringAndInput(TSO_MORE);
31 hostAccess.sendKeys("[enter]");
32 hostAccess.waitForStringAndInput("ISPF");
33 hostAccess.sendKeys("=x[enter]");
34 hostAccess.waitForString(TSO_PROMPT);
35 var resp =hostAccess.doCmd("PROFILE NOPROMPT MSGID NOINTERCOM NOPAUSE NOWTPMSG PLANGUAGE(ENU) SLANGUAGE(ENU) NOPREFIX[enter]", TSO_PROMPT, TSO_MORE);
36 hostAccess.waitForStringAndInput("ENTER LOGON:");
37 hostAccess.sendKeys(system + "[enter]");
38 hostAccess.waitForStringAndInput("USER-ID.....");
39 hostAccess.sendKeys(user + "[tab]" + password.decryptToString() + "[enter]");
40 var stringsToHide = new java.util.ArrayList();
41 stringsToHide.add(password.decryptToString());
42 hostAccess.waitForString("==>", stringsToHide);
43 hostAccess.waitForInput();
44 hostAccess.sendKeys("[pf6]");
45 hostAccess.waitForInput();
46 </act>
47 </ResTypeAction>
48 </ResourceAction>
Logoff Action
49 <ResourceAction name='ACME Logoff Action'>
50 <ResTypeAction restype='TopSecret'>
51 <act>
52 var TSO_PROMPT = " READY";
53 hostAccess.sendKeys("[clear]end[enter]");
54 hostAccess.waitForString(TSO_PROMPT);
55 hostAccess.sendKeys("logoff[enter]");
56 </act>
57 </ResTypeAction>
58 </ResourceAction>
59 </Waveset>
SSL Configuration
Connecting the Adapter to a Telnet/TN3270 Server using SSL or TLS.
Use the following steps to connect Top Secret resource adapters to a Telnet/TN3270 server using SSL/TLS.
- Obtain the Telnet/TN3270 server's certificate in the PKCS #12 file format. Use hod as the password for this file. Consult your server's documentation on how to export the server’s certificate. The procedure “Generating a PKCS #12 File” below for some general guidelines.
- Create a CustomizedCAs.class file from the PKCS #12 file. If you are using a recent version of HOD, use the following command to do this.
..\hod_jre\jre\bin\java -cp ../lib/ssliteV2.zip;../lib/sm.zip com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT CustomizedCAs.p12 hod CustomizedCAs.class
- Place the CustomizedCAs.class file somewhere in the Identity Manager server's classpath, such as $WSHOME/WEB-INF/classes.
- If a resource attribute named Session Properties does not already exist for the resource, then use the BPE or debug pages to add the attribute to the resource object. Add the following definition in the <ResourceAttributes> section:
<ResourceAttribute name='Session Properties' displayName='Session Properties' description='Session Properties' multi='true'>
</ResourceAttribute>
- Go to the Resource Parameters page for the resource and add the following values to the Session Properties resource attribute:
SESSION_SSL
true
Generating a PKCS #12 File
The following procedure provides a general description of generating a PKCS #12 file when using the Host OnDemand (HOD) Redirector using SSL/TLS. Refer to the HOD documentation for detailed information about performing this task.
- Create a new HODServerKeyDb.kdb file using the IBM Certificate Management tool. As part of that file, create a new self-signed certificate as the default private certificate.
If you get a message that is similar to “error adding key to the certificate database” when you are creating the HODServerKeyDb.kdb file, one or more of the Trusted CA certificates may be expired. Check the IBM website to obtain up-to-date certificates.
- Export that private certificate as Base64 ASCII into a cert.arm file.
- Create a new PKCS #12 file named CustomizedCAs.p12 with the IBM Certificate Management tool by adding the exported certificate from the cert.arm file to the Signer Certificates. Use hod as the password for this file.
Troubleshooting
You can enable tracing of the HACL by adding the following to the Session Properties resource attribute:
SESSION_TRACE
ECLSession=3 ECLPS=3 ECLCommEvent=3 ECLErr=3 DataStream=3 Transport=3 ECLPSEvent=3
Note The trace parameters should be listed without any new line characters. It is acceptable if the parameters wrap in the text box.
The Telnet/TN3270 server should have logs that may help as well.
Provisioning Notes
The following table summarizes the provisioning capabilities of this adapter.
Feature
Supported?
Enable/disable account
Yes
Rename account
Yes
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, via the TSS ADMIN function, to CREATE ACIDs under their administrative scope
- RESOURCE(OWN) authority, via the TSS ADMIN function, to assign resource ownership to ACIDs within their scope
- MISC1, MISC2 and MISC9 authorities, via 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.
The following table lists account attributes that are suported, but are not listed in the schema map by default. The data type for these attributes is string.
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:
The hostAccess object may be traced in Identity Manager. The class to trace via 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 hardcoded with an absolute directory path. In a clustered environment, it is recommended that the trace file 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:
<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.