CATop Secret for z/OSAdapter Installation and ... · CATop Secret for z/OSAdapter Installation and...

IBM Security Identity ManagerVersion 6.0

CA Top Secret for z/OS AdapterInstallation and Configuration Guide

SC27-4424-02

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 119.

Edition notice

Note: This edition applies to version 6.0 of IBM Security Identity Manager (product number 5724-C34) and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2012, 2014.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . vii

Preface . . . . . . . . . . . . . . . ixAbout this publication . . . . . . . . . . . ixAccess to publications and terminology . . . . . ixAccessibility . . . . . . . . . . . . . . xTechnical training. . . . . . . . . . . . . xSupport information . . . . . . . . . . . . xStatement of Good Security Practices . . . . . . x

Chapter 1. Overview of the CA TopSecret Adapter . . . . . . . . . . . . 1CA Top Secret Adapter considerations . . . . . . 2Adapter interactions with the IBM Security IdentityManager server . . . . . . . . . . . . . 3

Chapter 2. Preparation for installing theCA Top Secret Adapter . . . . . . . . 5Preinstallation roadmap . . . . . . . . . . 5Installation roadmap. . . . . . . . . . . . 5Prerequisites . . . . . . . . . . . . . . 5Software download . . . . . . . . . . . . 6

Chapter 3. Installation and configurationof the CA Top Secret Adapter . . . . . 7Uploading the adapter package on z/OS . . . . . 7Installing the ISPF dialog . . . . . . . . . . 7Running the ISPF dialog . . . . . . . . . . 8Starting and stopping the adapter . . . . . . . 16Configuration of communication . . . . . . . 16

Importing the adapter profile into the IBMSecurity Identity Manager server . . . . . . 17Verification of the adapter profile installation . . 17Creating a CA Top Secret Adapter service . . . 18

Chapter 4. First steps after installation 21Adapter configuration for IBM Security IdentityManager . . . . . . . . . . . . . . . 21

z/OS UNIX System Services considerations . . 21Configuration of CA Top Secret access . . . . 21Starting the adapter configuration tool . . . . 24Viewing configuration settings . . . . . . . 25Changing protocol configuration settings . . . 26Configuring event notification . . . . . . . 29Setting attributes for reconciliation. . . . . . 42Modifying an event notification context . . . . 43Changing the configuration key . . . . . . 46Changing activity logging settings . . . . . . 47Modifying registry settings . . . . . . . . 49Modifying non-encrypted registry settings . . . 49

Changing advanced settings . . . . . . . . 50Viewing statistics . . . . . . . . . . . 51Code page settings . . . . . . . . . . . 52Accessing help and additional options . . . . 54

Customization of the CA Top Secret Adapter . . . 56ISIMEXIT . . . . . . . . . . . . . . 57ISIMEXEC . . . . . . . . . . . . . . 61Supporting user-defined ACID fields withextended attributes . . . . . . . . . . . 62Comments with the CA Top Secret commandstring . . . . . . . . . . . . . . . 68

Configuration of SSL authentication for the adapter 68Overview of SSL and digital certificates . . . . 68SSL authentication . . . . . . . . . . . 71Configuring certificates for SSL authentication . . 71Managing SSL certificates with the certToolutility . . . . . . . . . . . . . . . 75

Chapter 5. Troubleshooting of the CATop Secret Adapter errors . . . . . . 83Techniques for troubleshooting problems . . . . 85Troubleshooting APPC problems . . . . . . . 87Adapter log files. . . . . . . . . . . . . 87CA Top Secret/SSL adapter information to begathered for support requests . . . . . . . . 88

Chapter 6. Upgrading the adapter . . . 91

Chapter 7. Uninstalling the adapter . . 93

Appendix A. Adapter attributes . . . . 95

Appendix B. Registry settings . . . . 107

Appendix C. Environment variables 109

Appendix D. CA Top Secret useraccount form . . . . . . . . . . . 111

Appendix E. Support information . . . 113Searching knowledge bases . . . . . . . . . 113Obtaining a product fix . . . . . . . . . . 114Contacting IBM Support . . . . . . . . . . 114

Appendix F. Accessibility features forIBM Security Identity Manager . . . . 117

Notices . . . . . . . . . . . . . . 119

Index . . . . . . . . . . . . . . . 123

© Copyright IBM Corp. 2012, 2014 iii

iv IBM Security Identity Manager: CA Top Secret for z/OS Adapter Installation and Configuration Guide

Figures

1. The CA Top Secret Adapter components . . . 12. One-way SSL authentication (server

authentication) . . . . . . . . . . . 723. Two-way SSL authentication (client

authentication) . . . . . . . . . . . 73

4. Adapter operating as an SSL server and anSSL client . . . . . . . . . . . . . 74

© Copyright IBM Corp. 2012, 2014 v

vi IBM Security Identity Manager: CA Top Secret for z/OS Adapter Installation and Configuration Guide

Tables

1. Preinstallation roadmap . . . . . . . . . 52. Installation roadmap . . . . . . . . . . 53. Prerequisites to install the adapter . . . . . 64. ISPF dialog data sets . . . . . . . . . . 85. APPC transaction names . . . . . . . . 146. Options for the main configuration menu 257. Options for the DAML protocol menu . . . 278. Options for the event notification menu 369. Attributes for search . . . . . . . . . 38

10. Name values and their description . . . . . 3911. Organization chart example . . . . . . . 4012. Organization chart example . . . . . . . 4113. Options for the Modify Context Menu 44

14. DN elements and definitions . . . . . . . 4515. Options for the activity logging menu. . . . 4816. Attribute configuration option description 5017. Options for the advanced settings menu 5118. Arguments and description for the agentCfg

help menu . . . . . . . . . . . . . 5519. ISIMEXIT processing information . . . . . 5820. ISIMEXEC processing information . . . . . 6121. Error messages, warnings, and corrective

actions . . . . . . . . . . . . . . 8322. Account form attributes . . . . . . . . 9523. Registry settings and additional information 10724. CA Top Secret Adapter environment variables 109

© Copyright IBM Corp. 2012, 2014 vii

viii IBM Security Identity Manager: CA Top Secret for z/OS Adapter Installation and Configuration Guide

Preface

About this publicationThe CA Top Secret for z/OS Adapter Installation and Configuration Guideprovides the basic information that you can use to install and configure the IBM®

Security Identity Manager CA Top Secret for z/OS® Adapter (CA Top SecretAdapter).

The CA Top Secret Adapter enables connectivity between the IBM Security IdentityManager server and a network of systems that run the Multiple Virtual Storage(MVS™) operating system. After the adapter is installed and configured, IBMSecurity Identity Manager manages access to z/OS operating system resources.

Access to publications and terminologyThis section provides:v A list of publications in the “IBM Security Identity Manager library.”v Links to “Online publications.”v A link to the “IBM Terminology website.”

IBM Security Identity Manager library

For a complete listing of the IBM Security Identity Manager and IBM SecurityIdentity Manager Adapter documentation, see the online library(http://www-01.ibm.com/support/knowledgecenter/SSRMWJ/welcome).

Online publications

IBM posts product publications when the product is released and when thepublications are updated at the following locations:

IBM Security Identity Manager libraryThe product documentation site (http://www-01.ibm.com/support/knowledgecenter/SSRMWJ/welcome) displays the welcome page andnavigation for the library.

IBM Security Systems Documentation CentralIBM Security Systems Documentation Central provides an alphabetical listof all IBM Security Systems product libraries and links to the onlinedocumentation for specific versions of each product.

IBM Publications CenterThe IBM Publications Center site ( http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss) offers customized search functionsto help you find all the IBM publications you need.

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in onelocation. You can access the Terminology website at http://www.ibm.com/software/globalization/terminology.

© Copyright IBM Corp. 2012, 2014 ix

http://www-01.ibm.com/support/knowledgecenter/SSRMWJ/welcome



https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM%20Security%20Systems%20Documentation%20Central/page/Welcome

http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/software/globalization/terminology

http://www.ibm.com/software/globalization/terminology

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Technical trainingFor technical training information, see the following IBM Education website athttp://www.ibm.com/software/tivoli/education.

Support informationIBM Support provides assistance with code-related problems and routine, shortduration installation or usage questions. You can directly access the IBM SoftwareSupport site at http://www.ibm.com/software/support/probsub.html.

Appendix E, “Support information,” on page 113 provides details about:v What information to collect before contacting IBM Support.v The various methods for contacting IBM Support.v How to use IBM Support Assistant.v Instructions and problem-determination resources to isolate and fix the problem

yourself.

Note: The Community and Support tab on the product information center canprovide additional support resources.

Statement of Good Security PracticesIT system security involves protecting systems and information throughprevention, detection and response to improper access from within and outsideyour enterprise. Improper access can result in information being altered, destroyed,misappropriated or misused or can result in damage to or misuse of your systems,including for use in attacks on others. No IT system or product should beconsidered completely secure and no single product, service or security measurecan be completely effective in preventing improper use or access. IBM systems,products and services are designed to be part of a comprehensive securityapproach, which will necessarily involve additional operational procedures, andmay require other systems, products or services to be most effective. IBM DOESNOT WARRANT THAT ANY SYSTEMS, PRODUCTS OR SERVICES AREIMMUNE FROM, OR WILL MAKE YOUR ENTERPRISE IMMUNE FROM, THEMALICIOUS OR ILLEGAL CONDUCT OF ANY PARTY.

x IBM Security Identity Manager: CA Top Secret for z/OS Adapter Installation and Configuration Guide

http://www.ibm.com/software/tivoli/education

http://www.ibm.com/software/support/probsub.html

Chapter 1. Overview of the CA Top Secret Adapter

An adapter is a program that provides an interface between a managed resourceand the IBM Security Identity Manager server.

Adapters might reside on the managed resource. The IBM Security IdentityManager server manages access to the resource by using the security system.Adapters function as trusted virtual administrators on the target platform. Theadapter performs tasks, such as creating login IDs, suspending IDs, and otherfunctions that administrators run manually. The adapter runs as a service,independently of whether you are logged on to IBM Security Identity Manager.

IBM Security Identity Manager works with CA Top Secret in an MVS environment.The CA Top Secret Adapter:v Receives provisioning requests from IBM Security Identity Manager.v Processes the requests to add, modify, suspend, restore, delete, and reconcile

user information from the CA Top Secret database.v Converts the Directory Access Markup Language (DAML) requests that are

received from IBM Security Identity Manager to corresponding CA Top Secretfor z/OS commands by using Enrole Resource Management API (ERMA)libraries.

v Forwards the commands to a command executor through a series of AdvancedProgram to Program Communication (APPC) requests. The command executorreceives the formatted CA Top Secret for z/OS command strings and sends thecommand to the adapter through the Time Sharing Option (TSO).

v Returns the results of the command including the success or failure message of arequest to IBM Security Identity Manager.

The following figure describes the various components of the adapter.

AdapterReceives and processes requests from IBM Security Identity Manager. Theadapter can handle multiple requests simultaneously. Each request resultsin execution of an APPC/MVS transaction. The binaries of the adapter andrelated external files reside in the Unix System Services environment ofz/OS (OS/390®).

Figure 1. The CA Top Secret Adapter components

© Copyright IBM Corp. 2012, 2014 1

Command ExecutorOperates as an APPC/MVS transaction that is triggered from an incomingrequest from the adapter. APPC requests consist of commands. The adapterruns these commands with the Command Executor in an APPC/MVSenvironment.

Reconciliation ProcessorThe processor operates as an APPC/MVS transaction that is triggered byan incoming request to the adapter. By default, the Reconciliation Processorruns the CA Top Secret database unload utility (TSSCFILE) to obtain data.You can also modify the Job Control Language (JCL) to read an existinginput file that the TSSCFILE utility produces.

Note: When you submit a reconciliation request from IBM SecurityIdentity Manager, the Reconciliation Processor component runs theTSSCFILE to unload the CA Top Secret database. This creates a file thatcontains the required contents of the CA Top Secret database.

When an APPC/MVS transaction fails, there is no cascading failure of the adapterprocess.

CA Top Secret Adapter considerationsThe CA Top Secret Adapter does not require APF authorization. It does require anAccessor ID (ACID) with specific authorization.

The CA Top Secret Adapter operates in two modes.v If no operational ACID is specified on the IBM Security Identity Manager service

form when a request is issued, the ACID that the adapter uses requires specificprivileges. For example, if the adapter administers all users in the CA Top Secretdatabase (apart from creating type SCA users), it must operate with SecurityAdministrator (SCA) type of Top Secret ACID.If IBM Security Identity Manager performs operations against only a portion ofthe CA Top Secret database, the adapter must be associated with a securityadministrator with the appropriate privileges for the portion of the database itadministers. The following figure depicts the preceding scenario.

IBM Security IdentityManager Server

Z/OS Platform

CA Top Secret SSLService Form

Agent operatingin UNIX System

Services

CommandProcessor

Operating inAPPC/MVS

"CA Top Secret

"

ID under whichrequests will be

processed field onservice form is set to blank

CA Top Secret IDassigned to

agent isITIAGNT" ”

CA Top Secret IDused for processing

requests will beITIAGNT" ”

v If the operations are performed under an ACID specified on the IBM SecurityIdentity Manager service form, the CA Top Secret ACID the adapter uses doesnot require any special privileged attributes. It does, however, require surrogateauthority to run functions under the identity of the ACID specified on the IBMSecurity Identity Manager service form. The ACID specified on the IBM SecurityIdentity Manager service form must have authority to perform theadministration functions requested by the IBM Security Identity Manager server.

2 IBM Security Identity Manager: CA Top Secret for z/OS Adapter Installation and Configuration Guide

The following figure depicts the preceding scenario:

IBM Security IdentityManager Server

Z/OS Platform

CA Top Secret SSLService Form

Agent operatingin UNIX System

Services

CommandProcessor

Operating inAPPC/MVS

"CA Top Secret

"

" "

ID underwhich requests will be

processed field onservice form is set to

.ADMINX

CA Top Secret IDassigned to agent is

ITIAGNT" ”

CA Top Secret IDused for processing

requests will beADMINX" ”

ADMINX

The CA Top Secret resources that require consideration are:

FACILITY class profile STGADMIN.IGG.DEFDEL.UALIAS, with READThe adapter requires permissions to update the master catalog. Therefore,the adapter ACID must have one of the following permissions:v UPDATE access to the DATASET class profile that protects the master

catalog.v READ access to the FACILITY class profile that protects the

STGADMIN.IGG.DEFDEL.UALIAS resource. The FACILITY class profilecan update the master catalog irrespective of the FACILITY class profilename.

SURROGAT class profile ATBALLC.userid, with READThe surrogate profile is required if the adapter ACID differs from the ACIDunder which commands and reconciliations are performed.

APPCLU class profile vtamnode.appcname.appcname, with SESSION segmentThe Interactive System Productivity Facility (ISPF) customization dialoggenerates the required APPCLU profiles.

Note: The ISPF customization dialog generates job streams to register thenecessary APPC/MVS transactions.

Adapter interactions with the IBM Security Identity Manager serverThe CA Top Secret Adapter uses IBM Security Identity Manager to perform usertasks on CA Top Secret for z/OS.

The adapter can add, modify, suspend, restore, reconcile, or delete users from CATop Secret. The adapter uses the TCP/IP protocol to communicate with IBMSecurity Identity Manager.

The CA Top Secret Adapter does not use Secure Socket Layer (SSL) by default tocommunicate with IBM Security Identity Manager. To enable SSL you mustperform post configuration steps.

SSL requires digital certificates and private keys to establish communicationbetween the endpoints. Regarding SSL, the CA Top Secret Adapter is considered aserver. When the adapter uses the SSL protocol, the server endpoint must contain adigital certificate and a private key. The client endpoint (IBM Security IdentityManager) must contain the Certificate Authority or CA certificate.

To enable SSL communication by default, install a digital certificate and a privatekey on the adapter and install the CA certificate onIBM Security Identity Manager.

Chapter 1. Overview of the CA Top Secret Adapter 3

The default TCP/IP port on the z/OS host for the adapter and servercommunication is 45580. You can change this port to a different port. When youspecify the port number on the adapter service form on IBM Security IdentityManager, make sure that it references the same port number that is configured forthe adapter on the z/OS host.

Use the agentCfg utility to configure the adapter. The utility communicates withthe adapter through TCP/IP. The TCP/IP port number used is dynamicallyassigned and is in the range 44970 - 44994. The port number and the range of portnumbers cannot be configured.

You can restrict the use of these ports to the CA Top Secret Adapter. To protectthese ports with the CA Top Secret protection, define the profiles in the CA TopSecret SERVAUTH resource class. For more information, see the z/OSCommunications Server, IP Configuration Guide.


Chapter 2. Preparation for installing the CA Top SecretAdapter

Installing and configuring the adapter involves several steps that you mustcomplete in an appropriate sequence.

Review the roadmaps before you begin the installation process.

Preinstallation roadmapYou must prepare the environment before you can install the adapter.

Table 1. Preinstallation roadmap

Task For more information

Obtain the installation software. Download the software from the IBMPassport Advantage® Web site. See“Software download” on page 6.

Verify that your environment meets thesoftware and hardware requirements for theadapter.

See “Prerequisites.”

Installation roadmapYou must complete the necessary steps to install the adapter, including completingpost-installation configuration tasks and verifying the installation.

Table 2. Installation roadmap

Task For more information

Install and configure the adapter. See Chapter 3, “Installation andconfiguration of the CA Top Secret Adapter,”on page 7.

Import the adapter profile. See “Importing the adapter profile into theIBM Security Identity Manager server” onpage 17.

Verify the profile installation. See “Verification of the adapter profileinstallation” on page 17.

Create a service. See “Creating a CA Top Secret Adapterservice” on page 18.

Configure the adapter. See “Adapter configuration for IBM SecurityIdentity Manager” on page 21.

Customize the adapter. See “Customization of the CA Top SecretAdapter” on page 56.

PrerequisitesVerify that your environment meets all the prerequisites before installing theadapter.


Table 3 identifies hardware, software, and authorization prerequisites for installingthe adapter.

Table 3. Prerequisites to install the adapter

Operating System v z/OSversion 1.11

v z/OS version 1.12

v z/OS version 1.13

Network ConnectivityTCP/IP network

Server CommunicationCommunication must be tested with alow-level communications ping from theIBM Security Identity Manager server to theMVS Server. When you do so,troubleshooting becomes easier if youencounter installation problems.

IBM Security Identity Manager server Version 51

Required authorityTo complete the adapter installationprocedure, you must have systemadministrator authority.

Organizations with multiple CA Top Secret databases must have the adapterinstalled on a z/OS host that manages the database. You can manage a single CATop Secret database with a single instance of the CA Top Secret Adapter.

Note: Support for Sysplex failover is not implemented. When the participatingimage of the Sysplex running the adapter becomes inoperative, you can restart thefailed z/OS image, then restart the adapter. You can also pre- configure alternateinstance of the adapter for use on another image. You must already have this typeof environment set up and the necessary resources available. The related serviceinstance on the IBM Security Identity Manager server might require updates if thealternate image is known through a different IP address.

Software downloadDownload the software through your account at the IBM Passport Advantagewebsite.

Go to IBM Passport Advantage.

See the IBM Security Identity Manager Download Document for instructions.

Note:

You can also obtain additional adapter information from IBM Support.


http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

Chapter 3. Installation and configuration of the CA Top SecretAdapter

Install and configure the CA Top Secret Adapter to enable the adapter to work in anon-secure environment.

Installing and configuring the CA Top Secret Adapter involves the following tasks:1. “Uploading the adapter package on z/OS”2. “Installing the ISPF dialog”3. “Running the ISPF dialog” on page 8

Note: The screens displayed in these tasks are examples; the actual screensdisplayed might differ.

Uploading the adapter package on z/OSYou can upload the adapter package on z/OS.

Procedure1. Obtain the software. See “Software download” on page 6.2. Extract the installation package on your local workstation and ensure that a file

named ISIMTSS.UPLOAD.XMI exists. The file is in the z/OS Time Sharing Option(TSO) TRANSMIT/RECEIVE format.

3. On the z/OS operating system, use the TSO to allocate a sequentialISIMTSS.UPLOAD.XMI file with the following parameters:v RECFM=FBv LRECL=80v 400 MB of space

4. Upload the extracted ISIMTSS.UPLOAD.XMI file with a Binary transfer method,such as FTP or 3270 file transfer (IND$FILE).

5. Receive the uploaded file with the TSO RECEIVE command:RECEIVE INDA(ISIMTSS.UPLOAD.XMI)

6. Press Enter to create a Partitioned Data Set (PDS) file named,userid.ISIMTSS.UPLOAD, where, userid is your TSO User ID.

Installing the ISPF dialogInstall the ISPF dialog to install and configure the CA Top Secret Adapter.

Before you begin

Note: This dialog requires a model 3 or model 4 3270 display.

Procedure1. Log on to a z/OS operating system.2. From ISPF 6 option, run the INSTALL1 exec:

EXEC 'userid.ISIMTSS.UPLOAD(INSTALL1)’


where userid is your TSO User ID.3. Specify a high-level qualifier (hlq) for the data sets that the INSTALL1 exec

creates. When you do not specify a high-level qualifier, the exec uses your TSOUser ID as the high-level qualifier. Specify another hlq to use the ISPF dialog inthe future.

4. Enter BATCH or ONLINE (not case-sensitive) to specify whether to create a batchjob stream or complete the file extraction online. If you enter BATCH, you mustmodify the generated INSTALL2 and submit it.

Results

When you run the exec, the exec creates the listed hlq data sets.

Table 4. ISPF dialog data sets

High-level qualifier Library

hlq.SAGTCENU CLIST/EXEC library

hlq.SAGTMENU ISPF message library

hlq.SAGTPENU ISPF panel library

hlq.SAGTSENU ISPF skeleton library

Note: The AGTCCFG exec allocates the libraries.

Running the ISPF dialogRun the ISPF dialog to customize the adapter for run time execution.

About this task

The dialog presents the default values for the parameters, however, you can setyour own values. The ISPF dialog creates the Job Control Language (JCL) jobstreams with the installation parameters that you have selected. The JCL jobstreams are required for adapter installation. Before you perform this task, youmust install the ISPF dialog.

To run the ISPF dialog, perform the following steps:

Procedure1. Log on to TSO on the z/OS operating system.2. From ISPF 6 option, run the following command to start the ISPF dialog:

EXEC 'hlq.SAGTCENU(AGTCCFG)’

The License page is displayed.3. Press Enter to display this screen.


------------------- ISIM CA-TopSecret Adapter Customization -----------Option ===> Location: 1

IBM Security Identity Manager CA-Top Secret Adapter

Initial Customization

1 Initial CustomizationIf this is a new installation, select this option.

2 Customize to support user-defined ACID fieldsIf you have user-defined fields in the FDT, select this option.

X Exit

Note: As you run the dialog, keep in mind the following considerations:v You can return to the previous menu at any time by pressing F3 or END on

the Menu selection screen.v If you press F3 on a data entry screen, the values that you entered are not

saved.v When you fill the data entry screen and if it is validated without errors, the

software returns to the previous screen.4. Select Initial Customization to display the Initial Customization page that

lists the high-level tasks that you must perform.

------------------- ISIM CA-TopSecret Adapter Customization -------------------Option ===> Location: 1-> 1

Initial Installation

1 Load Default or Saved Variables.You must load either the default variables, or your previouslysaved variables prior to defining or altering.

2 Display / Define / Alter Variables.Select or change specifications for this server or node.

3 Generate Job Streams.You must have performed choices 1 and 2 before performingthis choice.

4 Save All Variables.Save variable changes to an MVS data set.

5 View instructions for job execution and further tailoring.This displays customized instructions, based on your inputs.

5. Select Load Default or Saved Variables and specify the fully qualified nameof the data set that includes previously saved variables. If none exists, leavethe fields blank to load the default variables.

------------------- ISIM CA-TopSecret Adapter Customization -------------------Option ===> Location: 1->1-> 1

Load Variables

The IBM supplied defaults are in IBMUSER.ISIMTSS.SAGTCENU(AGTCDFLT)If you remove the name specified below, the defaults will be loaded.

To load previously saved variables, specify the fully qualifieddata set name without quotes.

===>

Chapter 3. Installation and configuration of the CA Top Secret Adapter 9

6. Press PF3 (Cancel) or Enter after final input (Accept) to return to the InitialInstallation panel.

7. Select Display / Define / Alter Variables.

------------------- ISIM CA-TopSecret Adapter Customization -------------------Option ===> Location: 1->1-> 2

Specify or Alter variables for this configuration.

1 Disk location paramaters.Define / alter data set and Unix System Services locations.

2 Adapter specific parameters.Define / alter ISIM server to adapter runtime parameters.

3 VTAM and APPC/MVS parametersDefine / alter VTAM and APPC/MVS specifics.

4 APPC/MVS customization/configurationDefine and or create APPC/MVS environment.

** Indicates option has been visited during this session.

Select an option, or press F3 to return to main menu selection.

a. Select Disk location parameters to define or alter data set and UNIXSystem Services (USS) locations.

------------------- ISIM CA-TopSecret Adapter Customization -------------------Option ===>

Input Data Sets

Fully qualified data set name of the UPLOAD data set.===> IBMUSER.ISIMTSS.UPLOAD

Enter data sets names, volume ID, Storage Class and z/OS Unix directories.

USS Adapter read-only home===> /usr/lpp/isimcatss

USS Adapter read/write home===> /var/ibm/isimcatss

Storage Class ===> STORCLASand/or

Disk Volume ID ===> DSKVOL

Fully qualified data set name of Adapter Load Library===> IBMUSER.ISIMTSS.LOAD

Fully qualified data set name of Adapter EXEC Library===> IBMUSER.ISIMTSS.EXEC

Fully qualified data set name of the UPLOAD data setSpecifies the name of the data set that you have received earlier.For example, IBMUSER.ISIMTSS.UPLOAD.XMI.

Unix System Services (USS) Adapter read-only homeSpecifies the location where the adapter USS binaries are stored.The adapter installer creates the directories and the subordinatedirectories later.

USS Adapter read/write homeSpecifies the location where the adapter registry file, certificates,and log files are written. The adapter installer creates thedirectories and the subordinate directories later.


Note: The read-only home and the read/write home must specifydifferent locations. If they are the same location, the installationmight fail.

Storage classSpecifies the storage class for the Load and EXEC libraries.

DASD (Disk) volume IDSpecifies the Disk ID for the Load and EXEC libraries.

Fully qualified data set name of Adapter Load Library and Fullyqualified data set name of Adapter EXEC Library

Specify the fully qualified data set name for the Load and EXEClibraries.

b. Press PF3 (Cancel) or Enter after final input (Accept) to return to theSpecify or Alter variables for this configuration panel.

c. Select Adapter specific parameters to define or alter the IBM SecurityIdentity Manager or adapter run time parameters.


Adapter specific parameters

Name of adapter instance ===> CATSSAGENT

Name of Started Task JCL procedure name ===> CATSAGT

IP Communications Port Number ===> 45580Note: The adapter will always require access to ports 44970 through 44994.

These ports are implicitly reserved.

Adapter authentication ID (internal) ===> agent

Adapter authentication password (internal) ===> agent

PDU backlog limit ===> 1000

Do you want passwords set as expired? ===> TRUE (True, False)

Do you use SYS1.BRODCAST in the environment? ===> TRUE (True, False)

CA Top Secret SCA ACID for ISIM adapter ===> CATSAGT

CA Top Secret Default Group ACID for adapter ===> STCUSS

OMVS UID to be assigned to ACID (non-zero) ===> 123456789

Name of adapter instanceSpecifies the unique name assigned to the adapter instance. Whenmore than one adapter is active in the same Logical Partition(LPAR), use a different adapter name for each instance.

Name of the Started Task JCL procedure nameSpecifies the name of the JCL member that is created. This name isalso used to create an entry in the STC Top Secret table.

IP Communications Port NumberSpecifies the default IP Communications Port Number which is45580. When more than one adapter is active in the same LPAR,use a different port number for each adapter instance.

Adapter authentication ID and Adapter authentication passwordSpecifies the adapter authentication ID and password that arestored in the adapter registry. The ID and password are used to


authenticate the IBM Security Identity Manager server to the CATop Secret Adapter. These two parameters must also be specifiedon the adapter service form that is created on IBM SecurityIdentity Manager.

PDU backlog limitSpecifies the number of entries that can be in queue for sending tothe IBM Security Identity Manager server. The higher the number,the greater the throughput on reconciliations; however, this alsoresults in higher storage utilization.

Do you want passwords set as expiredSpecifies whether the passwords must be set as expired ornon-expired. The default value is set to TRUE; however, you mightchange it to FALSE if you want all the passwords set asnon-expired.

Do you use SYS1.BRODCAST in the environmentSpecifies if your TSO environment uses the SYS1.BRODCAST dataset for TSO logon messages and notifications. The default value isTRUE.

CA-Top Secret SCA ACID for ISIM adapterSpecifies the CA Top Secret Security Administrator (SCA) ACIDthat the adapter task is assigned to.

CA-Top Secret Default Group ACID for adapterSpecifies a CA Top Secret z/OS UNIX GROUP with a GID. A GID isa UNIX Group ID, which is a unique number assigned to a UNIXgroup name. The adapter operates as a z/OS UNIX process andrequires this information.

OMVS UID to be assigned to ACID (non-zero)Specifies a unique UID number for the SCA ACID. Ensure that youspecify a non-zero number as the UID number.

d. Press PF3 (Cancel) or Enter after final input (Accept) to return to theSpecify or Alter variables for this configuration panel.

e. Select VTAM and APPC/MVS parameters to define VTAM® andAPPC/MVS specifications.



VTAM and APPC/MVS Parameters

VTAM NETID ===> NET1

VTAM Originating Logical Unit ===> ISIMORIG (*)

VTAM Destination Logical Unit ===> ISIMDEST (*)

VTAM Session Key ===> 0123456789ABCDEF

VTAM LOGMODE entry name ===> #INTERSC

Fully qualified data set name of your APPC/MVS transaction data set:===> SYS1.APPCTP

APPC command transaction name ===> ISIMTCMD

APPC reconciliation transaction ===> ISIMTREC

APPC execution class ===> A

APPC Network Qualified Names? ===> FALSE (True or False)

(*) If both LU’s specified are the same, it must reflect the name of theAPPC/MVS defined BASE logical unit.

VTAM NETIDObtain the VTAM NETID from the MVS console by running thefollowing command:"D NET,E,ID=ISTNOP"

The result with the message ID IST075I indicates netid.ISTNOP,where netid is the Network ID required for the adapterconfiguration.

VTAM Originating Logical Unit and VTAM Destination Logical UnitWhen the Originating and Destination Logical Unit (LU) have thesame name, a single LU name is defined to APPC/MVS as theBASE LU. When the Originating and Destination Logical Units(LUs) have different names, the Destination LU must be the BASELU and the Originating LU must be different from the BASE LUname. This requirement is an APPC/MVS restriction.

VTAM Session KeyThe VTAM session key is an 8 byte shared secret key. If oneAPPCLU profile is created, the session key is not required. If twoAPPCLU profiles are created, and a session key is specified, thenthe session keys must match.

Note: In the Top Secret environment, specify session keys that areof 16 hexadecimal characters (0-9, A-F).

VTAM LOGMODE entry nameThe standard VTAM LOGMODE entry name is #INTERSC. Thisname is standard in the VTAM default mode table, ISTINCLM.

Fully qualified data set name of your APPC/MVS transaction data setSpecify the name of an existing or a new APPC/MVS transactionprofile data set name. This data set is a VSAM file.


APPC command transaction name and APPC reconciliation transactionSpecify APPC/MVS transaction names for the adapter APPCtransactions (APPC command transaction and APPC reconciliationtransaction). The following table lists the default APPC transactionnames.

Table 5. APPC transaction names

Transaction Default transaction name

APPC command transaction ISIMTCMD

APPC reconciliation transaction ISIMTREC

APPC execution classThe APPC execution class is a 1 - 8 character class name. Thisname is an Address Space Scheduler (ASCH, a part ofAPPC/MVS) class name defined or to be defined in ASCHPMxx.

APPC Network Qualified NamesThe APPC/MVS network qualified names specify how the TopSecret APPCLU profiles must be defined. The specification inAPPCPMxx for the LUs to be configured indicates whether the LUis enabled to use a network-qualified Partner LU name. For NQN(fully qualified network names) specify TRUE, and for NONQN(non-fully qualified network names), specify FALSE.

Note: The default value in APPCPMxx is NONQN.f. Press PF3 (Cancel) or Enter after final input (Accept) to return to the

Specify or Alter variables for this configuration panel.g. Select APPC/MVS customization/configuration to define or create the

APPC/MVS environment.


APPC/MVS customization/configuration

If the following field is FALSE, the remaining fields are required.

Is APPC currently configured? ===> TRUE (True or False)

CA-Top Secret ACID for APPC/MVS ===> APPC

CA-Top Secret ACID for ASCH ===> ASCH

CA-Top Secret department ACID for APPC/MVS ===> DEPT

SMS STORCLAS for APPCTP data set ===> STORCLASand/orDisk Volume ID for APPCTP data set ===> DSKVOL

Case 1: If APPC/MVS is already configured, then ignore the other fields.Case 2: If APPC/MVS is not configured, then specify values for theremaining parameters that are displayed on the screen.v Specify CA-Top Secret ACID for APPC/MVS and ASCH. You might

specify APPC for APPC/MVS and ASCH for ASCH as shown in thescreen. The APPC/MVS and ASCH ACIDs must be associated with adepartment for started tasks.

v Specify the SMS Storage class or the disk volume, or both to create alocation for the APPC/MVS transaction profile data set.


8. Press PF3 to return to the Initial Installation panel.9. Select Generate Job Streams.

10. This screen displays the default data set names that are generated to store thejob streams and data. You might change the default names on this screen asper requirements of your organization. These data sets are not used at theadapter run time.

------------------- ISIM CA TopSecret Adapter Customization -------------------Option ===>

Generate the job streams

Specify two fully qualified data set names. These data sets will bepopulated with the job streams and their input data elements.Specify the data set names, without quotes. If these data sets do notexist, they will be created.

Data set name for job streams to be stored.===> IBMUSER.ISIMTSS.CNTL

Data set name for data elements required by generated job streams.===> IBMUSER.ISIMTSS.DATA

Enter your installation job statement parameters here:

=> //JOBNAME JOB (ACCTNO,ROOM),’&SYSUID’,CLASS=A,MSGCLASS=X,=> // NOTIFY=&SYSUID=> //*

Specify valid parameters for installation JCL JOB statement and press Enter tocreate job streams (members) and data members. Control returns to the InitialInstallation panel.

11. Select Save All Variables to save all the changes that you made to the dataset.You can use the same data set when you select Load Default or SavedVariables. Specify a data set name to save all your settings for the adapterconfiguration as described in this screen.


Save variables to a data set.

Specify the data set where the variables specified in this session areto be saved. Specify a fully qualified data set name, without quotes.If the data set does not exist, a sequential data set will be created.

===> IBMUSER.ISIMTSS.CONFIG

12. Select View instructions for job execution and further tailoring. To view theadapter settings and instructions to run the generated job streams, see thehlq.ISIMTSS.CNTL(INSTRUCT) data set. Follow the instructions specified in thehlq.ISIMTSS.CNTL(INSTRUCT) data set to complete the configuration.

Results

After completing the steps for running the ISPF dialog, the adapter is configured ina non-secure mode. To configure the adapter in a secure mode, you must performadditional steps. For example, enabling the Secure Socket Layer (SSL), creating andimporting the certificate in the adapter registry, and so on. For more information,see “Configuration of SSL authentication for the adapter” on page 68.


Starting and stopping the adapterVarious installation and configuration task might require the adapter to berestarted to apply the changes. Use this task to start or restart the adapter.

Before you begin

Start the adapter as a started task, where the started task JCL is customized andinstalled in a system procedure library.

About this task

ITIAGNT is the name of the JCL procedure that represents the adapter.

The ITIAGNT task listens on two IP ports. These two ports are used for:v Communication between the IBM Security Identity Manager server and the

adapterv agentCfg utility

Note: You can define _BPX_SHAREAS=YES in the /etc/profile. This setting enables theadapter to run in a single address space, instead of multiple address spaces. Newerreleases of z/OS create two address spaces with this environment variable set. See“z/OS UNIX System Services considerations” on page 21 for more information.

Procedure1. To start the adapter, run the this MVS console start command:

START ITIAGNT

2. To stop the adapter, perform one of the following steps:v If the USS environment is running with _BPX_SHAREAS=YES, then run one

of the following MVS stop command to stop the adapter:STOP ITIAGNT

P ITIAGNT

v In the new releases of z/OS, if the USS environment is running with the_BPX_SHAREAS=YES setting, an additional address space is created. In thiscase, run the following command to stop the adapter:P ITIAGNT1

v If an MVS STOP command does not stop the adapter, run the following MVSCANCEL command to stop the adapter:CANCEL ITIAGNT

Configuration of communicationYou must complete several tasks that configure the IBM Security Identity Managerserver to communicate with the adapter.1. “Importing the adapter profile into the IBM Security Identity Manager server”

on page 172. “Verification of the adapter profile installation” on page 173. “Creating a CA Top Secret Adapter service” on page 18


Importing the adapter profile into the IBM Security IdentityManager server

An adapter profile defines the types of resources that the IBM Security IdentityManager server can manage. Use the profile to create an adapter service on IBMSecurity Identity Manager and establish communication with the adapter.

Before you begin

Before you begin to import the adapter profile, verify that the following conditionsare met:v The IBM Security Identity Manager server is installed and running.v You have root or Administrator authority on the IBM Security Identity Manager

server.

About this task

Before you can add an adapter as a service to the IBM Security Identity Managerserver, the server must have an adapter profile to recognize the adapter as aservice. The files that are packaged with the adapter include the adapter JAR file,CATSSProfile.jar. You can import the adapter profile as a service profile on theserver with the Import feature of IBM Security Identity Manager.

The CATSSProfile.jar file includes all the files that are required to define theadapter schema, account form, service form, and profile properties. You can extractthe files from the JAR file to modify the necessary files and package the JAR filewith the updated files.

To import the adapter profile, perform the following steps:

Procedure1. Log on to the IBM Security Identity Manager server. Use an account that has

the authority to perform administrative tasks.2. In the My Work pane, expand Configure System and click Manage Service

Types.3. On the Manage Service Types page, click Import to display the Import Service

Types page4. Specify the location of the CATSSProfile.jar file in the Service Definition File

field. The CATSSProfile.jar is a component of the adapter installation package.See “Software download” on page 6. Perform one of the following tasks:a. Type the complete location of where the file is stored.b. Use Browse to navigate to the file.

5. Click OK.

Verification of the adapter profile installationAfter you install the adapter profile, verify that the installation was successful.

An unsuccessful installation:v Might cause the adapter to function incorrectly.v Prevents you from creating a service with the adapter profile.


To verify that the adapter profile is successfully installed, create a service with theadapter profile. For more information about creating a service, see “Creating a CATop Secret Adapter service.”

If you are unable to create a service using the adapter profile or open an accounton the service, the adapter profile is not installed correctly. You must import theadapter profile again.

Creating a CA Top Secret Adapter serviceAfter the adapter profile is imported on IBM Security Identity Manager, you mustcreate a service so that IBM Security Identity Manager can communicate with theadapter.

Before you begin

Ensure that you imported the CA Top Secret Adapter profile into the IBM SecurityIdentity Manager server.

About this task

To create or change a service, you must use the service form to provideinformation for the service. Service forms might vary depending on the adapter.

To create a service, perform the following steps:

Procedure1. Log on to the IBM Security Identity Manager server by using an account that

has the authority to perform administrative tasks.2. In the My Work pane, click Manage Services and click Create.3. On the Select the Type of Service page, select CA Top Secret Profile.4. Click Next to display the adapter service form.5. Complete the following fields on the service form:

On the General Information tab:

Service NameSpecify a name that identifies the CA Top Secret Adapterservice on the IBM Security Identity Manager server.

Service DescriptionOptional: Specify a description that identifies the service foryour environment. You can specify additional informationabout the service instance.

URL Specify the location and port number of the adapter. The portnumber is defined during installation, and can be viewed andmodified in the protocol configuration by using the agentCfgutility. For more information about protocol configurationsettings, see “Changing protocol configuration settings” onpage 26.

Note: If you specify https as part of the URL, the adapter mustbe configured to use SSL authentication. If the adapter is notconfigured to use SSL authentication, specify http for the URL.For more information, see “Configuration of SSL authenticationfor the adapter” on page 68.


User IDSpecify the name that was defined at installation time as theAdapter authentication ID. This name is stored in the registry.The default value is agent.

PasswordSpecify the password that was defined at installation time asthe Adapter authentication ID. The default value is agent.

CA Top Secret ID under which requests will be processedOptional: Specify a CA Top Secret ACID other than the one thatis used by the adapter. This ACID can be a Control ACID withauthority over a subset of ACIDs in the CA Top Secretdatabase.

OwnerOptional: Specify the service owner, if any.

Service PrerequisiteOptional: Specify an existing IBM Security Identity Managerservice.

On the Status and information tabThis page contains read only information about the adapter andmanaged resource. These fields are examples. The actual fields varydepending on the type of adapter and how the service form isconfigured. The adapter must be running to obtain the information.Click Test Connection to populate the fields.

Last status update: DateSpecifies the most recent date when the Status and informationtab was updated.

Last status update: TimeSpecifies the most recent time of the date when the Status andinformation tab was updated.

Managed resource statusSpecifies the status of the managed resource that the adapter isconnected to.

Adapter versionSpecifies the version of the adapter that the IBM SecurityIdentity Manager service uses to provision request to themanaged resource.

Profile versionSpecifies the version of the profile that is installed in the IBMSecurity Identity Manager server.

ADK versionSpecifies the version of the ADK that the adapter uses.

Installation platformSpecifies summary information about the operating systemwhere the adapter is installed.

Adapter accountSpecifies the account that running the adapter binary file.

Adapter up time: DateSpecifies the date when the adapter started.


Adapter up time: TimeSpecifies the time of the date when the adapter started.

Adapter memory usageSpecifies the memory usage for running the adapter.

If the connection fails, follow the instructions in the error message. Alsov Verify the adapter log to ensure that the IBM Security Identity

Manager test request was successfully sent to the adapter.v Verify the adapter configuration information.v Verify IBM Security Identity Manager service parameters for the

adapter profile. For example, verify the work station name or the IPaddress of the managed resource and the port.

6. Click Finish.


Chapter 4. First steps after installation

After you install the adapter, you must perform several other tasks. The tasksinclude configuring the adapter, setting up SSL, installing the language pack, andverifying the adapter works correctly.

Adapter configuration for IBM Security Identity ManagerUse the adapter configuration tool, agentCfg, to view or modify the adapterparameters.

All the changes that you make to the parameters with the agentCfg take effectimmediately. You can also use agentCfg to view or modify configuration settingsfrom a remote workstation. For more information about specific procedures to useadditional arguments, see Table 18 on page 55 in “Accessing help and additionaloptions” on page 54.

Note: The screens displayed in this section are examples, the actual screensdisplayed might differ.

z/OS UNIX System Services considerationsUNIX System Service creates a task for each child process. If you define_BPX_SHAREAS=YES in the /etc/profile, the adapter runs in a single address space,instead of multiple address spaces.

By defining this setting, you can use the same name to start and stop a task.Newer releases of z/OS create two address spaces with this environment variableset, for example ISIAGNT and ISIAGNT1. In this case, the task must be stopped byissuing the stop command to the task ISIAGNT1. This setting affects other areas ofUNIX System Services. See the z/OS UNIX System Services Planning, documentGA22-7800.

You must correctly define the time zone environment variable (TZ) in/etc/profile for your time zone. The messages in the adapter log then reflect thecorrect local time. See z/OS UNIX System Services Planning, document GA22-7800,for more details about this setting.

Configuration of CA Top Secret accessDetermine your needs and configure how the adapter accesses CA Top Secretinformation. The installation process configures most of the definitions that arenecessary for the adapter to function. For more information, see the job streamsthat are generated during the installation process.

CA Top Secret ACIDThe adapter must run under a valid CA Top Secret Accessor ID (ACID), withaccess to the STC, OPENMVS, APPC, and BATCH facilities.

The ACID must have a valid UID and the group of this user must have a validGID. Unless surrogate ACIDs are being used, the adapter must have the authorityto change, create, delete, and list the required ACIDs. For example, for access to allACIDs define a SCA type ACID with the required administrative authority. To


perform reconciliation the ACID must have the data authority level set to ALL andPASSWORD. The adapter ACID must also be defined to the STC record.

Note: The adapter task should not run as a Master Security Control ACID(MSCA). Therefore, SCA ACIDs cannot be created by the CA Top Secret Adapter.

Example

These commands are an example of how to define the CA Top Secret Adapter tomanage all accounts on this CA Top Secret database:/* The ISIM CA Top Secret Adapter adapter requires an SCA user id, with *//* OMVS attributes, and administrative authority. */TSS CREATE(ITIAGNT) NAME(’ISIM TOP-SECRET ADAPTER’) +

PASSWORD(password,0) FACILITY(STC,OPENMVS,APPC,BATCH) +TYPE(SCA)

TSS ADD(ITIAGNT) CONSOLETSS ADD(ITIAGNT) OMVSPGM(’/bin/sh’)TSS ADD(ITIAGNT) HOME(’/u/isim/catss/readwrite’)TSS ADD(ITIAGNT) UID(1010)TSS ADD(ITIAGNT) DFLTGRP(OMVSGRP) GROUP(OMVSGRP)TSS ADMIN(ITIAGNT) ACID(ALL)TSS ADMIN(ITIAGNT) DATA(ALL,PASSWORD)TSS ADMIN(ITIAGNT) MISC1(ALL)TSS ADMIN(ITIAGNT) MISC2(ALL)TSS ADMIN(ITIAGNT) MISC3(ALL)TSS ADMIN(ITIAGNT) MISC4(ALL)TSS ADMIN(ITIAGNT) MISC5(ALL)TSS ADMIN(ITIAGNT) MISC7(ALL)TSS ADMIN(ITIAGNT) MISC8(ALL)TSS ADMIN(ITIAGNT) MISC9(ALL)TSS ADMIN(ITIAGNT) FACILITY(ALL)TSS LIST(ITIAGNT) DATA(ALL)/* The adapter also requires a STARTED ID, with OMVS attributes */TSS ADD(STC) PROCNAME(ITIAGNT) ACID(ITIAGNT)/* Refresh the OMVS tables */TSS MODIFY(OMVSTABS)

ACID propagationThe adapter running in z/OS UNIX System Services must be able to propagate theACID it is running as, to the APPC/MVS environment.

This task is accomplished by defining one or more entries in the APPCLU record.You can configure the definitions in either of two ways.

Single APPC/MVS base logical unit

By default, the APPC/MVS baselu is utilized by the CA Top Secret Adapter, bothfor the originating and destination logical units. If this method is utilized, only onelink in the APPCLU record must be defined. The form of the CA Top Secretcommand to define the link can take two forms.v If the APPC/MVS LUADD statement takes the default, or has specified

NONQN, then this command takes the following form:TSS ADD(APPCLU) LINKID(netid.baselu.baselu) +

CONVSEC(ALREADYV) INTERVAL(0) +SESSKEY(0123456789ABCDEF)

v If the APPC/MVS LUADD statement has specified NQN, then this commandtakes the following form:TSS ADD(APPCLU) LINKID(netid.baselu.netid.baselu) +



In the preceding examples, netid is the VTAM NETID (Network ID) selected foruse for VTAM in your environment. The baselu specifies the VTAM logical unitname for the BASELU defined to APPC/MVS. The 0123456789ABCDEF in theSESSKEY field is a session key, or password, used for security when theAPPC/MVS sessions are initiated.After this profile has been defined, an MVS console command must be issued toVTAM to inform VTAM of this profile being defined or updated.F VTAM,PROFILES,ID=baselu

Use of two APPC/MVS logical units

Your installation might use two separate logical units, and not use the APPC/MVSBASELU definition. If this method is used, two links in the APPCLU record mustbe defined. The CA Top Secret commands to define these links can take two forms:v If the APPC/MVS LUADD statements have defaulted or specified NONQN,

then the commands takes the following form. (This example implies thatNONQN is used for both logical units.)TSS ADD(APPCLU) LINKID(netid.origin.dest) +


TSS ADD(APPCLU) LINKID(netid.dest.origin) +CONVSEC(ALREADYV) INTERVAL(0) +SESSKEY(0123456789ABCDEF)

v If the APPC/MVS LUADD statements have specified NQN, then thesecommands take the following form. (This example implies that NQN is specifiedfor both logical units.)TSS ADD(APPCLU) LINKID(netid.origin.netid.dest) +


TSS ADD(APPCLU) LINKID(netid.dest.netid.origin) +CONVSEC(ALREADYV) INTERVAL(0) +SESSKEY(0123456789ABCDEF)

In the preceding examples, netid is the VTAM Network ID (NETID) selected foruse for VTAM in your environment. The origin and dest specify the VTAM logicalunit names used as the originating and destination logical units defined toAPPC/MVS. The 0123456789ABCDEF in the SESSKEY field is a session key, orpassword, utilized for security when the APPC/MVS sessions are initiated.

After these links have been defined, two MVS console commands must be issuedto inform VTAM of the update:F VTAM,PROFILES,ID=originF VTAM,PROFILES,ID=dest

Surrogate userA surrogate user is a user who has the authority to perform tasks on behalf ofanother user, by using the other users level of authority. For the CA Top SecretAdapter, the adapter task ACID runs as a surrogate user on behalf of the ACIDdefined in the ITIM service form.

The authorization of the adapter ACID as a surrogate user is necessary only if:v The installation uses 'business unit support'.v A single instance of the adapter supports a single CA Top Secret database.v The IBM Security Identity Manager has multiple service instances, each

representing a different business unit within the organization.

Chapter 4. First steps after installation 23

Note: If a single IBM Security Identity Manager service instance supports all theACIDs in the CA Top Secret database, surrogate user authority is not needed.

For the adapter to perform requests on behalf of another user, you must permitauthority for the SURROGAT resource.

If the adapter ACID is ITIAGNT, and the ACID defined on the ITIM service formis UNIT1, then the following commands defines the SURROGAT resource.TSS ADD(dept) SURROGAT(ATBALLC.)TSS PERMIT(ITIAGNT) SURROGAT(ATBALLC.UNIT1) ACCESS(READ)

Starting the adapter configuration toolStart the adapter configuration tool, agentCfg, for CA Top Secret Adapterparameters.

Procedure1. Log on to the TSO on the z/OS operating system that hosts the adapter.2. From ISPF option 6, run the following command and press Enter to enter the

USS shell environment:omvs

Optional: You can also enter the USS shell environment through a telnetsession.

3. In the command prompt, change to the /bin subdirectory of the adapter in theread/write directory. If the adapter is installed in the default location for theread/write directory, run the following command.

Note: There is a /bin subdirectory in the adapter read-only directory too. Theread/write /bin subdirectory contains scripts that set up environmentvariables, then call the actual executables that reside in the read-only /bindirectory. You must start the adapter tools by running the scripts in theread/write directory, otherwise errors might occur.# cd /var/ibm/isim/bin

4. Run the following command:agentCfg -agent adapter_name

The adapter name was specified when you installed the adapter. You can findthe names of the active adapters by running the agentCfg as:agentCfg -list

5. At Enter configuration key for Agent adapter_name, type the configurationkey for the adapter.The default configuration key is agent. To prevent unauthorized access to theconfiguration of the adapter, you must modify the configuration key after theadapter installation completes. For more information, see “Changing protocolconfiguration settings” on page 26.The Agent Main Configuration Menu is displayed.


adapter_name 6.0 Agent Main Configuration Menu-------------------------------------------A. Configuration Settings.B. Protocol Configuration.C. Event Notification.D. Change Configuration Key.E. Activity Logging.F. Registry Settings.G. Advanced Settings.H. Statistics.I. Codepage Support.

X. Done

Select menu option:

From the Agent Main Configuration Menu screen, you can configure theprotocol, view statistics, and modify settings, including configuration, registry,and advanced settings.

Table 6. Options for the main configuration menu

Option Configuration task For more information

A Viewing configurationsettings

See “Viewing configuration settings.”

B Changing protocolconfiguration settings

See “Changing protocol configurationsettings” on page 26.

C Configuring eventnotification

See “Configuring event notification” onpage 29.

D Changing the configurationkey

See “Changing the configuration key” onpage 46.

E Changing activity loggingsettings

See “Changing activity logging settings”on page 47.

F Changing registry settings See “Modifying registry settings” on page49.

G Changing advanced settings See “Changing advanced settings” onpage 50.

H Viewing statistics See “Viewing statistics” on page 51.

I Changing code page settings See “Code page settings” on page 52.

Viewing configuration settingsYou might want to view the adapter configuration settings for information aboutthe adapter version, ADK version, adapter log file name, and other information.

About this task

The following procedure describes how to view the adapter configuration settings:

Procedure1. Access the Agent Main configuration Menu. See “Starting the adapter

configuration tool” on page 24.2. Type A to display the configuration settings for the adapter.


Configuration Settings-------------------------------------------Name : adapter_nameVersion : 6.0ADK Version : 6.0ERM Version : 6.0Adapter Events : FALSELicense : NONEAsynchronous ADD Requests : FALSE (Max.Threads:3)Asynchronous MOD Requests : FALSE (Max.Threads:3)Asynchronous DEL Requests : FALSE (Max.Threads:3)Asynchronous SEA Requests : FALSE (Max.Threads:3)Available Protocols : DAMLConfigured Protocols : DAMLLogging Enabled : TRUELogging Directory : /var/ibm/isim/isimcatss/logLog File Name : adapter_name.logMax. log files : 3Max.log file size (Mbytes) : 1Debug Logging Enabled : TRUEDetail Logging Enabled : FALSEThread Logging Enabled : FALSE

3. Press any key to return to the Main Menu.

Changing protocol configuration settingsThe adapter uses the DAML protocol to communicate with the IBM SecurityIdentity Manager server.

About this task

By default, when the adapter is installed, the DAML protocol is configured for anonsecure environment. To configure a secure environment, use Secure Shell Layer(SSL) and install a certificate. For more information, see “Installing the certificate”on page 78.

The DAML protocol is the only supported protocol that you can use. Do not addor remove a protocol.

To configure the DAML protocol for the adapter, perform the following steps:

Procedure1. Access the Agent Main Configuration Menu, if you have not already done so.

See “Starting the adapter configuration tool” on page 24.2. Type B. The DAML protocol is configured and available by default for the

adapter.

Agent Protocol Configuration Menu-----------------------------------Available Protocols: DAMLConfigured Protocols: DAMLA. Add Protocol.B. Remove Protocol.C. Configure Protocol.

X. Done

Select menu option

3. At the Agent Protocol Configuration Menu, type C to display the ConfigureProtocol Menu.


4. Type A to display the Protocol Properties Menu for the configured protocol withprotocol properties. The following screen is an example of the DAML protocolproperties.

DAML Protocol Properties--------------------------------------------------------------------A. USERNAME ****** ;Authorized user name.B. PASSWORD ****** ;Authorized user password.C. MAX_CONNECTIONS 100 ;Max Connections.D. PORTNUMBER 45580 ;Protocol Server port number.E. USE_SSL FALSE ;Use SSL secure connection.F. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.H. HOSTADDR ANY;Listen on address (or "ANY")I. VALIDATE_CLIENT_CE FALSE ;Require client certificate.J. REQUIRE_CERT_REG FALSE ;Require registered certificate.

X. Done

Select menu option:

5. Follow these steps to change a protocol value:v Type the letter of the menu option for the protocol property to configure.

Table 7 describes each property.v Take one of the following actions:

– Change the property value and press Enter to display the ProtocolProperties Menu with the new value.

– If you do not want to change the value, press Enter.

Table 7. Options for the DAML protocol menu

Option Configuration task

A Displays the following prompt:

Modify Property ’USERNAME’:

Type a User ID, for example, admin.

The IBM Security Identity Manager server uses this value to connect tothe adapter.

B Displays the following prompt

Modify Property ’PASSWORD’:

Type a password, for example, admin.

The IBM Security Identity Manager server uses this value to connect tothe adapter.

C Displays the following prompt:

Modify Property ’MAX_CONNECTIONS’:

Enter the maximum number of concurrent open connections that theadapter supports.

The default value is 100.Note: This setting is sufficient and does not require adjustment.


Table 7. Options for the DAML protocol menu (continued)


D Displays the following prompt:

Modify Property ’PORTNUMBER’:

Type a different port number.

The IBM Security Identity Manager server uses the port number toconnect to the adapter. The default port number is 45580. For moreinformation, see “Adapter interactions with the IBM Security IdentityManager server” on page 3.

E Displays the following prompt:

Modify Property ’USE_SSL’:

TRUE specifies to use a secure SSL connection to connect the adapter. Ifyou set USE_SSL to TRUE, you must install a certificate. For moreinformation, see “Installing the certificate” on page 78.

FALSE, the default value, specifies not to use a secure SSL connection.

F Displays the following prompt:

Modify Property ’SRV_NODENAME’:

Type a server name or an IP address of the workstation where you haveinstalled the IBM Security Identity Manager server.

This value is the DNS name or the IP address of the IBM SecurityIdentity Manager server that is used for event notification andasynchronous request processing.Note: If your platform supports Internet Protocol version 6 (IPv6)connections, you can specify an IPv6 server.

G Displays the following prompt:

Modify Property ’SRV_PORTNUMBER’:

Type a different port number to access the IBM Security IdentityManager server.

The adapter uses this port number to connect to the IBM SecurityIdentity Manager server. The default port number is 9443.

H The HOSTADDR option is useful when the system, where the adapter isrunning, has more than one network adapter. You can select which IPaddress the adapter must listen to. The default value is ANY.

I Displays the following prompt:

Modify Property ’VALIDATE_CLIENT_CE’:

Specify TRUE for the IBM Security Identity Manager server to send acertificate when it communicates with the adapter. When you set thisoption to TRUE, you must configure options D through I.

Specify FALSE, the default value, to let the IBM Security IdentityManager server communicate with the adapter without a certificate.Note:

v The property name is VALIDATE_CLIENT_CERT, however, it istruncated by the agentCfg to fit in the screen.

v You must use certTool to install the appropriate CA certificates andoptionally register the IBM Security Identity Manager servercertificate. For more information about using the certTool, see“Managing SSL certificates with the certTool utility” on page 75.


Table 7. Options for the DAML protocol menu (continued)


J Displays the following prompt:

Modify Property ’REQUIRE_CERT_REG’:

This value applies when option I is set to TRUE.

Type TRUE to register the adapter with the client certificate from theIBM Security Identity Manager server before it accepts an SSLconnection.

Type FALSE to verify the client certificate against the list of CAcertificates. The default value is FALSE.

For more information about certificates, see “Configuration of SSLauthentication for the adapter” on page 68.

6. Follow one these steps at the prompt:v Change the property value and press Enter to display the Protocol Properties

Menu with the new value.v If you do not want to change the value, press Enter.

7. Repeat step 5 to configure the other protocol properties.8. At the Protocol Properties Menu, type X to exit.

Configuring event notificationEvent notification detects changes that are made directly on the managed resourceand updates the IBM Security Identity Manager server with the changes.

About this task

You can enable event notification to obtain the updated information from themanaged resource.

Note: Event notification does not replace reconciliations on the IBM SecurityIdentity Manager server.

When you enable event notification, the workstation on which the adapter isinstalled maintains a database of the reconciliation data. The adapter updates thedatabase with the changes that are requested from IBM Security Identity Managerand synchronizes with the server. You can specify an interval for the eventnotification process to compare the database to the data that currently exists on themanaged resource. When the interval elapses, the adapter forwards the differencesbetween the managed resource and the database to IBM Security Identity Managerand updates the local snapshot database.

To enable event notification, ensure that the adapter is deployed on the managedhost and is communicating successfully with IBM Security Identity Manager.Related concepts:“Required information” on page 30To implement event notification, you must specify required information.“Example definition” on page 30This section provides an example definition.


Required informationTo implement event notification, you must specify required information.v Installing IBM Security Identity Manager digital certificate in the adapter's

registry if you use communications between IBM Security Identity Manager andthe adapter on the managed resource.

v Knowing the IP address for the IBM Security Identity Manager hosting platform.v Knowing the IP port for the IBM Security Identity Manager hosting platform,

which is either:– The SSL port, if you use SSL communications– The non-SSL port, if you do not use SSL

These are the port numbers for the Web application server on IBM SecurityIdentity Manager. The default WebSphere®, port numbers are 9443 (SSL) and9080 (non-SSL).

v Knowing and defining the pseudo-Distinguished Name (DN) for the IBM SecurityIdentity Manager service in an event notification context in the adapter's registry.The DN is not a typical LDAP DN and is unique for IBM Security IdentityManager. The DN identifies a specific service instance defined on the IBMSecurity Identity Manager server.

v Optionally, there are credentials passed to an adapter to identify the serviceinstance to the managed resource adapter. For example, a Windows Basepointthat you specify on the adapter service form. The adapter connects to themanaged resource by using these credentials.

Example definitionThis section provides an example definition.

It includes the following information:v “Assumptions for the example”v “Protocol properties”v “Installing the CA certificate in the adapter” on page 32v “Adding an event notification context” on page 36v “Configuring the target DN for event notification contexts” on page 45v “Attributes for search” on page 38v “Pseudo-distinguished name values” on page 39

Assumptions for the exampleThis example makes several assumptions.v SSL for communication. Because SSL is used, the adapter receives a digital

certificate from IBM Security Identity Manager. The certificate is self-signed andmust be installed in the adapter registry as a Certificate Authority (CA)certificate.

v 9.38.214.54 as the host IP address where IBM Security Identity Manager runs.v 9443 as the host IP port for the web application server SSL port.v CA Top Secret as the name of the adapter context.v A pseudo DN as a target notification event for the IBM Security Identity

Manager services, which is erservicename=MVS CA Top Secret 4.5.1016 ENTEST,o=Acme Inc, ou=Acme, dc=my_suffix

Protocol propertiesYou must set the protocol properties.


SSL is often used. All the properties are defined under the DAML protocolenvironment.

In the following examples, the IBM Security Identity Manager host IP and portaddresses are set through the agentCfg utility.

ISIMAGNT 6.0.1000 Agent Main Configuration Menu-------------------------------------------

A. Configuration Settings.B. Protocol Configuration.C. Event Notification.D. Change Configuration Key.E. Activity Logging.F. Registry Settings.G. Advanced Settings.H. HostaddrI. Statistics.J. Codepage Support.

X. Done

Select menu option:b

Agent Protocol Configuration Menu--------------------------------------Available Protocols : DAMLConfigured Protocols: DAML

A. Add Protocol.B. Remove Protocol.C. Configure Protocol.

X. Done

Select menu option:cConfigure Protocol Menu------------------------------

A. DAMLX. Done

Select menu option:a

DAML Protocol Properties------------------------------------

A. USERNAME ****** ;Authorized user name.B. PASSWORD ****** ;Authorized user password.C. MAX_CONNECTIONS 100 ;Max Connections.D. PORTNUMBER 45581 ;Protocol Server port number.E. USE_SSL TRUE ;Use SSL secure connectionF. SRV_NODENAME ----- ;Event Notif. Server name.G. SRV_PORTNUMBER 7003 ;Event Notif. Server port number.H. HOSTADDR ANY ;Listen on address (or "ANY")I. VALIDATE_CLIENT_CE FALSE ;Require client certificate.J. REQUIRE_CERT_REG FALSE ;Require registered certificate.

X. Done


Select menu option:f

Modify Property ’SRV_NODENAME’: 9.38.215.20


A. USERNAME ****** ;Authorized user name.B. PASSWORD ****** ;Authorized user password.C. MAX_CONNECTIONS 100 ;Max Connections.D. PORTNUMBER 45581 ;Protocol Server port number.E. USE_SSL TRUE ;Use SSL secure connectionF. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.H. HOSTADDR ANY ;Listen on address (or "ANY")I. VALIDATE_CLIENT_CE FALSE ;Require client certificate.J. REQUIRE_CERT_REG FALSE ;Require registered certificate.

X. Done

Select menu option:g

Modify Property ’SRV_PORTNUMBER’: 9443


A. USERNAME ****** ;Authorized user name.B. PASSWORD ****** ;Authorized user password.C. MAX_CONNECTIONS 100 ;Max Connections.D. PORTNUMBER 45581 ;Protocol Server port number.E. USE_SSL TRUE ;Use SSL secure connectionF. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name.G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number.H. HOSTADDR ANY ;Listen on address (or "ANY")I. VALIDATE_CLIENT_CE FALSE ;Require client certificate.J. REQUIRE_CERT_REG FALSE ;Require registered certificate.

X. Done

Select menu option:x

Configure Protocol Menu------------------------------

A. DAMLX. Done


Installing the CA certificate in the adapterYou must install a CA certificate in the adapter to establish a securecommunication between the adapter and IBM Security Identity Manager.

About this task

To establish a secure communication, you must install:v A private and a corresponding digital certificate for the adapter.v A Certificate Authority (CA) certificate that signed the adapter certificate for the

IBM Security Identity Manager server.

When event notification is employed, the adapter side must contact the IBMSecurity Identity Manager server. In this case, the IBM Security Identity Managerserver identifies itself to the adapter. Because of this action, you must install the


Certificate Authority digital certificate (which signed the IBM Security IdentityManager server digital certificate) in the adapter registry.

When you configure and install event notification, install the IBM Security IdentityManager server CA certificate in the adapter environment. If the server is using aself-signed digital certificate, then the server certificate acts as a CA certificate. Inthis case, only the server digital certificate is required.

The server self-signed certificate or CA signing certificate must be obtained in anexported X.509 DER form and transferred to the adapter host. It must be stored inthe read/write /data directory for subsequent installation by using the certToolutility (provided with the adapter). The binary file transfer of the certificate to theadapter platform is necessary because the certificate is in the DER form. There aredifferent methods to obtain and transfer the certificate to the adapter host.

The following steps are valid ONLY for obtaining a self-signed certificate from awebserver:

Procedure1. Open a Web browser, for example, Internet Explorer.2. Use HTTPS (HTP over SSL) to connect to IBM Security Identity Manager

server platform. The following URL is an example:https://9.38.215.20:9443/enrole/login

3. Press Enter, and a dialog box is displayed, indicating a security alert. This alertis because the certificate presented by the site to your web browser is notissued by a company you have chosen to trust.

4. Click View Certificate.5. On the Details tab, click Copy to File and click Next.6. On the Export File Format page, select the DER encoded X.509 (.CER) option

as the format of the certificate and click Next.7. On the File to Export page, specify a directory and name on your local

workstation to store the certificate. Click Next. A completion dialog indicatesthe success of the export wizard. Note of the full path of the File Name in thisdisplay.

8. Click OK to close the Success dialog box.9. Click OK to close the Certificate dialog box. The Security alert dialog box is

displayed.10. Click either:

v Yes to connect to the IBM Security Identity Manager server.v No to deny the connection.

The choice is irrelevant, because you have already captured the certificate toyour workstation.

11. Use the FTP utility to transfer the exported certificate to the host where theadapter resides. The following example shows an FTP session, transferring thecertificate to the adapter host:


C:\temp>dir *.cerVolume in drive C is Local DiskVolume Serial Number is 289F-D3F5

Directory of C:\temp

10/26/2004 04:37p 742 rhea.cer1 File(s) 742 bytes0 Dir(s) 3,924,729,856 bytes free

C:\temp>ftp 9.38.214.54Connected to 9.38.214.54.220-FTPD1 IBM FTP CS V1R4 at AGENTHOST.IBM.COM, 00:59:19 on 2004-10-30.220 Connection will close if idle for more than 5 minutes.User (9.38.214.54:(none)): agntusr331 Send password please.Password:230 JOHNY is logged on. Working directory is "JOHNY.".ftp> cd /u/itim/data250 HFS directory /u/itim/data is the current working directoryftp> bin200 Representation type is Imageftp> put rhea.cer200 Port request OK.125 Storing data set /u/itim/data/rhea.cer250 Transfer completed successfully.ftp: 742 bytes sent in 0.02Seconds 37.10Kbytes/sec.ftp> quit221 Quit command received. Goodbye.

C:\temp>exit

12. Connect to the adapter host so that you can run the certTool utility and installthe certificate that you have just uploaded. The following example is a sampleterminal session on the adapter host to do the installation:


/u/itim/readwrite/data:>ls -altotal 10328drwxrwxr-x 2 AGNTUSR SYS1 8192 Oct 29 14:22 .drwxrwxr-x 6 AGNTUSR SYS1 8192 Oct 7 16:44 ..-rw-rw-r-- 1 AGNTUSR SYS1 888 Oct 15 17:12 DamlCACerts.pem-rwx------ 1 AGNTUSR SYS1 7173 Oct 29 14:09 CATSSAgentT.dat-rw------- 1 AGNTUSR SYS1 1581 Oct 7 16:45 damlserver.pfx-rw-r----- 1 AGNTUSR SYS1 1970 Oct 20 18:00 damlsrvr2.pfx-rw-r----- 1 AGNTUSR SYS1 729 Oct 29 17:59 rhea.cer-rw------- 1 AGNTUSR SYS1 5242908 Oct 29 14:21 rhea_local.dat/u/itim/readwrite/data:>../bin/certTool

IBM Security Agent DAML Protocol Certificate Tool 6.00------------------------------------------------------

Main menu - Configuring agent: CATSSAgent------------------------------

A. Generate private key and certificate requestB. Install certificate from fileC. Install certificate and key from PKCS12 fileD. View current installed certificate

E. List CA certificatesF. Install a CA certificateG. Delete a CA certificate

H. List registered certificatesI. Register certificateJ. Unregister a certificate

K. Export certificate and key to PKCS12 file

X. Quit

Choice: f

Enter name of certificate file: rhea.cer

Subject: /C=US/O=IBM/OU=SWG/CN=jserver

Install this CA (Y/N)? y

Main menu - Configuring agent: CATSSAgent------------------------------

A. Generate private key and certificate requestB. Install certificate from fileC. Install certificate and key from PKCS12 fileD. View current installed certificate




X. Quit

Choice: x

Results

The self-signed digital certificate for the IBM Security Identity Manager server isnow installed in the managed host adapter, as a CA certificate. You can use the


event notification process to connect to IBM Security Identity Manager throughSSL.

Adding an event notification contextEvent Notification updates the IBM Security Identity Manager server at setintervals. It updates the server with the information that changed from the lastserver initiated reconciliation.

About this task

The following screen describes all the options that are displayed when you enableEvent Notification. If you disable Event Notification, none of the options aredisplayed. To set Event Notification for the IBM Security Identity Manager server,perform the following steps:1. Access the Agent Main Configuration Menu. See “Starting the adapter

configuration tool” on page 24.2. At the Agent Main Configuration Menu, type C to display Event Notification

Menu.

Event Notification Menu--------------------------------------* Reconciliation interval : 1 day(s)* Next Reconciliation time : 23 hour(s) 41 min(s). 37 sec(s).* Last processing time : 53 sec(s).* Configured Contexts : RHEA

A. EnabledB. Time interval between reconciliations.C. Set processing cache size.(currently: 50 Mbytes)D. Start event notification now.E. Set attributes to be reconciled.F. Add Event Notification Context.G. Modify Event Notification Context.H. Remove Event Notification Context.I. List Event Notification Contexts.J. Set password attribute names.

X. Done

Select menu option:

3. At the Agent Main Configuration Menu, type the letter of the menu optionthat you want to change.

Note:

v Enable option A for the values of the other options to take effect. Each timeyou select this option, the state of the option changes.

v Press Enter to return to the Agent Event Notification Menu withoutchanging the value.

Table 8. Options for the event notification menu


A If you select this option, the adapter updates the IBM Security IdentityManager server with changes to the adapter at regular intervals.

When the option is set to:

v Disabled, pressing the A key changes to enabled

v Enabled, pressing the A key changes to disabled

Type A to toggle between the options.


Table 8. Options for the event notification menu (continued)


B Displays the following prompt:

Enter new interval([ww:dd:hh:mm:ss])

Type a different reconciliation interval. For example:

[00:01:00:00:00]

Note: This value is the interval to wait after the event notificationcompletes before it is run again. The event notification process isresource intense, therefore, this value must not be set to run frequently.

C Displays the following prompt:

Enter new cache size[5]:

Type a different value to change the processing cache size.

D If you select this option, event notification starts.

E Displays the Event Notification Entry Types Menu: For moreinformation, see “Setting attributes for reconciliation” on page 42.

F Displays the following prompt:

Context name:

Type the new context name and press Enter. The new context is added.

G Displays a menu that lists the available contexts: For more information,see “Modifying an event notification context” on page 43.

H Displays the Remove Context Menu. This option displays the followingprompt:

Delete context context1? [no]:

Press Enter to exit without deleting the context or type Yes and pressEnter to delete the context.

I Displays the Event Notification Contexts in the following format:

Context Name : Context1Target DN :erservicename=context1,o=IBM,ou=IBM,dc=com--- Attributes for search request ---{search attributes listed}-----------------------------------------------

J When you select the Set password attribute names option, you can setthe names of the attributes that are sensitive, for example, erpassword.In this case, the state database does not store these attribute values. Thelocal database for event notification stores the changes from IBMSecurity Identity Manager and the subsequent event notification doesnot retrieve the sensitive attributes. The event notification does not sendthe changes as events if the reconciliation operation does not retrieve thesensitive attributes.

4. To add an event notification context, select option F to add a context. You areprompted for a context name, then returned to the Event Notification Menu.


Select menu option:F

Enter new context name: CATSSAgent

Event Notification Menu--------------------------------------* Reconciliation interval : 1 day(s)* Next Reconciliation time : 22 hour(s) 24 min(s). 52 sec(s).* Configured Contexts : CA Top Secret

A. EnabledB. Time interval between reconciliations.C. Set processing cache size.(currently: 50 Mbytes)D. Start event notification now.E. Set attributes to be reconciled.F. Add Event Notification Context.G. Modify Event Notification Context.H. Remove Event Notification Context.I. List Event Notification Contexts.J. Set password attribute names.

X. Done

Select menu option:

5. If you changed the value for options B, C, E, or F, press Enter. The otheroptions are automatically changed when you type the corresponding letter ofthe menu option.

Results

The Event Notification Menu is displayed with your new settings.

Attributes for searchFor some adapters, you might need to specify an attribute/value pair for one ormore contexts.

These attribute/value pairs, which are defined in the context under Set attributesfor search, serve multiple purposes:v Multiple service instances on the IBM Security Identity Manager server can

reference the adapter. Each service instance must have permissions to specify anattribute-value pair so that the adapter knows which service instance isrequesting work.

v The attribute is sent to the event notification process when the event notificationinterval occurred or is manually initiated. When the attribute is received, theadapter processes information that the attribute/value pair indicates.

v When you initiate a server-initiated reconciliation process is initiated, theadapter replaces the local database that represents this service instance.

Table 9 describes a partial list of possible attribute/value pairs that you can specifyfor Set attributes for search.

Table 9. Attributes for search

Service type Form label Attribute name Value

CATSSProfile CA Top Secret IDunder which requestsare processed

ertopzrequester A CA Top SecretControl ACID thatmanages users inthis service.


Select menu option:g

Modify Context Menu------------------------------

A. CA Top Secret

X. Done


Modify Context: CA Top Secret------------------------------------

A. Set attributes for searchB. Target DN:


Reconciliation Attributes Passed to Agent for context: CA Top Secret-------------------------------------------------

A. Add new attributeB. Modify attribute valueC. Remove attribute

X. Done


Attribute name : ertopzrequester

Attribute value: admnbu1

Reconciliation Attributes Passed to Agent for context: CA Top Secret-------------------------------------------------01. ertopzrequester ’admnbu1’-------------------------------------------------


X. Done


Pseudo-distinguished name valuesThe Target DN field has the pseudo-distinguished name of the service that receivesevent notification updates.

To assist in determining the correct entries, this name might be considered tocontain the listed components in the A+B+C+D+E sequence.

Note: Do not use a comma to define a pseudo DN.

Table 10. Name values and their description

Component Item Description

A erServicename The value of the erServicename attribute of theservice.


Table 10. Name values and their description (continued)

Component Item Description

B Zero or moreoccurrences of ouor 1 or both.

When the service is not directly associated with theorganization, you must specify ou and l. Thespecification of these values are in a reversesequence of their appearance in the IBM SecurityIdentity Manager organization chart.

C o The value of the o attribute of an organization towhich the service belongs, at the highest level. Thismight be determined by examining the IBM SecurityIdentity Manager organization chart.

D ou The ou component is established at IBM SecurityIdentity Manager installation. You can find thiscomponent in the IBM Security Identity Managerconfiguration file named enRole.properties, onconfiguration item named enrole.defaulttenant.id=

E dc The dc component is established at IBM SecurityIdentity Manager installation. This is the root suffixof the LDAP environment. You can find thiscomponent in the IBM Security Identity Managerconfiguration file named enRole.properties, onconfiguration item named enrole.ldapserver.root=

Example 1:

A:

The service name on the IBM Security Identity Manager server is MVS CATop Secret 4.5.1016 ENTEST. This name becomes the component A of thepseudo-DN:erservicename=MVS CA Top Secret 4.5.1016 ENTEST

B:

Table 11 describes an example of the IBM Security Identity Managerorganization chart that indicates the location of the service in theorganization.

Table 11. Organization chart example

+ Identity Manager Home IBM Security Identity Manager Home

+ Acme Inc Base organization o

Component B is not required because the service is directly associated withthe organization at the beginning of the organization chart.

C:

The organization this service is associated with, described on the IBMSecurity Identity Manager organization chart is named Acme Inc. Theservice becomes component C of the pseudo-DN:o=Acme Inc

D:

Through examination or prior knowledge of the contents of theenRole.properties definition file on the IBM Security Identity Managerserver, the value of the property named enrole.defaulttenant.id= becomescomponent D of the pseudo-DN. For example:


############################################################# Default tenant information###########################################################enrole.defaulttenant.id=Acme

The D component of the pseudo-DN is: ou=Acme

E:

Through examination or prior knowledge of the contents of theenRole.properties definition file on the IBM Security Identity Managerserver, the value of the property named enrole.ldapserver.root= becomescomponent E of the pseudo-DN. For example:############################################################# LDAP server information###########################################################enrole.ldapserver.root=dc=my_suffix

The E component of the pseudo-DN is: dc=my_suffix

The following pseudo-DN is the result of all the components (A+B+C+D+Ecomponents):erservicename=MVS CA Top Secret 4.5.1016 ENTEST,o=Acme Inc,ou=Acme,dc=my_suffix

Example 2:

A:

The service name on the IBM Security Identity Manager server is IrvineSales. This name becomes component A of the pseudo-DN:erservicename=Irvine Sales

B:

Table 12 describes an example of the IBM Security Identity Managerorganization chart that indicates the location of the service in theorganization.

Table 12. Organization chart example

+ Identity Manager Home IBM Security Identity Manager Home

-Acme Inc Base organization o

- IrvineSales

LocationOrganizational Unit lou

The Irvine Sales service is defined under organizational unit (ou) namedSales, which is defined under location (l) named Irvine.

Component B of the pseudo-DN is:ou=Sales,l=Irvine

C:

The organization this service is associated with, shown on the IBM SecurityIdentity Manager organization chart is named Acme Inc. This becomes thecomponent C of the pseudo-DN:o=Acme Inc

D:

Through examination or prior knowledge of the contents of theenRole.properties definition file on the IBM Security Identity Manager


server, the value of the property named enrole.defaulttenant.id= becomescomponent D of the pseudo-DN. For example:############################################################# Default tenant information###########################################################enrole.defaulttenant.id=Acme

The D component of the pseudo-DN is:ou=Acme

E:

Through examination or prior knowledge of the contents of theenRole.properties definition file on the IBM Security Identity Managerserver, the value of the property named enrole.ldapserver.root= becomescomponent E of the pseudo-DN. For example:############################################################# LDAP server information###########################################################enrole.ldapserver.root=dc=my_suffix

The E component of the pseudo-DN is:dc=my_suffix

The following pseudo-DN is the result of the components (A+C+D+E). ComponentB is not required.erservicename=Irvine Sales, ou=Sales,l=Irvine o=Acme Inc,ou=Acme,dc=my_suffix

Setting attributes for reconciliationYou can set attributes for reconciliation when the values change for attributes thattrigger event notifications. You also can remove attributes that change frequently,such as password age or last successful logon.

About this task

Note: You cannot see the event notification entry types and attributes until youperform the first reconciliation with event notification as Enabled.


See “Starting the adapter configuration tool” on page 24.2. Type E (Set attributes for reconciliation) to display the Event Notification Entry

Types menu.Select menu option:e

Event Notification Entry Types--------------------------------------A. ERTOPZACCOUNTSB. ERTOPZPROFILESC. ERTOPZGROUPSD. ERTOPZDEPARTMENTSE. ERTOPZDIVISIONSF. ERTOPZZONES

X. Done

Select menu option:


3. Do one of the following to display the Event Notification Attribute Listing forthe selected reconciliation type.Select menu option:a

Event Notification Attribute Listing---------------------------------------------------------------------{A} ** ERACCOUNTSTATUS {B} ** ERTOPZACIDAUTH {C} ** ERTOPZADMINLISTDATA{D} ** ERTOPZASSIZE {E} ** ERTOPZASUSPEND {F} ** ERTOPZAUDIT{G} ** ERTOPZCONSOLE {H} ** ERTOPZCREATEDDATE {I} ** ERTOPZDEPARTMTACID{J} ** ERTOPZDFLTGRP {K} ** ERTOPZDFLTSLBL {L} ** ERTOPZDIVISIONACID{M} ** ERTOPZDUFUPD {O} ** ERTOPZDUFXTR {Q} ** ERTOPZEXPIRATIONDATE{R} ** ERTOPZFACILITY {S} ** ERTOPZGROUP {T} ** ERTOPZIMSMSC

(p)rev Page 1 of 7 (n)ext-----------------------------------------------------------------------X. Done

Select menu option:

4. To exclude an attribute from an event notification, type the letter beside theattribute you want to exclude.

Note: Attributes that are marked with ** are returned during the eventnotification. Attributes that are not marked with ** are not returned during theevent notification.

Modifying an event notification contextAn event notification context corresponds to a service on the IBM Security IdentityManager server.

About this task

Some adapters support multiple services. One z/OS adapter can have several IBMSecurity Identity Manager services if you specify a different base point for eachservice. You can have multiple event notification contexts, however, you must haveat least one adapter.

To modify an event notification context, perform the following steps. In thefollowing example screen, Context1, Context2, and Context3 are different contextsthat have a different base point.

Procedure1. Access the Agent Main Configuration Menu. See “Starting the adapter

configuration tool” on page 24.2. From Event Notification, type the Event Notification Menu option.3. From Event Notification Menu, type the Modify Event Notification Context

option to display a list of available context.For example,

Modify Context Menu------------------------------A. Context1B. Context2C. Context3X. DoneSelect menu option:

4. Type the option of the context that you want to modify to obtain a list asdescribed in the following screen.


A. Set attributes for searchB. Target DN:C. Delete Baseline DatabaseX. DoneSelect menu option:

Table 13. Options for the Modify Context Menu

Option Configuration task For more information

A Adding search attributes for event notification See “Adding search attributesfor event notification.”

B Configuring the target DN for event notificationcontexts

See “Configuring the target DNfor event notification contexts”on page 45.

C Removing the baseline database for eventnotification contexts

See “Removing the baselinedatabase for event notificationcontexts” on page 46.

Adding search attributes for event notificationFor some adapters, you might need to specify an attribute/value pair for one ormore contexts.

About this task

These attribute/value pairs, which are defined by completing the following steps,serve multiple purposes:v When a single adapter supports multiple services, each service must specify one

or more attributes to differentiate the service from the other services.v The adapter passes the search attributes to the event notification process either

after the event notification interval occurs or the event notification startsmanually. For each context, a complete search request is sent to the adapter.Additionally, the attributes specified for that context are passed to the adapter.

v When the IBM Security Identity Manager server initiates a reconciliation process,the adapter replaces the local database that represents this service with the newdatabase.

To add search attributes, perform the following steps:


See “Starting the adapter configuration tool” on page 24.2. At the Modify Context Menu for the context, type A to display the

Reconciliation Attribute Passed to Agent Menu.

Reconciliation Attributes Passed to Agent for Context: Context1--------------------------------------------------------------------------------------------------------A. Add new attributeB. Modify attribute valueC. Remove attributeX. DoneSelect menu option:

3. Type the letter of the menu option that you want to change. The supportedattribute names are displayed with two asterisks (**) in front of each name.


Attributes without asterisks are not updated during an event notification. TheReconciliation Attributes Passed to Agent Menu is displayed with the changesdisplayed.

Configuring the target DN for event notification contextsDuring event notification configuration, the adapter sends requests to a servicerunning on the IBM Security Identity Manager server.

About this task

Therefore, you must configure target DN for event notification contexts for theadapter to know which service the adapter must send the request to. Configuringthe target DN for event notification contexts involves specifying parameters, suchas the adapter service name, organization (o), organization name (ou), and otherparameters.

To configure the target DN, perform the following steps:

Procedure1. Access the Agent Main Configuration Menu, if you have not already done so. .

See “Starting the adapter configuration tool” on page 242. Type the option for Event Notification to display the Event Notification Menu.3. Type the option for Modify Event Notification Context, then enter the option of

the context that you want to modify.4. At the Modify Context menu for the context, type B to display the following

prompt:Enter Target DN:

5. Type the target DN for the context and press Enter. The target DN for the eventnotification context must be in the following format:erservicename=erservicename,o=organizationname,ou=tenantname,rootsuffix

Table 14 describes each DN element.

Table 14. DN elements and definitions

Element Definition

erservicename Specifies the name of the target service.

o Specifies the name of the organization.

ou Specifies the name of the tenant under which theorganization is. If this is an enterprise installation, thenou is the name of the organization.

rootsuffix Specifies the root of the directory tree. This value is thesame as the value of Identity Manager DN Location whichis specified during the IBM Security Identity Managerserver installation.

6. After you define the new target DN, the software displays the Modify Contextmenu. After you add the event notification context, you can modify it withoption G to add information to the context. You must specify a target pseudoDN.To construct a target DN, see “Pseudo-distinguished name values” on page 39.


Select menu option: G


A. Set attributes for searchB. Target DN:

X. Done

Select menu option:b

Enter Target DN: erservicename=MVS CA Top Secret 4.5.1016 ENTEST,o=Acme Inc,ou=Acme,dc=my_suffix


A. Set attributes for searchB. Target DN: erservicename=MVS CA Top Secret 4.5.1016 ENTEST,o=Acme Inc,

ou=Acme,dc=my_suffix

X. Done

Select menu option:

Removing the baseline database for event notification contextsYou can remove the baseline database for event notification contexts only after youcreate a context and perform a reconciliation operation on the context to create aBaseline Database file.

About this task

To remove the baseline database for event notification contexts, perform thefollowing steps:

Procedure1. From the Agent Main Configuration Menu, type the Event Notification option.2. From the Event Notification Menu, type the Remove Event Notification

Context option to display the Modify Context Menu.3. Select the context that you want to remove.4. After confirming that you want to remove a context, press Enter to remove the

baseline database for event notification contexts.

Changing the configuration keyYou use the configuration key as a password to access the configuration tool forthe adapter.

About this task

To change the CA Top Secret Adapter configuration key, perform the followingsteps:


See “Starting the adapter configuration tool” on page 24.2. At the Main Menu prompt, type D.3. Do on of the following:


v Change the value of the configuration key and press Enter.v Press Enter to return to the Main Configuration Menu without changing the

configuration key.

Results

The default configuration key is agent. Ensure that your password is complex. Thefollowing message is displayed:Configuration key successfully changed.

The configuration program returns to the Main Menu prompt.

Changing activity logging settingsUse this task to enable or disable log files that monitor various system activities.

About this task

When you enable activity logging settings, IBM Security Identity Managermaintains a log file (CATSSAgent.log) of all transactions. By default, the log file isin the read/write \log directory.

To change the CA Top Secret Adapter activity logging settings,


See “Starting the adapter configuration tool” on page 24.2. At the Main Menu prompt, type E to display the Agent Activity Logging Menu.

The following screen displays the default activity logging settings.

Agent Activity Logging Menu-------------------------------------A. Activity Logging (Enabled).B. Logging Directory (current: /var/ibm/isimcatss/log).C. Activity Log File Name (current: CATSSAgent.log).D. Activity Logging Max. File Size ( 1 mbytes)E. Activity Logging Max. Files ( 3 )F. Debug Logging (Enabled).G. Detail Logging (Disabled).H. Base Logging (Disabled).I. Thread Logging (Disabled).X. DoneSelect menu option:

3. Perform one of the following steps:v Press Enter to change the value for menu option B, C, D, or E. The other

options are changed automatically when you type the corresponding letter ofthe menu option. Table 15 on page 48 describes each option.

v Press Enter to return to the Agent Activity Logging Menu without changingthe value.

Note: Ensure that Option A is enabled for the values of other options to takeeffect.


Table 15. Options for the activity logging menu


A Set this option to Enabled for the adapter to maintain a dated log file ofall transactions.


v Disabled, pressing the A key changes to enabled

v Enabled, pressing the A key changes to disabled

Type A to toggle between the options.

B Displays the following prompt:

Enter log file directory:

Type a different value for the logging directory, for example, /home/Log.When the logging option is enabled, details about each access requestare stored in the logging file that is in this directory.

CDisplays the following prompt:

Enter log file name:

Type a different value for the log file name. When the logging option isenabled, details about each access request are stored in the logging file.

D Displays the following prompt:

Enter maximum size of log files (mbytes):

Type a new value, for example, 10. The oldest data is archived when thelog file reaches the maximum file size. File size is measured inmegabytes. It is possible for the activity log file size to exceed the diskcapacity.

E Displays the following prompt:

Enter maximum number of log files to retain:

Type a new value up to 99, for example, 5. The adapter automaticallydeletes the oldest activity logs beyond the specified limit.

F If this option is set to enabled, the adapter includes the debugstatements in the log file of all transactions.


v Disabled, pressing the F key changes the value to enabled

v Enabled, pressing the F key changes the value to disabled

Type F to toggle between the options.

G If this option is set to enabled, the adapter maintains a detailed log fileof all transactions. The detail logging option must be used for diagnosticpurposes only. Detailed logging enables more messages from the adapterand might increase the size of the logs.


v Disabled, pressing the G key changes the value to enabled

v Enabled, pressing the G key changes the value to disabled

Type G to toggle between the options.


Table 15. Options for the activity logging menu (continued)


H If this option is set to enabled, the adapter maintains a log file of alltransactions in the Agent Development Kit (ADK) and library files. Baselogging substantially increases the size of the logs.


v Disabled, pressing the H key changes the value to enabled

v Enabled, pressing the H key changes the value to disabled

Type H to toggle between the options.

I If this option is enabled, the log file contains thread IDs, in addition to adate and timestamp on each line of the file.


v Disabled, pressing the I key changes the value to enabled

v Enabled, pressing the I key changes the value to disabled

Type I to toggle between the options.

Modifying registry settingsUse this procedure to change the adapter registry settings.

Procedure1. At the Main Menu, type F. The Registry Menu is displayed.2. Select menu option.

adapter_name 5.1 Agent Registry Menu-------------------------------------------A. Modify Non-encrypted registry settings.B. Modify encrypted registry settings.C. Multi-instance settings.X. DoneSelect menu option:

What to do next

For a list of valid registry options, their values, and meanings, see Appendix B,“Registry settings,” on page 107.

Modifying non-encrypted registry settingsYou can modify non-encrypted registry settings.

Procedure1. At the Agent Registry Menu, type A. The Non-encrypted Registry Settings

Menu is displayed.


Agent Registry Items-------------------------------------------------01. APPCCMD ’ISIMCMD’02. APPCMODE ’#INTERSC’03. APPCRECO ’ISIMRECO’04. ENROLE_VERSION ’4.0’05. PASSEXPIRE ’FALSE’-------------------------------------------------

Page 1 of 1


X. Done

Select menu option:

2. Type the letter of the menu option for the action that you want to perform onan attribute.

Table 16. Attribute configuration option description


A Add new attribute

B Modify attribute value

C Remove attribute

3. Type the registry item name and press Enter.4. If you selected option A or B, type the registry item value and press Enter.

Results

The non-encrypted registry settings menu reappears and displays your newsettings.

Changing advanced settingsYou might need to change advanced settings.

About this task

You can change the adapter thread count settings for the following types ofrequests:v System Login Addv System Login Changev System Login Deletev Reconciliation

These thread counts determines the maximum number of requests that the adapterprocesses. To change these settings, perform the following steps:


See “Starting the adapter configuration tool” on page 24.2. At the Main Menu prompt, type G to display the Advanced Settings Menu.

The following screen displays the default thread count settings.


CATSSAgent 5.1 Advanced Settings Menu-------------------------------------------A. Single Thread Agent (current:FALSE)B. ADD max. thread count. (current:3)C. MODIFY max. thread count. (current:3)D. DELETE max. thread count. (current:3)E. SEARCH max. thread count. (current:3)F. Allow User EXEC procedures (current:FALSE)G. Archive Request Packets (current:FALSE)H. UTF8 Conversion support (current:TRUE)I. Pass search filter to agent (current:FALSE)

X. DoneSelect menu option:

Table 17. Options for the advanced settings menu

Option Description

AForces the adapter to submit only one request at a time.

The default value is FALSE.

BLimits the number of Add requests that can run simultaneously.

The default value is 3.

CLimits the number of Modify requests that can run simultaneously.


DLimits the number of Delete requests that can run simultaneously.


ELimits the number of Search requests that can run simultaneously.


FDetermines if the adapter can perform the pre-exec and post-execfunctions. The default value is FALSE.Note: Enabling this option is a potential security risk.

JSets the thread priority level for the adapter.


3. Type the letter of the menu option that you want to change. For a descriptionof each option, see Table 17.

4. Change the value and press Enter to display the Advanced Settings Menu withnew settings.

Viewing statisticsYou can view an event log for the adapter.


See “Starting the adapter configuration tool” on page 24.


2. At the Main Menu prompt, type H to display the activity history for theadapter.

CATSSAgent 5.1 Agent Request Statistics--------------------------------------------------------------------Date Add Mod Del Ssp Res Rec

-----------------------------------------------------------------

10/19/2004 000000 000004 000000 000000 000000 000004

-----------------------------------------------------------------

X. Done

3. Type X to return to the Main Configuration Menu.

Code page settingsYou must complete several tasks to change code page settings.v “Default adapter code page locale”v “Obtaining of a list of valid code pages”v “Setting the code page” on page 53

Default adapter code page localeThe default code page setting for ASCII based adapters is US-ASCII.

For EBCDIC hosts, such as MVS, the default code page is IBM-1047-s390.

Obtaining of a list of valid code pagesTo obtain a list of valid code page locale names, run the agentCfg.

For example:agentCfg -ag adaptername -codepages

Ensure that the adapter is running and you have specified the configuration key todisplay a list of valid code page names that are available for the adapter. Thefollowing list of valid code pages is a partial session with the agentCfg.


IBMUSER:/home/itim/CATSSAgent/readwrite/bin: >agentCfg -ag CATSSAgent -codepages

Enter configuration key for Agent ’CATSSAgent’:

List of codepage supported by ICU :

UTF-8UTF-16UTF-16BEUTF-16LEUTF-32UTF-32BEUTF-32LEUTF16_PlatformEndianUTF16_OppositeEndianUTF32_PlatformEndianUTF32_OppositeEndianISO-8859-1US-ASCII...ibm-37_P100-1995,swaplfnlibm-1047_P100-1995,swaplfnlibm-1140_P100-1997,swaplfnlibm-1142_P100-1997,swaplfnlibm-1143_P100-1997,swaplfnlibm-1144_P100-1997,swaplfnlibm-1145_P100-1997,swaplfnlibm-1146_P100-1997,swaplfnlibm-1147_P100-1997,swaplfnlibm-1148_P100-1997,swaplfnlibm-1149_P100-1997,swaplfnlibm-1153_P100-1999,swaplfnlibm-12712_P100-1998,swaplfnlibm-16804_X110-1999,swaplfnlebcdic-xml-us

Setting the code pageYou can change the code page settings for the adapter.

Procedure1. At the Main Menu prompt, type I.

The Code Page Support Menu for the adapter is displayed.

CATSSAgent 5.1 Codepage Support Menu-------------------------------------------* Configured codepage: IBM-1047-s390-------------------------------------------********************************************* Restart Agent After Configuring Codepages*******************************************

A. Codepage Configure.

X. Done

Select menu option:

2. Type A to configure a code page.

Note: The CATSSAgent uses unicode; therefore, this option is not applicable.3. Type X to return to the Main Configuration Menu.4. After you select a code page, restart the adapter.


Example

The following example is a sample session with the agentCfg, altering the defaultcode page, from US EBCDIC (IBM-1047) to Spanish EBCDIC (IBM-1145).

IBMUSER:/u/ibmuser: >agentCfg -ag CATSSAgent

Enter configuration key for Agent ’CATSSAgent’:

CATSSAgent 4.6 Agent Main Configuration Menu-------------------------------------------

A. Configuration Settings.B. Protocol Configuration.C. Event Notification.D. Change Configuration Key.E. Activity Logging.F. Registry Settings.G. Advanced Settings.H. Statistics.I. Codepage Support.

X. Done

Select menu option:i

CATSSAgent 4.5.1017 Codepage Support Menu-------------------------------------------* Configured codepage: IBM-1047-s390-------------------------------------------********************************************* Restart Agent After Configuring Codepages*******************************************


X. Done


Enter Codepage: ibm-1145

CATSSAgent 4.5.1017 Codepage Support Menu-------------------------------------------* Configured codepage: ibm-1145-------------------------------------------********************************************* Restart Agent After Configuring Codepages*******************************************


X. Done


Accessing help and additional optionsTo access the agentCfg help menu and use the help arguments, perform thefollowing steps:

Procedure1. At the Main Menu prompt, type X to display the USS command prompt.2. Type agentCfg -help at the prompt to display the help menu and list of

commands.


-version ;Show version-hostname <value> ;Target nodename to connect to (Default:Local hostIP address)-findall ;Find all agents on target node-list ;List available agents on target node-agent <value> ;Name of agent-tail ;Display agent’s activity log-schema ;Display agent’s attribute schema-portnumber <value> ;Specified agent’s TCP/IP port number-netsearch <value> ;Lookup agents hosted on specified subnet-codepages ;Display list of available codepages-help ;Display this help screen

The following table describes each argument.

Table 18. Arguments and description for the agentCfg help menu

Argument Description

-version Use this argument to display the version ofthe agentCfg tool.

-hostname <value> Use the -hostname argument with one of thefollowing arguments to specify a differenthost:

v -findall

v -list

v -tail

v -agent

Enter a host name or IP address as thevalue.

-findall Use this argument to search and display allport addresses 44970 - 44994 and theirassigned adapter names. This option timesout the unused port numbers, therefore, itmight take several minutes to complete.

Add the -hostname argument to search aremote host.

-list Use this argument to display the adaptersthat are installed on the local host of the CATop Secret Adapter. By default, the first timeyou install an adapter, it is either assigned toport address 44970 or to the next availableport number. You can then assign all thelater installed adapters to the next availableport address. After the software finds anunused port, the listing stops.

Use the -hostname argument to search aremote host.

-agent <value> Use this argument to specify the adapterthat you want to configure. Enter theadapter name as the value. Use thisargument with the -hostname argument tomodify the configuration setting from aremote host. You can also use this argumentwith the -tail argument.


Table 18. Arguments and description for the agentCfg help menu (continued)

Argument Description

-tail Use this argument with the -agent argumentto display the activity log for an adapter.Add the -hostname argument to display thelog file for an adapter on a different host.

-portnumber <value> Use this argument with the -agent argumentto specify the port number that is used forconnections for the agentCfg tool.

-netsearch <value> Use this argument with the -findallargument to display all active adapters onthe z/OS operating system. You mustspecify a subnet address as the value.

-codepages Use this argument to display a list ofavailable codepages.

-help Use this argument to display the Helpinformation for the agentCfg command.

3. Type agentCfg before each argument you want to run, as shown in thefollowing examples.

agentCfg -listDisplays a list of all the adapters on the local host, the IP address of thehost, the IP address of the local host, and the node on which theadapter is installed. The default node for the IBM Security IdentityManager server must be 44970. The output is similar to the followingexample:Agent(s) installed on node ’127.0.0.1’-----------------------adapter_name (44970)

agentCfg -agent adapter_nameDisplays the Main Menu of the agentCfg tool, which you can use toview or modify the adapter parameters.

agentCfg -list -hostname 192.9.200.7Displays a list of the adapters on a host with the IP address 192.9.200.7.Ensure that the default node for the adapter is 44970. The output issimilar to the following example:Agent(s) installed on node ’192.9.200.7’------------------adapter_name (44970)

agentCfg -agent adapter_name -hostname 192.9.200.7Displays the agentCfg tool Main Menu for a host with the IP address192.9.200.7. Use the menu options to view or modify the adapterparameters.

Customization of the CA Top Secret AdapterYou can perform specific functions according to your requirements with REXXexecs that are provided with the adapter installation.v “ISIMEXIT” on page 57v “ISIMEXEC” on page 61


ISIMEXITThe REXX exec ISIMEXIT gets called in response to add, modify and deleterequests received from the IBM Security Identity Manager server.

You can implement the following instances where the ISIMEXIT exec gets control:

Before add processingThe request to add a user is received, however, not yet processed.

After add processingThe request to add a user is completed successfully.

Before modify processingThe request to modify a user is received, however, not yet processed.

After modify processingThe request to modify a user is completed successfully.

Before delete processingThe request to delete a user is received, however, not yet processed.

After delete processingThe request to delete a user is completed successfully.

You may program ISIMEXIT to indicate success (zero return code) or failure(non-zero return code). For the before add processing, before modify, and beforedelete exits, any non-zero return code will stop processing and return a failure toIBM Security Identity Manager server for that request, and the add, modify ordelete request will not be processed. For the after add processing, after modify, andafter delete exits, a non-zero return code will return a warning to the IBM SecurityIdentity Manager server.

ISIMEXIT gets control in a TSO batch environment, running in the APPC/MVSenvironment. Processing is performed under the authority of the same CA TopSecret ACID that runs the CA Top Secret commands. You might call otherprograms, perform file Input/Output (I/O), or run valid TSO commands (if it doesnot prompt for a terminal user for input), as necessary.

Ensure that the ISIMEXIT exec is available independent of whether it performs anyfunctions. The sample ISIMEXIT provided has an exit 0 as the first executablestatement. You must modify this exit to meet your requirements.

The sample exit provides functions that you might use or customize according toyour requirements. For example:v Defining a user catalog alias in one or more master catalogs after add processing

or at after modify exit time.v Defining a user data set profile after add processing or at after modify exit time.v Defining a user OMVS (UNIX System Services) home directory after add

processing or at after modify exit time.v Deleting a user data set profiles at before delete exit time.v Deleting a user catalog alias at after delete exit time.

Note: Ensure that the Processing ID has appropriate CA Top Secret authorizationto perform the listed exit functions.

The listed information is available to the EXIT.


Table 19. ISIMEXIT processing information

Parameter # Meaning Possible value Availability

1 Verb

Indicates what operationis calling the exit.

ADD, MODIFY, orDELETE

Always

2 Object

The object name of thetransaction.

USER indicating a CATop Secret user objectthat is processed.

Always

3 Prepost

Qualifies whether this isbefore or afterprocessing entry to theexit.

BEFORE or AFTER Always

4 User ID The CA Top SecretACID that is processed.

Always

5 Organizational type

The CA Top SecretACID type

The value of theattribute ertopztype

Only at before addprocessing or after addprocessing exit. Notavailable for delete ormodify processing.

6 Organization

The CA Top SecretACIDzone/division/department, dependenton the organizationaltype.

The value of theattributeertopzzoneacid,ertopzdivisionacid, orertopzdepartmtacid,depending on the type.

Only at before addprocessing or after addprocessing exit. Notavailable for delete ormodify processing.

7 Name The value of theattribute ertopzname.

Only add before andafter

8 Using The value of theattribute ertopzusing.

Only add before andafter

Additional REXX exit parametersYou can make additional information (attributes) available to ISIMEXIT using themulti-value attribute ertopzexitstring.

This attribute provides a way of telling the adapter to make specific attributesavailable to ISIMEXIT. Only attribute values that are sent with the current requestare available to ISIMEXIT.

Note: This is only available for add and modify requests. On delete requests onlythe userid (ACID) is available to the adapter.

Making additional parameters available to ISIMEXITYou can set the parameters in ertopzexitstring using the account form, or theattribute list could be set in ertopzexitstring using a provisioning policy or aworkflow.

About this task

Take these steps to set the parameters in the account form:


Note: The attribute ertopzexitstring is defined as SendOnly. The attribute namesset in ertopzexitstring are case insensitive.

Procedure1. Customize the account form to include a multiple-value list box of all the

attributes you may wish to make available to ISIMEXIT. See “Customizing theaccount form with fields for ISIMEXIT” on page 60.

2. Type the appropriate information required to add or modify the CA Top Secretaccount into the ITIM account form.

3. Select the attributes you want available to ISIMEXIT for this call from theertopzexitstring multiple-value list box. The attributes you select should havevalues already set in the account form from the previous step.

4. Submit the add or modify request. After receiving the call, the CA Top SecretAdapter will build a string of attribute names and values, as described in“Process of the exit string with ISIMEXIT.”

Process of the exit string with ISIMEXITThe CA Top Secret Adapter receives the request from the IBM Security IdentityManager server and reads the attribute list set in ertopzexitstring.

If attributes are listed, the adapter attempts to find the corresponding values forthose attributes sent with that request. Attributes with no value available areignored by the adapter, and a message is written to the adapter log. You must codethe ISIMEXIT to manage the case where an expected attribute is not available. Astring of the following format is then built:UES=ertopzattr1=value1,ertopzattr2=value2,...,ertopzattrN=valueN

For example:UES=ertopzname=”IBM user”,ertopzUID=123

This string will be made available as a parameter to ISIMEXIT for both before andafter processing.

For an ADD request, ertopzexitstring is the eighth or ninth parameter available toISIMEXIT, depending on whether the optional parameter USING is present.v If USING is not present, ertopzexitstring is the eighth parameter, if USING is

present, ertopzexitstring is the ninth parameter.v The parameter USING is always in this format:

USING(ertopzusing)

For a MODIFY request:v ertopzexitstring is the fifth parameter available to ISIMEXIT.v Only the values that are being modified are available. For example, if you are

adding the ACID authority CREATE to a user ACID that already has INFO andREPORT authorities, then the string available to ISIMEXIT isertopzacidauth=CREATE

The attribute values within the string follow these rules:v If the value contains a space, a comma, or a single quotation mark, then the

value is enclosed in single quotation marks. If the value contains a singlequotation mark, the quotation mark is replaced with two single quotation marks.For example: ertopzname=’Administrator’’s ACID’

v If the attribute is Boolean, the value is either TRUE or FALSE.


v Multi-valued attributes are enclosed in parentheses and separated by commas.For example: ertopzacidauth=(CREATE, INFO, MAINTAIN)

For example, a request for a new CA Top Secret account might have these values:v User ID: USER1v CA-TSS ACID Type: USERv CA-TSS ACID Full Name: Top Secret Userv ACID's Department ACID: DEPT1v Home Directory: /u/userv ACID's Default Group: OMVS

Suppose that you select the following for “Attributes available to adapter userexit” on the account form:ertopzomvshomeertopzdfltgrp

The ISIMEXIT receives the following parameters for the pre-processing exit:ADD USER BEFORE USER1 USER DEPT1 “Top Secret User”UES=ertopzomvshome=/u/user,ertopzdfltgrp=OMVS

Customizing the account form with fields for ISIMEXITYou can customize the account form by adding a multiple-value list box forattributes that you want to make available to ISIMEXIT.

About this task

To add a multiple-value list box to the account form, take these steps:

Procedure1. Copy the CATSSProfile.jar file to a temporary directory and extract the files.

See “Copying the CATSSProfile.jar file and extract the files” on page 65.2. Edit the erTopzACCOUNTS.xml file. There is an example in comments for the

multiple-value list box ertopzexitstring on a new tab “Non CA-TSS attributes”.You may remove the comment delimiters, and add new options as required.For example:

<tab index="12" selected="false"><title><![CDATA[$tab.tss.13]]></title><image/><url>javascript:switchTabs(document.forms[’body’],12);</url><formElement direction="inherit" name="data.ertopzexitstring"label="$ertopzexitstring"><select style="width:200px" name="data.ertopzexitstring" width="200"><option value=" erTopzOMVSHOME">erTopzOMVSHOME</option><option value=" erTopzOMVSPGM">erTopzOMVSPGM</option><option value=" erTopzUID">erTopzUID</option><option value=" erTopzGRP">erTopzGRP</option>..(other lines omitted).</select></formElement></tab>


3. Create a new JAR file and install the new account form on the IBM SecurityIdentity Manager server. For more information, see “Creating a JAR file andinstalling the new attributes on the IBM Security Identity Manager server” onpage 67.

ISIMEXECISIMEXEC is a REXX command. Use this command for backward compatibilitywith the earlier version of the adapter.

The ISIMEXEC processing can present a zero or a non-zero return code when theprocessing is complete. A zero return code indicates successful processing of theerTopzExecname attribute. If a non-zero return code is presented on exit, theadapter indicates that the erTopzExecname attribute failed.

The environment in which the ISIMEXEC gets control is in a TSO batchenvironment, running in the APPC/MVS environment. You might call otherprograms and perform file I/O as necessary. Processing is performed under theauthority of the same CA Top Secret ACID that runs the CA Top Secret commands.You might run a valid TSO command if it does not prompt for a terminal user forinput.

Table 20. ISIMEXEC processing information

Parameter # Source Value Availability

1 IBM Security IdentityManager attribute oferUid

The value of theerUid.

Always, because thisattribute accompaniesall requests.

2 IBM Security IdentityManager attribute oferTopzExecname

The value of theerTopzExecname.

Always, because theavailability of thisattribute indicates thatthis exit must bestarted.

3 IBM Security IdentityManager attribute oferTopzExecvar

The value of theerTopzExecvar.

Based on the requestgenerated by the IBMSecurity IdentityManager server.

The ISIMEXEC exit point is started as a TSO command in the command executorwhen the following attributes are available:v erTopzExecnamev Optional: erTopzExecvar%ISIMEXEC erUid erTopzExecname erTopzExecvar

When the ISIMEXEC is processed, the erTopzExecname attribute can representanything that you want to process. It provides a second-level command or execname that you want to run.

Note:

v You can prevent the running of unauthorized commands for processing byinterrogating the erTopzExecname attribute because ISIMEXEC always receivescontrol.

v ISIMEXEC is never started during a delete command because the adapterpresents only the erUid attribute.


Supporting user-defined ACID fields with extended attributesYou can customize the CA Top Secret Adapter to support user-defined ACID fieldsby mapping each user-defined ACID field to an extended attribute.

About this task

Complete these steps to customize the CA Top Secret Adapter to support theuser-defined fields in the CA Top Secret Field Descriptor Table (FDT):

Procedure1. Define the user-defined ACID fields and extended attributes mappings to the

CA Top Secret Adapter . Use the IBM Security Identity Manager CA Top SecretAdapter ISPF dialog to perform this step.For more information, see “Mapping the user-defined ACID fields to theextended attributes by using the ISPF dialog.”

2. Copy the JAR file to a temporary directory and extract the files.For more information, see “Copying the CATSSProfile.jar file and extract thefiles” on page 65.

3. Update the schema.dsml file on the IBM Security Identity Manager server.For more information, see “Updating the schema.dsml file” on page 66.

4. Update the customlabels.properties file on the IBM Security Identity Managerserver.For more information, see “Modifying the CustomLabels.properties file” onpage 66.

5. Install the new attributes on the IBM Security Identity Manager server.For more information, see “Creating a JAR file and installing the new attributeson the IBM Security Identity Manager server” on page 67.

6. Modify the form for the account on the IBM Security Identity Manager server.For more information, see “Optional modification of the adapter form” on page67.

Mapping the user-defined ACID fields to the extended attributesby using the ISPF dialogThe extended attribute definitions in the CA Top Secret Adapter are managedthrough the ISPF dialog that was installed as part of installation of the adapter.The adapter uses the mapped ACID fields for generating the CA Top Secretcommands for provisioning and for reconciliation.

Before you begin

This dialog requires a model 3 or model 4 3270 display. You also must have anauthority level of MISC8(LISTRDT).

About this task

The ISPF dialog generates and saves a file in the read/write data directory. Thisfile is created so that only the administrator can make updates, and the adapterhas read access.

Note: When a new extended attribute is added, the CA Top Secret Adapter doesnot need to be restarted.


Complete these steps to create the adapter file that maps the CA Top Secretuser-defined ACID fields to the extended attributes.

Procedure1. Log on to TSO on the z/OS operating system.2. From ISPF 6 option, run the following command to start the ISPF dialog:

EXEC 'hlq.SAGTCENU(AGTCCFG)’

The License page is displayed.3. Press Enter to display this screen.

Note: The screens displayed in these tasks are examples; the actual screensdisplayed might differ.

------------------- ISIM CA-TopSecret Adapter Customization -----------Option ===> Location: 1

IBM Security Identity Manager CA-Top Secret Adapter

Initial Customization

1 Initial CustomizationIf this is a new installation, select this option.

2 Customize to support user-defined ACID fieldsIf you have user-defined fields in the FDT, select this option.

X Exit

Note: As you run the dialog, keep in mind the following considerations:v You can return to the previous menu at any time by pressing F3 or END on

the Menu selection screen.v If you press F3 on a data entry screen, the values that you entered are not

saved.4. Select Customize to support user-defined ACID fields. An authority level of

MISC8(LISTRDT) is required.

------------------- ISIM CA-TopSecret Adapter Customization ------Option ===>

user-defined ACID fields

Select the user-defined fields with an S.Type S * on the command line to select all fields.Type SAVE on the command line to save the selected fields andattribute names to the data directory in the read/write home.

USS Adapter read/write home===>CA Top Secret Default Group ACID for adapter ===>

S Field Name Max len Attribute name Comments- ---------- ------- ------------------------------- --------------------

JOBTYPE 1 ERTOPZJOBTYPEPHONE 20 ERTOPZPHONE$LOCKID 20 ERTOPZ$LOCKID$DESKNO 20 ERTOPZ$DESKNO

This panel lists all fields defined in the CA Top Secret FDT that have theattribute USER. The panel shows:v The maximum value length allowed as defined in the FDT.


v A generated attribute name based on the field name.

USS Adapter read/write homeThis parameter must be the read/write home as specified in the Disklocation parameters panel during installation. The user-defined ACIDfields and corresponding attribute names that are selected are writtento the UDF.dat file in the data directory of the read/write home.

CA Top Secret Default Group ACID for adapterThis parameter must be the default group ACID for the adapter asspecified in the Adapter specific parameters panel during installation. Itis used to give the adapter read access to the UDF.dat file.

Tip: You can load previously saved parameters from the initialinstallation by selecting Initial Customization on the first panel, thenLoad Default or Saved Variables.

Attribute nameAttribute names are required for selected fields. The attribute names aremodifiable. The attribute names must be unique, and must not containthe characters '$', '*' or '-'. If the attribute names contain any of thosecharacters, the adapter profile cannot be imported correctly. Thegenerated default attribute names might need to be modified to removeany disallowed characters. The maximum length for an attribute nameis 31 characters.

If the data directory in the USS Adpater read/write home directory alreadycontains an UDF.dat file, then the fields defined in this UDF.dat file arepre-selected in the list of user-defined fields.

------------------- ISIM CA Top Secret Adapter Customization ------Option ===>

user-defined ACID fields

Select the user-defined fields with an S.Type S * on the command line to select all fields.Type SAVE on the command line to save the selected fields andattribute names to the data directory in the read/write home.

USS Adapter read/write home===> /var/ibm/isimcatssCA Top Secret Adapter Default Group ACID for adapter ===> STCUSS

S Field Name Max len Attribute name Comments- ---------- ------- ------------------------------- --------------------S JOBTYPE 1 ERTOPZJOBTYPE Defined in UDF.datS PHONE 20 ERTOPZPHONE Defined in UDF.dat

$LOCKID 20 ERTOPZ$LOCKID$DESKNO 20 ERTOPZ$DESKNO

You might see the following in the comments column:

Invalid attribute nameYou selected a field and the attribute name contains invalid characters.The attribute name must be corrected before it can be saved.

Length discrepancyThe maximum length for the user-defined ACID field that is saved inthe UDF.dat does not match the maximum length for that field in theFDT. This error might occur if the FDT is updated after the UDF.dat filewas created. The maximum length value displayed is the value fromthe FDT. If the UDF.dat file is saved, the FDT value is the value that is


saved. If you change the length of one or more fields in the FDT,optionally, save the UDF.dat file to avoid this error.

Defined in UDF.datIndicates that the user-defined field is in the current UDF.dat file in thespecified read/write home directory.

5. Type S in the selection column to select any additional user-defined ACID fieldsyou want to support. If you want to remove a field that is currently defined inthe UDF.dat, remove the S from the selection column. You can page up anddown if necessary. The selections are maintained. If you want to select alluser-defined fields, type S * on the command line.

6. When you are finished selecting the user-defined ACID fields, type SAVE on thecommand line. The UDF.dat file is saved with read and write permissions forthe administrator and read permission for the group ACID for the adapterspecified.

Note: The administrator is the user who is selecting and saving theuser-defined ACID fields to be supported.

Results

The extended attributes are now defined to the CA Top Secret Adapter. Thefollowing steps describe how to update and import the CA Top Secret Adapterprofile. Importing the profile makes the new attribute definitions available to theIBM Security Identity Manager server.

Copying the CATSSProfile.jar file and extract the filesThe profile JAR file, CATSSProfile.jar, is included in the CA Top Secret Adaptercompressed file that you downloaded from the IBM website.

About this task

The CATSSProfile.jar file contains the following files:v CustomLabels.properties

v erTopzACCOUNTS.xml

v erTopzSERVICE.xml

v resource.def

v schema.dsml

You can modify these files to customize your environment. When you finishupdating the profile JAR file, rebuild the jar and import it in to the IBM SecurityIdentity Manager server. To modify the CATSSProfile.jar file, complete thefollowing steps:

Procedure1. Copy the CATSSProfile.jar file to a temporary Windows folder.2. From the command prompt, extract the contents of the CATSSProfile.jar file

into the temporary directory by running the following command:jar xvf CATSSProfile.jar

The jar command creates the directory CATSSProfile.3. Change the directory to the CATSSProfile subdirectory. For example, run the

following command:cd CATSSProfile


4. Edit the appropriate files.

Updating the schema.dsml fileThe CA Top Secret Adapter schema.dsml file identifies all of the standard CA TopSecret account attributes. Modify this file to identify the new extended attributes.

About this task

The schema.dsml file defines the attributes and objects that the adapter supportsand uses to communicate with the IBM Security Identity Manager server. Toupdate the schema.dsml file, complete the following steps:

Procedure1. Change to the \CATSSProfile directory, where the schema.dsml file is created.2. Edit the schema.dsml file to add an attribute definition for each extended

attributes.The attribute name must match the attribute name registered with ISPF dialog.All attributes must be unique, and assigned a unique Object Identifier (OID).The instance ID for the extended attributes starts from 1000, so the OID for thefirst extended attribute is:<object-identifier>1.3.6.1.4.1.6054.3.155.1.1000</object-identifier>

This numbering prevents duplicate OIDs if the adapter is upgraded to supportnew attributes. For subsequent extended attributes, the OID is incremented by1, based on the last entry in the file. For example, if the last attribute in the fileuses the OID 1.3.6.1.4.1.6054.3.155.1.1008, the next new attribute uses the OID1.3.6.1.4.1.6054.3.155.1.1009. The data type is always a directory string and isdefined using the syntax tags:<syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax>

3. Add each of the new attributes to the account class. For example, add thefollowing attribute definition under the erTopzACCOUNTS section of theschema.dsml file:<attribute ref="erTopzphone" required="false"/><attribute-type single-value = "true" ><name>erTopzPHONE</name><description>Phone Number</description><object-identifier>1.3.6.1.4.1.6054.3.155.1.1000</object-identifier><syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax></attribute-type>

::

<attribute ref = "erTopzPHONE" required = "false" />

Modifying the CustomLabels.properties fileAfter you add the extended attributes to the schema.dsml file, the attributes areavailable for use on the CA Top Secret Adapter form.

About this task

You can modify the attribute names that are in the attribute list. To add theattribute and its corresponding label to the CustomLabels.properties file, completethe following steps:

Procedure1. Change to the \CATSSProfile directory, where the CustomLabels.properties file

is created.2. Edit the CustomLabels.properties file to add the attribute and its

corresponding label using the following format:attribute=label

Note: The attribute name must be in lowercase.For example:## CATSS Adapter Labels definitions#ertopzphone=Phone numberertopzemail=eMail

Creating a JAR file and installing the new attributes on the IBMSecurity Identity Manager serverAfter you modify the files, you must import these files, and any other files in theprofile that were modified for the adapter. The files must be imported into the IBMSecurity Identity Manager for the changes to take effect.

About this task

To install the new attributes, create a JAR file containing the updated files in thetemporary windows director:

Procedure1. Navigate to the parent directory of CATSSProfile, then run the following jar

command:cd ..jar cvf CATSSProfile.jar CATSSProfile

2. Import the CATSSProfile.jar file into the IBM Security Identity Manager server.

Note: If you are upgrading an existing adapter profile, the new adapter profileschema is not reflected immediately. If you want the updates to take effectimmediately, stop and start the IBM Security Identity Manager server.

Optional modification of the adapter formAfter the changes are available in the IBM Security Identity Manager server, youcan modify the CA Top Secret Adapter forms to use the new extended attributes.

For example:<formElement direction="inherit" name="data.ertopzphone" label="$ertopzphone"><input maxlength="40" name="data.ertopzphone" type="text" size="40"/>

<constraint><type>MAX_LENGTH</type><parameter>40</parameter>

</constraint></formElement>

The attributes do not need to be added to the CA Top Secret form unless you wantthem to be available. The attributes are returned during reconciliations unless youexplicitly exclude them. For more information about how to modify the adapterform, see the IBM Security Identity Manager product documentation.


http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.tsiem.doc%2Fwelcome.html

Comments with the CA Top Secret command stringYou might want to send a comment with the CA Top Secret command strings forauditing purposes.

For example:TSS CREATE(USER1) TYPE(USER) DEPT(DEPT1) PASSWORD(xxxx) NAME(IBM user) /*Request number 12345 */

You can use the attribute ertopzcomment to define a CA Top Secret commandcomment. For the above example, you would define:ertopzcomment=Request number 12345

ertopzcomment is a send only attribute and is only available with add and modifyrequests. ertopzcomment is of type string and with a maximum length of 80. Ifmore than 80 characters are defined, the string is truncated to 80 characters. Thecharacters ‘*/’ are not allowed. If the characters ‘*/’ are specified in the commentstring, the add or modify request might fail.

Note: ertopzcomment is not available on the release version of the account formerTopzACCOUNTS.xml. There is an example, in comments, of the ertopzcommentattribute displayed on a new tab Non CA-TSS attributes. You can editerTopzACCOUNTS.xml, remove the comment delimiters, re-create a new profile JARfile, and import the new profile as required.

Configuration of SSL authentication for the adapterYou can provide SSL authentication, certificates, and SSL authentication enablementwith the certTool utility.

To establish a secure connection between the adapter and the IBM Security IdentityManager server, configure the adapter and the IBM Security Identity Managerserver. Use the Secure Sockets Layer (SSL) authentication with the defaultcommunication protocol, DAML. By configuring the adapter for SSL, the IBMSecurity Identity Manager server can verify the identity of the adapter before theserver establishes a secure connection.

You can configure SSL authentication for connections that originate from the IBMSecurity Identity Manager server or from the adapter. The IBM Security IdentityManager server initiates a connection to the adapter to set or retrieve the value ofa managed attribute on the adapter. Depending on the security requirements ofyour environment, you might configure SSL authentication for connections thatoriginate from the adapter. For example, adapter events can notify the IBMSecurity Identity Manager server of changes to attributes on the adapter. In thiscase, configure SSL authentication for web connections that originate from theadapter to the web server used by the IBM Security Identity Manager server.

In a production environment, you must enable SSL security. If an externalapplication communicates with the adapter (for example, the IBM Security IdentityManager server) and uses server authentication, enable SSL on the adapter.Enabling SSL verifies the certificate that the application presents.

Overview of SSL and digital certificatesAn enterprise network deployment requires secure communication between theIBM Security Identity Manager server and the software products and componentswith which the server communicates.


SSL protocol uses signed digital certificates from a certificate authority (CA) forauthentication. SSL secures communication in a IBM Security Identity Managerconfiguration. SSL provides encryption of the data that is exchanged between theapplications. Encryption makes data that is transmitted over the networkintelligible only to the intended recipient.

Signed digital certificates enable two applications that connect in a network toauthenticate their identity. An application that acts as an SSL server presents itscredentials to verify to an SSL client. The SSL client then verifies that theapplication is the entity it claims to be. You can configure an application that actsas an SSL server so that it requires the application that acts as an SSL client topresent its credentials in a certificate. In this way, the two-way exchange ofcertificates is completed. A third-party certificate authority issues signed certificatesfor a fee. Some utilities, such as those provided by OpenSSL, can also providesigned certificates.

You must install a certificate authority certificate (CA certificate) to verify theorigin of a signed digital certificate. When an application receives a signedcertificate from another application, it uses a CA certificate to verify the certificateoriginator. A certificate authority can be:v Well-known and widely used by other organizations.v Local to a specific region or a company.

Many applications, such as web browsers, use the CA certificates of well-knowncertificate authorities. Using a well-known CA eliminates or reduces the task ofdistributing CA certificates throughout the security zones in a network.

Private keys, public keys, and digital certificatesKeys, digital certificates, and trusted certificate authorities establish and verify theidentities of applications.

SSL uses public key encryption technology for authentication. In public keyencryption, a public key and a private key are generated for an application. Thedata encrypted with the public key can be decrypted only with the correspondingprivate key. Similarly, the data encrypted with the private key can be decryptedonly with the corresponding public key. The private key is password-protected in akey database file. Only the owner can access the private key to decrypt messagesthat are encrypted with the corresponding public key.

A signed digital certificate is an industry-standard method of verifying theauthenticity of an entity, such as a server, a client, or an application. To ensuremaximum security, a third-party certificate authority provides a certificate. Acertificate contains the following information to verify the identity of an entity:

Organizational informationThis certificate section contains information that uniquely identifies theowner of the certificate, such as organizational name and address. Yousupply this information when you generate a certificate with a certificatemanagement utility.

Public keyThe receiver of the certificate uses the public key to decipher encryptedtext that is sent by the certificate owner to verify its identity. A public keyhas a corresponding private key that encrypts the text.

Certificate authority's distinguished nameThe issuer of the certificate identifies itself with this information.


Digital signatureThe issuer of the certificate signs it with a digital signature to verify itsauthenticity. The corresponding CA certificate compares the signature toverify that the certificate is originated from a trusted certificate authority.

Web browsers, servers, and other SSL-enabled applications accept as genuine anydigital certificate that is signed by a trusted certificate authority and is otherwisevalid. For example, a digital certificate can be invalidated for the following reasons:v The digital certificate expired.v The CA certificate that is used to verify that it expired.v The distinguished name in the digital certificate of the server does not match

with the distinguished name specified by the client.

Self-signed certificatesYou can use self-signed certificates to test an SSL configuration before you createand install a signed certificate that is provided by a certificate authority.

A self-signed certificate contains a public key, information about the certificateowner, and the owner signature. It has an associated private key; however, it doesnot verify the origin of the certificate through a third-party certificate authority.After you generate a self-signed certificate on an SSL server application, you must:1. Extract it.2. Add it to the certificate registry of the SSL client application.

This procedure is equivalent to installing a CA certificate that corresponds to aserver certificate. However, you do not include the private key in the file whenyou extract a self-signed certificate to use as the equivalent of a CA certificate.

Use a key management utility to:v Generate a self-signed certificate.v Generate a private key.v Extract a self-signed certificate.v Add a self-signed certificate.

Usage of self-signed certificates depends on your security requirements. To obtainthe highest level of authentication between critical software components, do notuse self-signed certificates or use them selectively. You can authenticateapplications that protect server data with signed digital certificates. You can useself-signed certificates to authenticate web browsers or IBM Security IdentityManager adapters.

If you are using self-signed certificates, you can substitute a self-signed certificatefor a certificate and CA certificate pair.

Certificate and key formatsCertificates and keys are stored in the files with various formats.

.pem formatA privacy-enhanced mail (.pem) format file begins and ends with thefollowing lines:-----BEGIN CERTIFICATE----------END CERTIFICATE-----


A .pem file format supports multiple digital certificates, including acertificate chain. If your organization uses certificate chaining, use thisformat to create CA certificates.

.arm formatAn .arm file contains a base-64 encoded ASCII representation of acertificate, including its public key, not a private key. The .arm file formatis generated and used by the IBM Key Management utility.

.der formatA .der file contains binary data. You can use a.der file for a singlecertificate, unlike a .pem file, which can contain multiple certificates.

.pfx format (PKCS12)A PKCS12 file is a portable file that contains a certificate and acorresponding private key. Use this format to convert from one type of SSLimplementation to another. For example, you can create and export aPKCS12 file with the IBM Key Management utility. You can then importthe file to another workstation with the certTool utility.

SSL authenticationWhen you start the adapter, it loads the available connection protocols.

The DAML protocol is the only available protocol that supports SSL authentication.You can specify DAML SSL implementation.

The DAML SSL implementation uses a certificate registry to store private keys andcertificates. The certTool key and certificate management tool manages the locationof the certificate registry. You do not need to specify the location of the registrywhen you perform certificate management tasks.

For more information about the, see “Changing protocol configuration settings” onpage 26.

Configuring certificates for SSL authenticationYou can configure the adapter for one-way or two-way SSL authentication withsigned certificates.

About this task

Use the certTool utility for these tasks:v “Configuring certificates for one-way SSL authentication”v “Configuring certificates for two-way SSL authentication” on page 73v “Configuring certificates when the adapter operates as an SSL client” on page 74

Configuring certificates for one-way SSL authenticationIn this configuration, the IBM Security Identity Manager server and the IBMSecurity Identity Manager adapter use SSL.

About this task

Client authentication is not set on either application. The IBM Security IdentityManager server operates as the SSL client and initiates the connection. The adapteroperates as the SSL server and responds by sending its signed certificate to the


IBM Security Identity Manager server. The IBM Security Identity Manager serveruses the installed CA certificate to validate the certificate that is sent by theadapter.

In Figure 2, Application A operates as the IBM Security Identity Manager server,and Application B operates as the IBM Security Identity Manager adapter.

To configure one-way SSL, do the following tasks for each application:

Procedure1. On the adapter, complete these steps:

a. Start the certTool utility.b. To configure the SSL-server application with a signed certificate issued by a

certificate authority:1) Create a certificate signing request (CSR) and private key. This step

creates the certificate with an embedded public key and a separateprivate key and places the private key in the PENDING_KEY registryvalue.

2) Submit the CSR to the certificate authority by using the instructions thatare supplied by the CA. When you submit the CSR, specify that youwant the root CA certificate that is returned with the server certificate.

2. On the IBM Security Identity Manager server, perform one of these steps:v If you used a signed certificate that is issued by a well-known CA:

a. Ensure that the IBM Security Identity Manager server stored the rootcertificate of the CA (CA certificate) in its keystore.

b. If the keystore does not contain the CA certificate, extract the CAcertificate from the adapter and add it to the keystore of the server.

v If you generated the self-signed certificate on the IBM Security IdentityManager server, the certificate is installed and requires no additional steps.

v If you generated the self-signed certificate with the key management utilityof another application:a. Extract the certificate from the keystore of that application.b. Add it to the keystore of the IBM Security Identity Manager server.

Related tasks:“Starting certTool” on page 75To start the certificate configuration tool, certTool, for the adapter, complete thesesteps:

CACertificate

A

CertificateA

IBM Security ManagerServer (SSL client)

IBM Security Manageradapter (SSL client)

Truststore

Verify

Hello

Send Certificate A

Figure 2. One-way SSL authentication (server authentication)


Configuring certificates for two-way SSL authenticationIn this configuration, the IBM Security Identity Manager server and adapter useSSL.

Before you begin

Before you do the following procedure, configure the adapter and IBM SecurityIdentity Manager server for one-way SSL authentication. If you use signedcertificates from a CA:v The CA provides a configured adapter with a private key and a signed

certificate.v The signed certificate of the adapter provides the CA certification for the IBM

Security Identity Manager server.

About this task

The adapter uses client authentication. After the adapter sends its certificate to theserver, the adapter requests identity verification from the server. The server sendsits signed certificate to the adapter. Both applications are configured with signedcertificates and corresponding CA certificates.

In Figure 3, the IBM Security Identity Manager server operates as Application Aand the IBM Security Identity Manager adapter operates as Application B.

Procedure1. On the IBM Security Identity Manager server:

a. Create a CSR and private key.b. Obtain a certificate from a CA.c. Install the CA certificate.d. Install the newly signed certificate.e. Extract the CA certificate to a temporary file.

2. On the adapter, add the CA certificate that was extracted from the keystore ofthe IBM Security Identity Manager server to the adapter.

Results

After you configure the two-way certificate, each application has its own certificateand private key. Each application also has the certificate of the CA that issued thecertificates.Related tasks:

C

Verify

CACertificate

A

CertificateB

Send Certificate AVerify

HelloKeystore

CertificateA

CACertificate

B

Security Identity Manageradapter (SSL server)

Security Identity ManagerServer (SSL client)

Truststore

Keystore

Figure 3. Two-way SSL authentication (client authentication)


“Configuring certificates for one-way SSL authentication” on page 71In this configuration, the IBM Security Identity Manager server and the IBMSecurity Identity Manager adapter use SSL.

Configuring certificates when the adapter operates as an SSLclientIn this configuration, the adapter operates as both an SSL client and as an SSLserver.

About this task

This configuration applies if the adapter initiates a connection to the web server(used by the IBM Security Identity Manager server) to send an event notification.For example, the adapter initiates the connection and the web server responds bypresenting its certificate to the adapter.

Figure 4 describes how the adapter operates as an SSL server and an SSL client.When the adapter communicates with the IBM Security Identity Manager server,the adapter sends its certificate for authentication. When the adapter communicateswith the web server, the adapter receives the certificate of the web server.

If the web server is configured for two-way SSL authentication, it verifies theidentity of the adapter. The adapter sends its signed certificate to the web server(not shown in the illustration). To enable two-way SSL authentication between theadapter and web server, do the following process:

Procedure1. Configure the web server to use client authentication.2. Follow the procedure for creating and installing a signed certificate on the web

server.3. Install the CA certificate on the adapter with the certTool utility.4. Add the CA certificate corresponding to the signed certificate of the adapter to

the web server.

What to do next

You might want the software to send an event notification when the adapterinitiates a connection to the web server (used by the IBM Security IdentityManager server). See the IBM Security Identity Manager product documentation.

IBM SecurityIdentityManagerAdapter

IBM SecurityIdentityManagerServer

CA Certificate ACertificate ACA Certificate C

Certificate C

Web server

A B

C

Hello

Certificate A

Hello

Certificate C

Figure 4. Adapter operating as an SSL server and an SSL client


Managing SSL certificates with the certTool utilityYou can use the certTool utility to manage private keys and certificates.

About this task

This section includes instructions for performing the following tasks:v “Starting certTool.”v “Generating a private key and certificate request” on page 77.v “Installing the certificate” on page 78.v “Installing the certificate and key from a PKCS12 file” on page 79.v “Viewing the installed certificate” on page 79.v “Viewing CA certificates” on page 80.v “Installing a CA certificate” on page 79.v “Deleting a CA certificate” on page 80.v “Viewing registered certificates” on page 81.v “Registering a certificate” on page 80.v “Unregistering a certificate” on page 81.

Starting certToolTo start the certificate configuration tool, certTool, for the adapter, complete thesesteps:

Procedure1. Log on to the adapter.2. For UNIX-based operating systems, change to the read/write directory for the

adapter. For example, if the adapter directory is in the default location, type thecommand: cd /var/ibm/isimcatss/bin

3. Type certTool at the prompt. The Main menu is displayed:Main menu - Configuring agent: adapter_name------------------------------A. Generate private key and certificate requestB. Install certificate from fileC. Install certificate and key from PKCS12 fileD. View current installed certificate




X. Quit

Choice:

Results

From the Main menu, you can generate a private key and certificate request, installand delete certificates, register and unregister certificates, and list certificates. Thefollowing sections summarize the purpose of each group of options.


By using the first set of options (A through D), you can generate a CSR and installthe returned signed certificate on the adapter.

A. Generate private key and certificate requestGenerate a CSR and the associated private key that is sent to the certificateauthority. For more information about option A, see “Generating a privatekey and certificate request” on page 77.

B. Install certificate from fileInstall a certificate from a file. This file must be the signed certificatereturned by the CA in response to the CSR that is generated by option A.For more information about option B, see “Installing the certificate” onpage 78.

C. Install certificate and key from a PKCS12 fileInstall a certificate from a PKCS12 format file that includes both the publiccertificate and a private key. If options A and B are not used to obtain acertificate, the certificate that you use must be in PKCS12 format. For moreinformation about option C, see “Installing the certificate and key from aPKCS12 file” on page 79.

D. View current installed certificateView the certificate that is installed on the workstation where the adapteris installed. For more information about option D, see “Viewing theinstalled certificate” on page 79.

The second set of options enables you to install root CA certificates on the adapter.A CA certificate validates the corresponding certificate presented by a client, suchas the server.

E. List CA certificatesShow the installed CA certificates. The adapter communicates only withservers whose certificates are validated by one of the installed CAcertificates.

F. Install a CA certificateInstall a new CA certificate so that certificates generated by this CA can bevalidated. The CA certificate file can either be in X.509 or PEM encodedformats. For more information about how to install a CA certificate, see“Installing a CA certificate” on page 79.

G. Delete a CA certificateRemove one of the installed CA certificates. For more information abouthow to delete a CA certificate, see “Deleting a CA certificate” on page 80.

Options H through K apply to adapters that must authenticate the application towhich the adapter is sending information. An example of an application is the IBMSecurity Identity Manager server or the web server. Use these options to registercertificates on the adapter. For IBM Security Identity Manager version 4.5 or earlier,register the signed certificate of the IBM Security Identity Manager server with anadapter to enable client authentication on the adapter. If you do not upgrade anexisting adapter to use CA certificates, you must register the signed certificatepresented by the server with the adapter.

If you configure the adapter for event notification or enable client authentication inDAML, you must install the CA certificate corresponding to the signed certificateof the IBM Security Identity Manager server. Use option F, Install a CA certificate.


H. List registered certificatesList all registered certificates that are accepted for communication. Formore information about listing registered certificates, see “Viewingregistered certificates” on page 81.

I. Register a certificateRegister a new certificate. The certificate for registration must be in Base 64encoded X.509 format or PEM. For more information about registeringcertificates, see “Registering a certificate” on page 80.

J. Unregister a certificateUnregister (remove) a certificate from the registered list. For moreinformation about unregistering certificates, see “Unregistering acertificate” on page 81.

K. Export certificate and key to PKCS12 fileExport a previously installed certificate and private key. You are promptedfor the file name and a password for encryption. For more informationabout exporting a certificate and key to a PKCS12 file, see “Exporting acertificate and key to PKCS12 file” on page 82.

Generating a private key and certificate requestUse the certTool utility to generate a private key and certificate request for securecommunication between the adapter and IBM Security Identity Manager.

About this task

A certificate signing request is an unsigned certificate that is a text file. When yousubmit an unsigned certificate to a certificate authority, the CA signs the certificatewith the private digital signature that is included in their corresponding CAcertificate. When the certificate signing request (CSR) is signed, it becomes a validcertificate. A CSR contains information about your organization, such as theorganization name, country, and the public key for your web server.

To generate a CSR file, take these steps:

Procedure1. At the Main menu of the certTool utility, type A to display the following

message and prompt:

Enter values for certificate request (press enter to skip value)----------------------------------------------------------------

2. At Organization, type your organization name and press Enter.3. At Organizational Unit, type the organizational unit and press Enter.4. At Agent Name, type the name of the adapter for which you are requesting a

certificate and press Enter.5. At Email, type the email address of the contact person for this request and

press Enter.6. At State, type the state that the adapter is in and press Enter. For example,

type TX if the adapter is in Texas. Some certificate authorities do not accepttwo letter abbreviations for states. In this case, type the full name of the state.

7. At Country, type the country that the adapter is in and press Enter.8. At Locality, type the name of the city that the adapter is in and press Enter.9. At Accept these values, do one of the following actions and press Enter:

v Type Y to accept the displayed values.


v Type N and specify different values.

The private key and certificate request are generated after the values areaccepted.

10. At Enter name of file to store PEM cert request, type the name of the file andpress Enter. Specify the file that you want to use to store the values youspecified in the previous steps.

11. Press Enter to continue. The certificate request and input values are written tothe file you specified. The file is copied to the adapter data directory and theMain menu is displayed again.

What to do next

You can now request a certificate from a trusted CA by sending the .pem file thatyou generated to a certificate authority vendor.

Example of certificate signing requestYour CSR file looks similar to the following example:-----BEGIN CERTIFICATE REQUEST-----MIIB1jCCAT8CAQAwgZUxEjAQBgNVBAoTCWFjY2VzczM2MDEUMBIGA1UECxMLZW5naW5lZXJpbmcxEDAOBgNVBAMTB250YWdlbnQxJDAiBgkqhkiG9w0BCQEWFW50YWdlbnRAYWNjZXNzMzYwLmNvbTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDzANBgNVBAcTBklydmluZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAmR6AcPnwf6hLLc72BmUkAwaXcebtxCoCnnTH9uc8VuMHPbIMAgjuC4s91hPrilG7UtlbOfy6X3R3kbeR8apRR9uLYrPIvQ1b4NK0whsytij6syCySaFQIB6V7RPBatFr6XQ9hpsARdkGytZmGTgGTJ1hSS/jA6mbxpgmttz9HPECAwEAAaAAMA0GCSqGSIb3DQEBAgUAA4GBADxA1cDkvXhgZntHkwT9tCTqUNV9sim8N/U15HgMRh177jVaHJqbN1Er46vQSsOOOk4z2i/XwOmFkNNTXRVl9TLZZ/D+9mGZcDobcO+lbAKlePwyufxKXqdpu3d433H7xfJJSNYLYBFkrQJesITqKft0Q45gIjywIrbctVUCepL2-----END CERTIFICATE REQUEST-----

Installing the certificateUse the certTool utility to install the certificate on the adapter.

About this task

After you receive your certificate from your trusted CA, you must install it in theregistry of the adapter.

To install the certificate, complete these steps:

Procedure1. If you received the certificate as part of an email message, take the following

actions:a. Copy the text of the certificate to a text file.b. Copy that file to the read/write data directory of the adapter. For

example:/var/ibm/isimagent/data2. At the Main menu of the certTool utility, type B. The following prompt is

displayed:Enter name of certificate file:------------------------------------------------

3. At Enter name of certificate file, type the full path to the certificate file andpress Enter.


Results

The certificate is installed in the registry for the adapter, and the Main menu isdisplayed again.

Installing the certificate and key from a PKCS12 fileIf the certTool utility did not generate a CSR to obtain a certificate, you mustinstall both the certificate and private key.

About this task

Store the certificate and the private key in a PKCS12 file. The CA sends a PKCS12file that has a .pfx extension. The file might be a password-protected file and itincludes both the certificate and private key.

To install the certificate from the PKCS12 file, complete these steps:

Procedure1. Copy the PKCS12 file to the data directory of the adapter.2. At the Main menu of the certTool utility, type C. The following prompt is

displayed:Enter name of PKCS12 file:------------------------------------------------

3. At Enter name of PKCS12 file, type the full path to the PKCS12 file that hasthe certificate and private key information and press Enter. You might typeDamlSrvr.pfx.

4. At Enter password, type the password to access the file and press Enter.

Results

After you install the certificate and private key in the adapter registry, the certToolutility displays the Main menu.

Viewing the installed certificateTo list the certificate on your workstation, type D at the Main Menu of certTool.

About this task

The utility displays the installed certificate and the Main Menu. The followingexample shows an installed certificate:The following certificate is currently installed.Subject: c=US,st=California,l=Irvine,o=DAML,cn=DAML Server

Installing a CA certificateUse the certTool utility to install root CA certificates on the adapter.

About this task

If you use client authentication, you must install a CA certificate that is providedby a certificate authority vendor.

To install a CA certificate that was extracted in a temporary file, complete thefollowing steps:


Procedure1. At Main Menu, type F (Install a CA certificate). The following prompt is

displayed:Enter name of certificate file:

2. At Enter name of certificate file, type the name of the certificate file, such asCAcert.der and press Enter. The certificate file opens and the following promptis displayed:[email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=EngInstall the CA? (Y/N)

3. At Install the CA, type Y to install the certificate and press Enter.

Results

The certificate file is installed in the DamlCACerts.pem file.

Viewing CA certificatesUse the certTool utility to view a private key and certificate that are installed forthe adapter.

About this task

The certTool utility installs only one certificate and one private key. You can list theCA certificate on the adapter.

Procedure

Type E at the Main Menu prompt.

Results

The certTool utility displays the installed CA certificates and the Main menu. Thefollowing example shows an installed CA certificate:Subject: o=IBM,ou=SampleCACert,cn=TestCAValid To: Wed Jul 26 23:59:59 2006

Deleting a CA certificateYou can delete a CA certificate from the adapter directories.

Procedure1. At Main Menu, type G to display a list of all CA certificates that are installed

on the adapter.0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=SupportEnter number of CA certificate to remove:

2. At Enter number of CA certificate to remove, type the number of the CAcertificate that you want to remove and press Enter.

Results

After you delete the CA certificate from the DamlCACerts.pem file, the certToolutility displays the Main menu.

Registering a certificateUse the certTool utility to register certificates on the adapter when the adaptermust authenticate to an application.


About this task

Adapters that must authenticate to the application to which it is sendinginformation must have a registered certificate. An example of an application is theIBM Security Identity Manager server or the web server. Use this task to registercertificates on the adapter.

For IBM Security Identity Manager version 4.5 or earlier, register the signedcertificate of the IBM Security Identity Manager server with an adapter to enableclient authentication on the adapter. You might not upgrade an existing adapter touse CA certificates. In this case, you must register the signed certificate that ispresented by the server with the adapter.

Procedure1. At the Main Menu prompt, type I to display the following prompt:

Enter name of certificate file:

2. At Enter name of certificate file, type the name of the certificate file that youwant to register and press Enter. The subject of the certificate is displayed, anda prompt is [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=EngRegister this CA? (Y/N)

3. At Register this CA, type Y to register the certificate, and press Enter.

Results

After you register the certificate to the adapter, the certTool displays the Mainmenu.

Viewing registered certificatesThe adapter accepts only the requests that present a registered certificate whenclient validation is enabled.

Procedure

To view a list of all registered certificates, type H on the Main Menu.The utility displays the registered certificates and the Main Menu. The followingexample shows a list of the registered certificates:0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support

Unregistering a certificateYou can unregister a certificate for the adapter.

Procedure1. At the Main Menu prompt, type J to display the registered certificates. The

following example shows a list of registered certificates:0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support

2. Type the number of the certificate file that you want to unregister and [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=EngUnregister this CA? (Y/N)

3. At Unregister this CA, type Y to unregister the certificate and press Enter.


Results

After you remove the certificate from the list of registered certificate for theadapter, the certTool utility displays the Main menu.

Exporting a certificate and key to PKCS12 fileYou can export a certificate and key to a PKCS12 file.

Procedure1. At the Main Menu prompt, type K to display the following prompt:

Enter name of PKCS12 file:

2. At Enter name of PKCS12 file, type the name of the PKCS12 file for theinstalled certificate or private key and press Enter.

3. At Enter Password, type the password for the PKCS12 file and press Enter.4. At Confirm Password, type the password again and press Enter.

Results

After you export the certificate or private key to the PKCS12 file, the certTooldisplays the Main menu.


Chapter 5. Troubleshooting of the CA Top Secret Adaptererrors

Troubleshooting is the process of determining why a product does not function asit is designed to function.

This topic provides information and techniques for identifying and resolvingproblems related to the CA Top Secret Adapter.

Note: If a problem is encountered, enable all levels of activity logging (debug,detail, base, and thread). The adapter log contains the main source oftroubleshooting information. See “Changing activity logging settings” on page 47.

Table 21. Error messages, warnings, and corrective actions

Error message orwarning

Additional warnings,messages, or information Corrective action

CTGIMU107W

The connection to thespecified service cannotbe established. Verify theservice information, andtry again.

An IO error occurredwhile sending a request.Error: Connectionrefused: connect

Ensure that the adapter service isrunning. For more informationabout starting the adapter service,see “Starting and stopping theadapter” on page 16.

The adapter returned anerror status for a bindrequest. Status code:invalid credentialsAdapter error message:Authentication Failed

Check the adapter authentication IDand password match the installedvalues. See the screen forAdapter-specific parameters in thetask“Running the ISPF dialog” onpage 8.

An IO error occurredwhile sending a request.Error: com.ibm.daml.jndi.JSSESocketConnection.HANDSHAKE_FAILED:

If SSL is enabled check theconfiguration. See “Configuration ofSSL authentication for the adapter”on page 68. The adapter logcontains details about thecertificates loaded duringinitialization.

APPC error in UserAdd. This error occurs when the adaptercannot establish an APPCtransaction. The request is failed.See the MVS system log and theadapter log for more information.

catssAdd: Unable toestablish APPCcommand environment.

This error occurs when the adaptercannot establish an APPCtransaction. The request is failed.See the MVS system log and theadapter log for more information.


Table 21. Error messages, warnings, and corrective actions (continued)



catssAdd: Invalid TYPEtype for creation of useruserid.

This error occurs when a User addrequest is submitted, however, thevalue for the erTopzTYPE attributeis incorrect. The valid values for theerTopzTYPE attribute are:

v ZCA

v VCA

v DCA

v USER

catssAdd: User useridadd Successful. Someattributes could not bemodified.

This warning occurs when a user iscreated, however, some additionalattributes failed. See the adapter logfile for more information.

catssAdd: MissingZONE, DIVISION, orDEPARTMENT for useruserid, Type type.

For a particular type of user, thecorresponding ZONE, DIVISION, orDEPARTMENT is missing. See theadapter log file for moreinformation.

catssAdd: MissingPASSWORD for accountuserid.

Ensure that you specify a passwordduring a user add request.

catssAdd: MissingNAME for user userid.

Ensure that you specify a name forthe user during a user add request.

catssAdd: Missing TYPEfor user userid.

Ensure that you specify a type forthe user during a user add request.

APPC error in UserDel. This error occurs when the adaptercannot establish an APPCtransaction. The request is failed.See the MVS system log and theadapter log for more information.

catssDelete: Unable toestablish commandenvironment.


catssModify: Unable toestablish APPCcommand environment.


catssModify: Someattributes unsuccessful.

This warning occurs when a user ismodified, however, some additionalattributes failed. See the adapter logfile for more information.

catssModify: Allattributes unsuccessful.

The modify request failed to set theattributes on the managed resource.See the adapter log file for moreinformation.


Table 21. Error messages, warnings, and corrective actions (continued)



catssSearch.catssSearchunexpected APPC error.


catssSearch:Reconciliation did notreturn at least 1 ACID.

During the reconciliation request,no ACIDs were returned. See theMVS system log and the adapterlog for more information.

catssSearch: Unable tocreate APPC transaction.


Techniques for troubleshooting problemsTroubleshooting is a systematic approach to solving a problem. The goal oftroubleshooting is to determine why something does not work as expected andhow to resolve the problem. Certain common techniques can help with the task oftroubleshooting.

The first step in the troubleshooting process is to describe the problem completely.Problem descriptions help you and the IBM technical-support representative knowwhere to start to find the cause of the problem. This step includes asking yourselfbasic questions:v What are the symptoms of the problem?v Where does the problem occur?v When does the problem occur?v Under which conditions does the problem occur?v Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem,which can then lead you to a problem resolution.

What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is “What is theproblem?” This question might seem straightforward; however, you can break itdown into several more-focused questions that create a more descriptive picture ofthe problem. These questions can include:v Who, or what, is reporting the problem?v What are the error codes and messages?v How does the system fail? For example, is it a loop, hang, crash, performance

degradation, or incorrect result?

Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of themost important steps in resolving a problem. Many layers of technology can exist

Chapter 5. Troubleshooting of the CA Top Secret Adapter errors 85

between the reporting and failing components. Networks, disks, and drivers areonly a few of the components to consider when you are investigating problems.

The following questions help you to focus on where the problem occurs to isolatethe problem layer:v Is the problem specific to one platform or operating system, or is it common

across multiple platforms or operating systems?v Is the current environment and configuration supported?v Do all users have the problem?v (For multi-site installations.) Do all sites have the problem?

If one layer reports the problem, the problem does not necessarily originate in thatlayer. Part of identifying where a problem originates is understanding theenvironment in which it exists. Take some time to completely describe the problemenvironment, including the operating system and version, all correspondingsoftware and versions, and hardware information. Confirm that you are runningwithin an environment that is a supported configuration; many problems can betraced back to incompatible levels of software that are not intended to run togetheror have not been fully tested together.

When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for thosecases that are one-time occurrences. You can most easily develop a timeline byworking backward: Start at the time an error was reported (as precisely as possible,even down to the millisecond), and work backward through the available logs andinformation. Typically, you need to look only as far as the first suspicious eventthat you find in a diagnostic log.

To develop a detailed timeline of events, answer these questions:v Does the problem happen only at a certain time of day or night?v How often does the problem happen?v What sequence of events leads up to the time that the problem is reported?v Does the problem happen after an environment change, such as upgrading or

installing software or hardware?

Responding to these types of questions can give you a frame of reference in whichto investigate the problem.

Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problemoccurs is an important part of troubleshooting. These questions about yourenvironment can help you to identify the root cause of the problem:v Does the problem always occur when the same task is being performed?v Does a certain sequence of events need to happen for the problem to occur?v Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment inwhich the problem occurs and correlate any dependencies. Remember that justbecause multiple problems might have occurred around the same time, theproblems are not necessarily related.


Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can bereproduced. Typically, when a problem can be reproduced you have a larger set oftools or procedures at your disposal to help you investigate. Consequently,problems that you can reproduce are often easier to debug and solve.

However, problems that you can reproduce can have a disadvantage: If theproblem is of significant business impact, you do not want it to recur. If possible,re-create the problem in a test or development environment, which typically offersyou more flexibility and control during your investigation.v Can the problem be re-created on a test system?v Are multiple users or applications encountering the same type of problem?v Can the problem be re-created by running a single command, a set of

commands, or a particular application?

For information about obtaining support, see Appendix E, “Support information,”on page 113.

Troubleshooting APPC problemsUse this procedure to troubleshoot errors encountered with the Advanced Programto Program Communication.

Procedure1. Ensure that the APPC/MVS and the ASCH address spaces are started. For

example, issue these commands:S APPC,APPC=00,SUB=MSTRS ASCH,ASCH=00,SUB=MSTR

2. Ensure that APPC and ASCH are using the members APPCPMxx andASCHPMxx as expected. You can check the system log to see which membersare loaded.

3. Check that the scheduler class specified in the installation is defined to theAPPC/MVS transaction scheduler. The command D ASCH,ALL shows all theactive classes. These commands display the active parameters for APPC andASCH:D APPC,LU,ALLD ASCH,ALLD NET,E,ID=ISIMORIGD NET,E,ID=ISIMDEST

4. Check that the APPCLU profile is correctly defined to CA Top Secret. See“Configuration of CA Top Secret access” on page 21.

5. Check the z/OS System log for CA Top Secret authorization error messagesaround the time of the APPC error. An APPC error might be caused by a lackof authorization to the installation LOAD and EXEC data sets.

Note: If the requester ID on the service form is being used, then you mustpermit the relevant authority for the SURROGAT resource. See “Surrogateuser” on page 23.

Adapter log filesWhen the adapter is initially configured, a default directory is selected to store thelog files, which contain activity from the adapter.


The log files are kept in the z/OS UNIX System Services file system, under theinstallation path of the adapter, in the read/write log/ subdirectory.

The adapter log name is the adapter instance name, followed by an extension of.log. When the extension is .log, it is the current log file. Old log files have adifferent extension, for example, .log_001, .log_002, and so on.

For example, an installation path name for the read/write directory is /usr/isim,and the adapter name configured is CATSSAgent. The log files are then in the/usr/isim/log/ directory. There are one or more files named CATSSAgent.log,CATSSAgent.log_001, CATSSAgent.log_002, and so on.

You might use the z/OS UNIX System Services obrowse command tail, or anyother UNIX-based utility to inspect these adapter logs.

The size of a log file, the number of log files, the directory path, and the detailedlevel of logging are configured with the agentCfg program. For more information,see “Adapter configuration for IBM Security Identity Manager” on page 21.

CA Top Secret/SSL adapter information to be gathered for supportrequests

This information assumes specifications for VTAM APPLIDs and user IDsindicated in the installation guide.

Replace these APPLIDs and user IDs with those IDs you have selected for theadapter installation.v The CA Top Secret Adapter log file, from the z/OS UNIX System Services file

system.v An excerpt from the MVS SYSTEM log, from the same time frame as the failure.v A screen capture of the ITIM service form, describing the connection to this

adapter.v A display from the adapter utility agentCfg describing the adapter parameters:

F. Registry Settings. -> A. Modify Non-encrypted registry settings

v The results from MVS console command: D APPC,LU,ALL

v The results from MVS console command: D ASCH,ALL

v If the APPC/MVS logical units are left unspecified, then only one logical unit isused for both sides of the conversation. The LU to be displayed is defined inAPPCPMxx with the BASE keyword, indicating it is the BASE LU. The baseluname is indicated by the command D APPC,LU,ALL . From the resulting display,one of the LUs is indicated as BASE=YES.– The results from MVS console command: D NET,E,ID=baselu

v If the APPC/MVS logical units are specifically defined to the adapter:– The results from MVS console command: D NET,E,ID=ISIMORIG

– The results from MVS console command: D NET,E,ID=ISIMDEST

v The APPC/MVS configuration definition (SYS1.PARMLIB(APPCPMxx) member.(Replace the data set name and member name suffix with those that definewhere the client stores this definition.)

v The APPC/MVS Address space scheduler definition(SYS1.PARMLIB(ASCHPMxx) member. (Replace the data set name and membername suffix with those that define where the client stores this definition.)


v The VTAM APPL definitions for ISIMORIG and ISIMDEST, from the VTAMLSTdata set. If the BASE LU is the only LU utilized, include the VTAMLSTdefinition for this LU.

v The VTAM mode table entry or entries used in the VTAM APPL definitions. Ifan IBM standard mode table entry from ISTINCLM is used, this information isnot necessary.

v The results from the following job (include all the output produced). A CA TopSecret administrator with authority to view all the indicated profiles must runthis job. Specify your VTAM Network ID where netid is shown. (You can findthe NETID from the display command D NET,E,ID=ISTNOP, where the lineindicating message IST599I indicates the netid.hostpu.)//TSSLIST JOB ACCT,IBM,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID//TMP EXEC PGM=IKJEFT01,REGION=0K//SYSTSPRT DD SYSOUT=*//SYSTSIN DD */* LIST THE APPCLU PROFILES */TSS LIST(APPCLU) DATA(ALL,SESSKEY)/* LIST THE STC RECORD */TSS LIST(STC) DATA(ALL)/* LIST THE ADAPTER ACID */TSS LIST(ITIAGNT) DATA(ALL,PASSWORD)/* LIST THE APPC/MVS ACID */TSS LIST(APPC) DATA(ALL,PASSWORD)

v The results from the following job (all the output produced, including the JCL).Replace the transaction data set file with your installation VSAM file name, andmodify the job statement as necessary://APPCLIST JOB ACCT,IBM,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID//ATBSDFMU EXEC PGM=ATBSDFMU//SYSPRINT DD SYSOUT=*//SYSSDLIB DD DISP=SHR,// DSN=your.appc.trans.action.profile.VSAM.dataset//SYSSDOUT DD SYSOUT=*//SYSIN DD *

TPKEYSTPRETRIEVE

TPNAME(ISIMTCMD)SYSTEM

TPRETRIEVETPNAME(ISIMTREC)SYSTEM

See “Contacting IBM Support” on page 114 for more information.


Chapter 6. Upgrading the adapter

For specific instructions about upgrading the adapter, see the adapter release notes.


Chapter 7. Uninstalling the adapter

Uninstalling the adapter involves tasks, such as removing the started task JCL andremoving the directories from the UNIX System Services (USS) environment.

About this task

To uninstall the adapter, perform the following steps:

Procedure1. Stop the adapter, if it is running. See “Starting and stopping the adapter” on

page 16.2. Remove the started task JCL from the system procedure library.3. Remove the read-only and read/write directories from the z/OS USS

environment.4. Remove the CNTL, EXEC and LOAD libraries that are related to the adapter.5. Remove the ISPF dialog libraries for customization.


Appendix A. Adapter attributes

You can use the attributes that are available on the adapter account form.

Table 22. Account form attributes

AttributeDatatype

Maximumlength

Singleormultiplevalue

Readorwrite

Required?

Commands

eraccountstatus True,False,or Null

8 Single RW No To add:

TSS ADD(id) SUSPEND

To delete:

TSS REM(id) ASUSPED

ertopzacidauth String 8 Multiple RW No To add:

TSS ADMI(id) ACID(val)

To delete:

TSS DEA(id) ACID(val)

ertopzadminlistdata

String 8 Multiple RW No To add:

TSS ADMI(id) DATA(val)

To delete:

TSS DEA(id) DATA(val)

ertopzassize Integer 10 Single RW No To add:

TSS ADD(id) ASSIZE(val)

To delete:

TSS REM(id) ASSIZE

ertopzasuspend True,False,or Null


TSS ADD(id) SUSPEND

To delete:

TSS REM(id) ASUSPEND

ertopzaudit True,False,or Null


TSS ADD(id) AUDIT

To delete:

TSS REM(id) AUDIT

ertopzconsole True,False,or Null


TSS ADD(id) CONSOLE

To delete:

TSS REM(id) CONSOLE

ertopzdepartmtacid

String 8 Single RW No To add:

TSS CREATE(id) DEPT(val)


Table 22. Account form attributes (continued)

AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzdfltgrp String 8 Single RW No To add:

TSS REP(id) DFLTGRP(val)

To delete:

TSS REM(id) DFLTGRP

ertopzdivisionacid


TSS CREATE(id) DIVISION(val)

ertopzdufupd True,False,or Null


TSS ADD(id) DUFUPD

To delete:

TSS REM(id) DUFUPD

ertopzdufxtr True,False,or Null


TSS ADD(id) DUFXTR

To delete:

TSS REM(id) DUFXTR

ertopzexpirationdate

Date(LDAPdate/time)


TSS ADD(id) UNTIL(val)

To delete:

TSS REM(id) EXPIRE

ertopzfacility String 8 Multiple RW No To add:

TSS ADD(id) FACILITY(val)

To delete:

TSS REM(id) FACILITY(val)

ertopzgid Integer 10 Single RW No -

ertopzgroup String 8 Multiple RW No To add:

TSS ADD(id) GROUP(val)

To delete:

TSS REM(id) GROUP(val)

ertopzinstdata String 255 Single RW No To add:

TSS REP(id) INSTDATA(’val’)

To delete:

TSS REM(id) INSTDATA



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzlanguage String 1 Single RW No To add:

TSS ADD(id) LANGUAGE(val)

To delete:

TSS REM(id) LANGUAGE

ertopzlds True,False,or Null


TSS ADD(id) LDS

To delete:

TSS REM(id) LDS

ertopzmastfac String 8 Single RW No To add:

TSS ADD(id) MASTFAC(val)

To delete:

TSS REM(id) MASTFAC

ertopzmisc1 String 8 Multiple RW No To add:

TSS ADMI(id) MISC1(val)

To delete:

TSS DEA(id) MISC1(val)



To delete:




To delete:




To delete:




To delete:


Appendix A. Adapter attributes 97


AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands



To delete:




To delete:




To delete:


ertopzmmaparea Integer 10 Single RW No To add:

TSS ADD(id) MMAPAREA(val)

To delete:

TSS REM(id) MMAPAREA

ertopzmro True,False,or Null


TSS ADD(id) MRO

To delete:

TSS REM(id) MRO

ertopzmultipw True,False,or Null


TSS ADD(id) MULTIPW

To delete:

TSS REM(id) MULTIPW

ertopzname String 32 Single RW No To add:

TSS REP(id) NAME(’val’)

ertopznoadsp True,False,or Null


TSS ADD(id) NOADSP

To delete:

TSS REM(id) NOADSP

ertopznoats True,False,or Null


TSS ADD(id) NOATS

To delete:

TSS REM(id) NOATS



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopznodsnchk

True,False,or Null


TSS ADD(id) NODSNCHK

To delete:

TSS REM(id) NODSNCHK

ertopznolcfchk True,False,or Null


TSS ADD(id) NOLCFCHK

To delete:

TSS REM(id) NOLCFCHK

ertopznoomvsdf True,False,or Null


TSS ADD(id) NOOMVSDF

To delete:

TSS REM(id) NOOMVSDF

ertopznopwchg True,False,or Null


TSS ADD(id) NOPWCHG

To delete:

TSS REM(id) NOPWCHG

ertopznoreschk True,False,or Null


TSS ADD(id) NORESCHK

To delete:

TSS REM(id) NORESCHK

ertopznosubchk True,False,or Null


TSS ADD(id) NOSUBCHK

To delete:

TSS REM(id) NOSUBCHK

ertopznosuspen True,False,or Null


TSS ADD(id) NOSUSPEND

To delete:

TSS REM(id) NOSUSPEND

ertopznovmdchk True,False,or Null


TSS ADD(id) NOVMDCHK

To delete:

TSS REM(id) NOVMDCHK

ertopznovolchk True,False,or Null


TSS ADD(id) NOVOLCHK

To delete:

TSS REM(id) NOVOLCHK



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzoecputm Integer 10 Single RW No To add:

TSS ADD(id) OECPUTM(val)

To delete:

TSS REM(id) OECPUTM

ertopzoefilep Integer 10 Single RW No To add:

TSS ADD(id) OEFILEP(val)

To delete:

TSS REM(id) OEFILEP

ertopzidcard True,False,or Null


TSS ADD(id) OIDCARD

To delete:

TSS REM(id) OIDCARD

ertopzomvshome


TSS ADD(id) HOME(’val’)

To delete:

TSS REM(id) HOME

ertopzomvspgm String 68 Single RW No To add:

TSS ADD(id) OMVSPGM(’val’)

To delete:

TSS REM(id) OMVSPGM

ertopzopclass Integer 2 Multiple RW No To add:

TSS ADD(id) OPCLASS(val)

To delete:

TSS REM(id) OPCLASS(val)

ertopzopident String 3 Single RW No To add:

TSS ADD(id) OPIDENT(val)

To delete:

TSS REM(id) OPIDENT

ertopzopprty Integer 3 Single RW No To add:

TSS ADD(id) OPPRTY(val)

To delete:

TSS REM(id) OPPRTY



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzpassexpinvl

Integer 3 Single RW No To add:

TSS REP(id) PASSWORD(*,val)

To delete:

TSS REM(id) PASSWORD(*,0)

ertopzhrsexpinvl

Integer 3 Single RW No To add:

TSS ADD(id) PHRASE(*,val)

To delete:

TSS REM(id) PHRASE(*,0)

ertopzprocuser Integer 10 Single RW No To add:

TSS ADD(id) PROCUSER(val)

To delete:

TSS REM(id) PROCUSER

ertopzprofile 12 Multiple RW No To add:

TSS ADD(id) PROFILE(val)

To delete:

TSS REM(id) PROFILE(val)

ertopzpswdphr True,False,or Null


TSS ADD(id) PSWDPHR

To delete:

TSS REM(id) PSWDPHR

ertopzrstdacc True,False,or Null


TSS ADD(id) RSTDACC

To delete:

TSS REM(id) RSTDACC

ertopzscopez String 8 Multiple RW No To add:

TSS ADMI(id) SCOPE(val)

To delete:

TSS DEA(id) SCOPE(val)



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzsctykey Integer 3 Mutliple RW No To add:

TSS ADD(id) SCTYKEY(val)

To delete:

TSS REM(id) SCTYKEY(val)

ertopzsitran String 8 Multiple RW No To add:

TSS ADD(id) SITRAN(val)

To delete:

TSS REM(id) SITRAN

ertopzsmsappl String 8 Single RW No To add:

TSS ADD(id) SMSAPPL(val)

To delete:

TSS REM(id) SMSAPPL

ertopzsmsdata String 8 Single RW No To add:

TSS ADD(id) SMSDATA(val)

To delete:

TSS REM(id) SMSDATA

ertopzsmsmgmt String 8 Single RW No To add:

TSS ADD(id) SMSMGMT(val)

To delete:

TSS REM(id) SMSMGMT

ertopzsmsstor String 8 Single RW No To add:

TSS ADD(id) SMSSTOR(val)

To delete:

TSS REM(id) SMSSTOR

ertopzsuspendeduntildate

Date(LDAPdate/time)


TSS ADD(id) SUSPENDUNTIL(val)

To delete:

TSS REM(id) ASUSPENDUNTIL



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopzthreads Integer 10 Single RW No To add:

TSS ADD(id) THREADS(val)

To delete:

TSS REM(id) THREADS

ertopztsocommand


TSS ADD(id) TSOCOMMAND(’val’)

To delete:

TSS REM(id) TSOCOMMAND

ertopztsodefprfg Integer 3 Single RW No To add:

TSS ADD(id) TSODEFPRFG(value)

To delete:

TSS REM(id) TSODEFPRFG

ertopztsodest String 8 Single RW No To add:

TSS ADD(id) TSODEST(val)

To delete:

TSS REM(id) TSODEST

ertopztsohclass String 1 Single RW No To add:

TSS ADD(id) TSOHCLASS(val)

To delete:

TSS REM(id) TSOHCLASS

ertopztsojclass String 1 Single RW No To add:

TSS ADD(id) TSOJCLASS(val)

To delete:

TSS REM(id) TSOJCLASS

ertopztsolacct String 40 Single RW No To add:

TSS ADD(id) TSOLACCT(val)

To delete:

TSS REM(id) TSOLACCT



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopztsolproc String 8 Single RW No To add:

TSS ADD(id) TSOLPROC(val)

To delete:

TSS REM(id) TSOLPROC

ertopztsolsize Integer 7 Single RW No To add:

TSS ADD(id) TSOLSIZE(val)

To delete:

TSS REM(id) TSOLSIZE

ertopztsomclass String 1 Single RW No To add:

TSS ADD(id) TSOMCLASS(val)

To delete:

TSS REM(id) TSOMCLASS

ertopztsompw True,False,or Null


TSS ADD(id) TSOMPW

To delete:

TSS REM(id) TSOMPW

ertopztsomsize Integer 7 Single RW No To add:

TSS ADD(id) TSOMSIZE(val)

To delete:

TSS REM(id) TSOMSIZE

ertopztsoopt String 12 Multiple RW No To add:

TSS ADD(id) TSOOPT(val)

To delete:

TSS REM(id) TSOOPT(val)

ertopztsosclass String 1 Single RW No To add:

TSS ADD(id) TSOSCLASS(val)

To delete:

TSS REM(id) TSOSCLASS

ertopztsoudata String 4 Single RW No To add:

TSS ADD(id) TSOUDATA(val)

To delete:

TSS REM(id) TSOUDATA



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands

ertopztsounit String 8 Single RW No To add:

TSS ADD(id) TSOUNIT(val)

To delete:

TSS REM(id) TSOUNIT

ertopztype String 8 NEWE RW No

ertopztzone String 3 Single RW No To add:

TSS ADD(id) TZONE(val)

To delete:

TSS REM(id) TZONE

ertopzuid Integer 10 Single RW No To add:

TSS ADD(id) UID(val)

To delete:

TSS REM(id) UID

ertopzvsuspend True,False,or Null

8 Single RW No -

ertopzwaaccnt String 255 Single RW No To add:

TSS REP(id) WAACCNT(val)

To delete:

TSS REM(id) WAACCNT

ertopzwaaddr1 String 255 Single RW No To add:

TSS REP(id) WAADDR1(val)

To delete:

TSS REM(id) WAADDR1



To delete:

TSS REM(id) WAADDR2



To delete:

TSS REM(id) WAADDR3



AttributeDatatype

Maximumlength


Readorwrite

Required?

Commands



To delete:

TSS REM(id) WAADDR4

ertopzwabldg String 255 Single RW No To add:

TSS REP(id) WABLDG(val)

To delete:

TSS REM(id) WABLDG

ertopzwadept String 255 Single RW No To add:

TSS REP(id) WADEPT(val)

To delete:

TSS REM(id) WADEPT

ertopzwaname String 255 Single RW No To add:

TSS REP(id) WANAME(val)

To delete:

TSS REM(id) WANAME

ertopzwaroom String 255 Single RW No To add:

TSS REP(id) WAROOM(val)

To delete:

TSS REM(id) WAROOM

ertopzzoneacid String 8 Single RW No -

ertopzacidauth String 8 Multiple RW No To add:

TSS ADMI(id) ACID(val)

To delete:

TSS DEA(id) ACID(val)


Appendix B. Registry settings

Take note of the valid registry options, values, and meanings.

Table 23. Registry settings and additional information

Option attribute Default value Valid value Function and meaning Required?

APPCDLU None 1 to 8 characters This is the APPC destinationLogical Unit (LU). If NULL, theadapter uses BASELU.

No

APPCMODE #INTERSC 1 to 8 characters This is the APPC mode table entrythat the adapter uses forconversations.

No

APPCOLU None 1 to 8 characters This is the APPC Originating LU. IfNULL, the adapter uses BASELU.

No

APPCCMD ISIMTCMD 1 to 8 characters This is the APPC transaction namefor the IBM Security IdentityManager command transaction.

No

APPCRECO ISIMTREC 1 to 8 characters This is the APPC transaction namefor the IBM Security IdentityManager reconciliation transaction.

No

PASSEXPIRE TRUE TRUE or FALSE This is the default action that theadapter must perform when theadapter receives a passwordchange request. TRUE indicatesthat passwords must be set asexpired. FALSE indicates thatpasswords must be set asnon-expired.

No


Appendix C. Environment variables

Take note of the valid environment variables, their meanings or usages, and valuesfor the CA Top Secret Adapter.

Table 24. CA Top Secret Adapter environment variables

Environmentvariable Meaning or use Default value Required?

PROTOCOL_DIR Specify the locationof adapter protocolmodules, forexample, the ./libdirectory

LIBPATH No

REGISTRYSpecify the locationof a specific registryfile.

The registry path isthe fully qualifiedpath and the filename of the registryfile. The registryname is the adaptername in upper case,with .dat suffixed tothe name.

Current® workingdirectory.

No

PDU_ENTRY_LIMIT Specify the maximumnumber of accountsthat are kept in themain storage.

3000 No

LIBPATH Specify the locationof the Dynamic LinkLibrary (DLL) and.so files.

- Yes


Appendix D. CA Top Secret user account form

The order of profiles attached to an ACID is important and affects the checking ofthe profile permissions.

To add profiles in a particular order you must add the profile names in the accountform in this manner. The first number indicates the order and the separator is avertical bar character:010|PROFA020|PROFB

The profile names are sorted by number (if necessary) by the adapter and added tothe ACID in that order.

For example, if you then wanted to add PROFC after PROFA and before PROFB,you can add a new profile 015|PROFC. The account form shows:010|PROFA020|PROFB015|PROFC

The account form already lists the previous two profile entries. You can add onlythe new profile entry, ensuring that the leading order number specifies the correctsequence. Alternatively, you can delete the existing list. Select the profiles and clickDelete next to the ‘ACID profile associations' list on the account form. Then addthe complete list in the desired order. For example:001|PROFA002|PROFC003|PROFB

The TSS commands generated from those two examples are:’TSS ADD(USERID) PROFILE(PROFA)’’TSS ADD(USERID) PROFILE(PROFC)’’TSS ADD(USERID) PROFILE(PROFB)’


Appendix E. Support information

You have several options to obtain support for IBM products.v “Searching knowledge bases”v “Obtaining a product fix” on page 114v “Contacting IBM Support” on page 114

Searching knowledge basesYou can often find solutions to problems by searching IBM knowledge bases. Youcan optimize your results by using available resources, support tools, and searchmethods.

About this task

You can find useful information by searching the product documentation for IBMSecurity Identity Manager. However, sometimes you must look beyond the productdocumentation to answer your questions or resolve problems.

Procedure

To search knowledge bases for information that you need, use one or more of thefollowing approaches:1. Search for content by using the IBM Support Assistant (ISA).

ISA is a no-charge software serviceability workbench that helps you answerquestions and resolve problems with IBM software products. You can findinstructions for downloading and installing ISA on the ISA website.

2. Find the content that you need by using the IBM Support Portal.The IBM Support Portal is a unified, centralized view of all technical supporttools and information for all IBM systems, software, and services. The IBMSupport Portal lets you access the IBM electronic support portfolio from oneplace. You can tailor the pages to focus on the information and resources thatyou need for problem prevention and faster problem resolution. Familiarizeyourself with the IBM Support Portal by viewing the demo videos(https://www.ibm.com/blogs/SPNA/entry/the_ibm_support_portal_videos)about this tool. These videos introduce you to the IBM Support Portal, exploretroubleshooting and other resources, and demonstrate how you can tailor thepage by moving, adding, and deleting portlets.

3. Search for content about IBM Security Identity Manager by using one of thefollowing additional technical resources:v IBM Security Identity Manager version 6.0 technotes and APARs (problem

reports).v IBM Security Identity Manager Support website.v IBM Redbooks®.v IBM support communities (forums and newsgroups).

4. Search for content by using the IBM masthead search. You can use the IBMmasthead search by typing your search string into the Search field at the top ofany ibm.com® page.

5. Search for content by using any external search engine, such as Google, Yahoo,or Bing. If you use an external search engine, your results are more likely to


http://www.ibm.com/software/support/isa/

http://www.ibm.com/support/entry/portal/overview/software/tivoli/tivoli_identity_manager

https://www.ibm.com/blogs/SPNA/entry/the_ibm_support_portal_videos

http://www.ibm.com/support/search.wss?rs=644&apar=include&tc=SSTFWV&dc=DB520+D800+D900+DA900+DA800+DB550+D100&dtm&atrn=SWVersion&atrv=5.1

http://www.ibm.com/support/search.wss?rs=644&apar=include&tc=SSTFWV&dc=DB520+D800+D900+DA900+DA800+DB550+D100&dtm&atrn=SWVersion&atrv=5.1

http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html

http://publib-b.boulder.ibm.com/Redbooks.nsf/portals/Tivoli

http://www.ibm.com/software/sysmgmt/products/support/Tivoli_Communities.html

include information that is outside the ibm.com domain. However, sometimesyou can find useful problem-solving information about IBM products innewsgroups, forums, and blogs that are not on ibm.com.

Tip: Include “IBM” and the name of the product in your search if you arelooking for information about an IBM product.

Obtaining a product fixA product fix might be available to resolve your problem.

About this task

You can get fixes by following these steps:

Procedure1. Obtain the tools that are required to get the fix. You can obtain product fixes

from the Fix Central Site. See http://www.ibm.com/support/fixcentral/.2. Determine which fix you need.3. Download the fix. Open the download document and follow the link in the

“Download package” section.4. Apply the fix. Follow the instructions in the “Installation Instructions” section

of the download document.

Contacting IBM SupportIBM Support assists you with product defects, answers FAQs, and helps usersresolve problems with the product.

Before you begin

After trying to find your answer or solution by using other self-help options suchas technotes, you can contact IBM Support. Before contacting IBM Support, yourcompany or organization must have an active IBM software subscription andsupport contract, and you must be authorized to submit problems to IBM. Forinformation about the types of available support, see the Support portfolio topic inthe “Software Support Handbook”.

Procedure

To contact IBM Support about a problem:1. Define the problem, gather background information, and determine the severity

of the problem. For more information, see the Getting IBM support topic in theSoftware Support Handbook.

2. Gather diagnostic information.3. Submit the problem to IBM Support in one of the following ways:

v Using IBM Support Assistant (ISA):Any data that has been collected can be attached to the service request.Using ISA in this way can expedite the analysis and reduce the time toresolution.a. Download and install the ISA tool from the ISA website. See

http://www.ibm.com/software/support/isa/.b. Open ISA.


http://www.ibm.com/support/fixcentral/

http://www14.software.ibm.com/webapp/set2/sas/f/handbook/offerings.html

http://www14.software.ibm.com/webapp/set2/sas/f/handbook/getsupport.html

http://www.ibm.com/software/support/isa/

c. Click Collection and Send Data.d. Click the Service Requests tab.e. Click Open a New Service Request.

v Online through the IBM Support Portal: You can open, update, and view allof your service requests from the Service Request portlet on the ServiceRequest page.

v By telephone for critical, system down, or severity 1 issues: For the telephonenumber to call in your region, see the Directory of worldwide contacts webpage.

Results

If the problem that you submit is for a software defect or for missing or inaccuratedocumentation, IBM Support creates an Authorized Program Analysis Report(APAR). The APAR describes the problem in detail. Whenever possible, IBMSupport provides a workaround that you can implement until the APAR isresolved and a fix is delivered. IBM publishes resolved APARs on the IBM Supportwebsite daily, so that other users who experience the same problem can benefitfrom the same resolution.

Appendix E. Support information 115

http://www.ibm.com/software/support/

http://www.ibm.com/planetwide/

Appendix F. Accessibility features for IBM Security IdentityManager

Accessibility features help users who have a disability, such as restricted mobilityor limited vision, to use information technology products successfully.

Accessibility features

The following list includes the major accessibility features in IBM Security IdentityManager.v Support for the Freedom Scientific JAWS screen reader applicationv Keyboard-only operationv Interfaces that are commonly used by screen readersv Keys that are discernible by touch but do not activate just by touching themv Industry-standard devices for ports and connectorsv The attachment of alternative input and output devices

The IBM Security Identity Manager library, and its related publications, areaccessible.

Keyboard navigation

This product uses standard Microsoft Windows navigation keys.

Related accessibility information

The following keyboard navigation and accessibility features are available in theform designer:v You can use the tab keys and arrow keys to move between the user interface

controls.v You can use the Home, End, Page Up, and Page Down keys for more

navigation.v You can launch any applet, such as the form designer applet, in a separate

window to enable the Alt+Tab keystroke to toggle between that applet and theweb interface, and also to use more screen workspace. To launch the window,click Launch as a separate window.

v You can change the appearance of applets such as the form designer by usingthemes, which provide high contrast color schemes that help users with visionimpairments to differentiate between controls.

IBM and accessibility

See the IBM Human Ability and Accessibility Center For more information aboutthe commitment that IBM has to accessibility.


http://www.ibm.com/able

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law :

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment to


IBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM's application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

If you are viewing this information softcopy, the photographs and colorillustrations might not appear.

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not be displayed.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at "Copyright andtrademark information" at http://www.ibm.com/legal/copytrade.shtml.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks orregistered trademarks of Intel Corporation or its subsidiaries in the United Statesand other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

ITIL is a registered trademark, and a registered community trademark of the Officeof Government Commerce, and is registered in the U.S. Patent and TrademarkOffice.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Cell Broadband Engine and Cell/B.E. are trademarks of Sony ComputerEntertainment, Inc., in the United States, other countries, or both and is used underlicense therefrom.

Notices 121

http://www.ibm.com/legal/copytrade.shtml

Java™ and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

Privacy Policy Considerations

IBM Software products, including software as a service solutions, ("SoftwareOfferings") may use cookies or other technologies to collect product usageinformation, to help improve the end user experience, and to tailor interactionswith the end user or for other purposes. In many cases, no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offeringscan help enable you to collect personally identifiable information. If this SoftwareOffering uses cookies to collect personally identifiable information, specificinformation about this offering’s use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collectpersonally identifiable information.

If the configurations deployed for this Software Offering provide you as customerthe ability to collect personally identifiable information from end users via cookiesand other technologies, you should seek your own legal advice about any lawsapplicable to such data collection, including any requirements for notice andconsent.

For more information about the use of various technologies, including cookies, forthese purposes, see IBM's Privacy Policy at http://www.ibm.com/privacy andIBM’s Online Privacy Statement at http://www.ibm.com/privacy/details/us/ensections entitled "Cookies, Web Beacons and Other Technologies and SoftwareProducts and Software-as-a Service".


http://www.ibm.com/privacy

http://www.ibm.com/privacy/details/us/en

Index

Aaccessibility x, 117accessor ID 21account form 58, 60

sequence of profiles 111ACID

defining 21fields

ispf dialog 62user-defined 62

propagation 22activity logging settings

changing 47enabling 47options 47

adapteraccount form attributes 95attributes 18CA certificate installation 32code page

changing 53default values 52valid values 52

commentsauditing 68command string 68

configuration 7, 16, 21configuration tool

agentCfg 24settings 24starting 24viewing statistics 24

considerations 2customization 56environment variables 109installation 7installation plans 5interactions with Security Identity

Manager 3introduction 1log files 88overview 1prerequisites 6profile

importing 16, 17verify 17verifying installation 16, 17

registry settings 107requirements 6service creation 16, 18starting 16stopping 16troubleshooting errors 83troubleshooting warnings 83uninstalling 93upgrading 93utility 88

adapter parametersaccessing 75options 75

administrator authority prerequisites 6

after installation 21agent main configuration menu 24agentCfg

adapter parameters, changingconfiguration key 46

advanced settings, changingoptions 50

help menu arguments 54menus, event notification 29viewing configuration settings 25

APPLID 88attributes

for search 38installing with JAR files 67

auditing, adapter comments 68authentication

certificate configuration for SSL 71two-way SSL configuration 73

Bbackwards compatability with earlier

versions 61

CCA Top Secret

access 21configuration, access 21

CA Top Secret Adapter 23CATSSProfile.jar, extracting files 65certificate authority

certificatedeleting 80

certTool usage 79deleting 80installation 79viewing 80viewing installed 79viewing registered 81

Certificate Authority (CA) certificates 32certificate signing request

definition 77file, generating 77

certificate signing request (CSR),examples 78

certificatescertificate management tools 71certTool usage 81configuration for SSL 71digital certificates 69examples of signing request (CSR) 78exporting to PKCS12 file 82installation 79installation, from file 78installation, using certTool 78key formats 70management with certTool 75one-way SSL authentication 71overview 69

certificates (continued)private keys 69protocol configuration tool

certTool 69registering 81removing 81self-signed 70SSL 70unregistering 81viewing 79, 80, 81viewing registered 81z/OS adapters 79

certToolcertificate configuration 71certificate installation 78initialization 75private key, generating 77private keys and certificates,

managing 75registered certificates

viewing 81SSL authentication enablement 68SSL certificate management 75

CertToolchanging adapter parameters

accessing 71changing code page settings 52code page settings 52comments

adapter 68auditing 68

compatibility, backwards 61configuration 21

keychanging with agentCfg 46default value 46default values 24modifications 24

one-way SSL authentication 71settings

default values 25viewing with agentCfg 25

connectionsecure 68

creating adapter service 18CSR 77CustomLabels.properties file,

modifying 66

DDAML

communication protocol 68default values 26properties 26protocol, configuration 26

DAML protocoldefault communication 68

DAML protocol configuration 26DAML protocols

SSL authentication 71


detail logpurpose 48

download, software 6

Eeducation xencryption

SSL 69encryption, SSL 69event notification

configuration 29assumptions 30examples 30

configuring with agentCfg 29context

baseline database 46disable 36enable 36listing 36modifying 43search attributes 44

event notification configurationrequirements 30

event notification contextadding

search attributes 44configuring

Target DN 45modifying 43removing baseline database 46

exit string 59extended attributes, mapping

user-defined ACID fields 62extracting files, CATSSProfile.jar file 65

Ffirst steps 21

IIBM

Software Support xSupport Assistant x

IBM Support Assistant 114installation

certificate 78certificates for z/OS adapters 79plan 5prerequisites 6private key 79roadmap 5

ISA 114ISIMEXIT 58, 59, 60ISPF dialog

installing 7running 7, 8

ISPF dialog installation 7ispf dialog, ACID fields 62

JJAR files, creating 67

Kkeys, exporting to PKCS12 file 82knowledge bases 113

Llabels, CustomLabels.properties file 66log files, adapter 88logs, viewing statistics 51

Mmapping ACID fields, extended

attributes 62modifying

adapter form 67labels 66registry settings 49schema.dsml file 66

Nnetwork connectivity prerequisites 6non-encrypted registry settings,

modifying 49notices 119

Oone-way SSL authentication 71online

publications ixterminology ix

operating system prerequisites 6overview 1

Ppasswords

changing configuration key 46configuration key, default value 46configuration keys, default value 24

permissions, sequencing of 111PKCS12 file

certificate installation 79exporting certificate and key 82importing 70

preinstallation roadmap 5prerequisites

administrator authority 6event notification configuration 30network connectivity 6operating system 6server communication 6

private keygenerating 77installation 79

problem-determination xprofile sequence, account forms 111propagation, ACID 22protocol

configuration settings, changing 26properties, settings 31

protocol (continued)SSL

two-way configuration 74pseudo-distinguished name 39public keys 69publications

accessing online ixlist of ix

Rreconciliation

event notifications 42setting attributes 42

registrationcertTool usage 81of certificates 81

registry settingsnon-encrypted 49

REXX execsisimexec 56isimexit 56

REXX exit parameters 58roadmaps

installation 5preinstallation 5

running ISPF dialog 8

Sschema.dsml, updating 66self-signed certificates 32server communication prerequisites 6service form attributes 18set protocol properties 31single address space

unix system services 21software

download 6website 6

SSLauthentication, certificate

configuration 71authentication, certTool 68authentication, enablement 68authentication, one-way 71authentication, overview 68certificate

signing request 77certificates 70certTool, certificate management 75client 74client and server 74configuration 68digital certificates 69encryption 69key formats 70overview 69private keys 69two-way configuration 74

SSL authenticationconfiguration 68two-way configuration 73

SSL implementationsDAML protocol 71

statistics, viewing 51


support contact information 114surrogate user 23

TTarget DN 39terminology ixtesting connection 18training xtroubleshooting

APPC problems 87contacting support 114getting fixes 114identifying problems 85searching knowledge bases 113support website xtechniques for 85troubleshooting techniques 85

two-way configurationSSL

certificates 73

Uunix system services

two address spaces 21uploading adapter package 7user-defined ACID fields 62USS

locations 8single address space 21UNIX System Services 8

Zz/OS

self-signed certificates 70z/OS operating systems

package file format 7uploading adapter package 7

Index 125

��

Printed in USA

SC27-4424-02

CATop Secret for z/OSAdapter Installation and ... · CATop Secret for z/OSAdapter Installation and...

Documents

Transcript of CATop Secret for z/OSAdapter Installation and ... · CATop Secret for z/OSAdapter Installation and...