T l Identity Manager - IBMpublib.boulder.ibm.com/tividd/td/ITIM/SC32-1490-08/en_US/PDF/racf... · ® Identity Manager RACF Adapter Installation and Configuration Guide ... Identity

Tivoli® Identity Manager

RACF Adapter Installation and Configuration Guide

Version 4.6

SC32-1490-08

��

Tivoli® Identity Manager

RACF Adapter Installation and Configuration Guide

Version 4.6

SC32-1490-08

��

Note:

Before using this information and the product it supports, read the information in Appendix D, “Notices,” on page 113.

Ninth Edition (June 2005)

This edition applies to version 4.6 of this adapter and to all subsequent releases and modifications until otherwise

indicated in new editions.

© Copyright International Business Machines Corporation 2003, 2005. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . v

Who should read this book . . . . . . . . . v

Publications and related information . . . . . . v

Tivoli Identity Manager library . . . . . . . v

Prerequisite Product Publications . . . . . . vii

Related Publications . . . . . . . . . . viii

Accessing publications online . . . . . . . ix

Accessibility . . . . . . . . . . . . . . ix

Support information . . . . . . . . . . . ix

Conventions used in this book . . . . . . . . ix

Typeface conventions . . . . . . . . . . ix

Operating system differences . . . . . . . . x

Definitions for HOME and other directory

variables . . . . . . . . . . . . . . . x

Summary of changes made to the RACF adapter . . xii

Summary of changes for SC32-1490-08 Ninth

Edition (June 2004) . . . . . . . . . . . xii

Summary of changes for SC32-1490-07 Eighth

Edition (November 2004) . . . . . . . . . xii

Summary of changes for SC32-1490-06 Seventh

Edition (November 2004) . . . . . . . . xiii

Summary of changes for SC32-1490-05 Sixth

Edition (August 2004) . . . . . . . . . xiii

Chapter 1. Overview of the RACF

adapter . . . . . . . . . . . . . . . 1

RACF considerations . . . . . . . . . . . 3

Chapter 2. Adapter interactions with the

Tivoli Identity Manager Server . . . . . 7

Chapter 3. Installing and configuring the

RACF adapter . . . . . . . . . . . . 9

Basic installation . . . . . . . . . . . . . 9

Prerequisites . . . . . . . . . . . . . . 9

Installation worksheet . . . . . . . . . . . 10

RACF adapter activation checklist . . . . . . . 13

Step 1: Upload the adapter package . . . . . . 13

Step 2: Install the MVS executables . . . . . . 16

Step 3: Install the UNIX System Services executables 18

Step 4: Configure the UNIX System Services

Component . . . . . . . . . . . . . . 19

Step 5: Configure MVS Components . . . . . . 22

Modify and submit the APPCCMD job . . . . 22

Modify and submit the APPCRECO job . . . . 24

Modify and submit the ITIMVSAM job . . . . 27

Create started task . . . . . . . . . . . 29

Configure RACF access . . . . . . . . . 30

Step 6: Configure communication . . . . . . . 34

Importing the adapter profile into the Tivoli

Identity Manager Server . . . . . . . . . 34

Creating a RACF service . . . . . . . . . 35

Step 7: Starting and stopping the adapter . . . . 36

Chapter 4. Configuring the RACF

adapter in IBM Tivoli Identity Manager . 39

Starting the adapter configuration tool . . . . . 39

Viewing configuration settings . . . . . . . . 40

Changing protocol configuration settings . . . . 41

Configuring event notification . . . . . . . . 44

Required information . . . . . . . . . . 44

Example definition . . . . . . . . . . . 45

Setting attributes to be reconciled . . . . . . 58

Modifying an event notification context . . . . 59

Changing the configuration key . . . . . . . 61

Changing activity logging settings . . . . . . . 61

Changing registry settings . . . . . . . . . 63

Modifying non-encrypted registry settings . . . 64

Changing advanced settings . . . . . . . . . 64

Viewing statistics . . . . . . . . . . . . 66

Changing code page settings . . . . . . . . 66

Default adapter code page locale . . . . . . 66

Obtaining a list of valid code pages . . . . . 66

Setting the code page . . . . . . . . . . 67

Accessing help and additional options . . . . . 68

Chapter 5. Configuring SSL

authentication for the RACF adapter . . 71

Overview of SSL and digital certificates . . . . . 71

Private keys, public keys, and digital certificates 72

Self-signed certificates . . . . . . . . . . 72

Certificate and key formats . . . . . . . . 73

The use of SSL authentication . . . . . . . . 73

Configuring certificates for SSL authentication . . . 74

Configuring certificates for one-way SSL

authentication . . . . . . . . . . . . 74

Configuring certificates for two-way SSL

authentication . . . . . . . . . . . . 75

Configuring certificates when the adapter

operates as an SSL client . . . . . . . . . 76

Managing SSL certificates using CertTool . . . . 77

Starting CertTool . . . . . . . . . . . 77

Generating a private key and certificate request 79

Installing the certificate . . . . . . . . . 80

Installing the certificate and key from a PKCS12

file . . . . . . . . . . . . . . . . 80

Viewing the installed certificate . . . . . . . 81

Installing a CA certificate . . . . . . . . . 81

Viewing CA certificates . . . . . . . . . 81

Deleting a CA certificate . . . . . . . . . 81

Viewing registered certificates . . . . . . . 82

Registering a certificate . . . . . . . . . 82

Unregistering a certificate . . . . . . . . 82

Exporting a certificate and key to PKCS12 file . . 82

Chapter 6. Customizing the RACF

adapter . . . . . . . . . . . . . . 85

ITIMEXIT . . . . . . . . . . . . . . . 85

© Copyright IBM Corp. 2003, 2005 iii

ITIMEXEC . . . . . . . . . . . . . . . 86

Chapter 7. Troubleshooting the adapter 89

Adapter log files . . . . . . . . . . . . . 89

Appendix A. Agent attributes . . . . . 91

Agent attributes by object . . . . . . . . . 91

erRacUser . . . . . . . . . . . . . . 91

erRacConnect . . . . . . . . . . . . 104

erRacGroup . . . . . . . . . . . . . 105

Appendix B. Registry settings . . . . 107

Appendix C. Support information . . . 109

Searching knowledge bases . . . . . . . . . 109

Search the information center on your local

system or network . . . . . . . . . . . 109

Search the Internet . . . . . . . . . . 109

Obtaining fixes . . . . . . . . . . . . . 110

Contacting IBM Software Support . . . . . . 110

Determine the business impact of your problem 111

Describe your problem and gather background

information . . . . . . . . . . . . . 111

Submit your problem to IBM Software Support 111

Appendix D. Notices . . . . . . . . 113

Trademarks . . . . . . . . . . . . . . 114

Index . . . . . . . . . . . . . . . 117

iv IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide

Preface

The IBM® Tivoli® Identity Manager RACF® Adapter (RACF Adapter) enables

connectivity between the IBM Tivoli Identity Manager Server and a network of

systems running the MVS operating system. Once the adapter is installed and

configured, Tivoli Identity Manager manages access to MVS RACF resources with

your site’s security system. This book describes how to install and configure the

RACF Adapter.

Note: The program that is used to connect the managed resource to the Tivoli

Identity Manager Server is now called an adapter. The term adapter replaces

the previously used term agent. The user interface used to configure the

adapter still refers to an adapter as an agent.

Who should read this book

This book is intended for MVS system and security administrators responsible for

installing software on their site’s computer systems. Readers are expected to

understand MVS concepts. The person completing the installation procedure

should also be familiar with their site’s system standards and needs to have

appropriate MVS experience and knowledge. Readers must be able to perform

routine MVS system and security administration tasks.

To install and configure the RACF Adapter, you should possess the following skills

and experience:

v Administration of RACF

v Administration of APPC/MVS

v Administration of z/OS VTAM

v Usage and administration of z/OS TCP/IP

v Usage of TSO/ISPF

v Usage of UNIX System Services

v If SSL is enabled, understanding of the creation and installation of digital

certificates

Publications and related information

Read the descriptions of the Tivoli Identity Manager library. To determine which

additional publications you might find helpful, read the “Prerequisite Product

Publications” on page vii and the “Related Publications” on page viii. After you

determine the publications you need, refer to the instructions in “Accessing

publications online” on page ix.

Tivoli Identity Manager library

The publications in the Tivoli Identity Manager technical documentation library are

organized into the following categories:

v Release information

v Online user assistance

v Server installation and configuration

v Problem determination

© Copyright IBM Corp. 2003, 2005 v

v Technical supplements

v Adapter installation and configuration

Release Information:

v IBM Tivoli Identity Manager Release Notes

Provides software and hardware requirements for Tivoli Identity Manager, and

additional fix, patch, and other support information.

v IBM Tivoli Identity Manager Documentation Read This First Card

Lists the Tivoli Identity Manager publications.

Online user assistance:

Provides online help topics and an information center for all Tivoli Identity

Manager administrative tasks. The information center includes information that

was previously provided in the IBM Tivoli Identity Manager Configuration Guide and

the IBM Tivoli Identity Manager Policy and Organization Administration Guide.

Server installation and configuration:

IBM Tivoli Identity Manager Server Installation and Configuration Guide for WebSphere

Environments provides installation and configuration information for Tivoli Identity

Manager.

Configuration information that was previously provided in the IBM Tivoli Identity

Manager Configuration Guide is now included in either the installation guide or in

the IBM Tivoli Identity Manager Information Center.

Problem determination:

IBM Tivoli Identity Manager Problem Determination Guide provides problem

determination, logging, and message information for the Tivoli Identity Manager

product.

Technical supplements:

The following technical supplements are provided by developers or by other

groups who are interested in this product:

v IBM Tivoli Identity Manager Performance Tuning Guide

Provides information needed to tune Tivoli Identity Manager Server for a

production environment, available on the Web at:

http://publib.boulder.ibm.com/tividd/td/tdprodlist.html

Click the I character in the A-Z product list, and then, click the Tivoli Identity

Manager link. Browse the information center for the Technical Supplements

section.

v Redbooks and white papers are available on the Web at:

http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html

Browse to the Self Help section, in the Learn category, and click the Redbooks

link.

v Technotes are available on the Web at:

http://www.redbooks.ibm.com/redbooks.nsf/tips/

v Field guides are available on the Web at:

vi IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide


http://www-306.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html



http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html

v For an extended list of other Tivoli Identity Manager resources, search the

following IBM developerWorks Web address:

http://www.ibm.com/developerworks/

Adapter installation and configuration:

The Tivoli Identity Manager Server technical documentation library also includes

an evolving set of platform-specific installation documents for the adapter

components of a Tivoli Identity Manager Server implementation. Locate adapters

on the Web at:

http://www.lotus.com/services/passport.nsf/WebDocs/Passport_Advantage_Home

Click Support & downloads. Browse to the Downloads and drivers. Click the link

for the current inventory of adapters.

Skills and training:

The following additional skills and technical training information were available at

the time that this manual was published:

v Virtual Skills Center for Tivoli Software on the Web at:

http://www.cgselearning.com/tivoliskills/

v Tivoli Education Software Training Roadmaps on the Web at:

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

v Tivoli Technical Exchange on the Web at:

http://www.ibm.com/software/sysmgmt/products/support/supp_tech_exch.html

Prerequisite Product Publications

To use the information in this book effectively, you must have knowledge of the

products that are prerequisites for Tivoli Identity Manager Server. Publications are

available from the following locations:

v MVS RACF

– http://www-1.ibm.com/servers/eserver/zseries/zos/racf/v Operating systems

– z/OS

http://www-1.ibm.com/servers/eserver/zseries/zos/

– IBM AIX®

http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix52.htm

– Sun Solaris

http://docs.sun.com/db?q=solaris+9

– Red Hat Linux®

http://www.redhat.com/docs/

– Microsoft® Windows Server 2003

http://www.microsoft.com/windowsserver2003/proddoc/default.mspxv Database servers

– IBM DB2®

Preface vii





http://www.cgselearning.com/tivoliskills/

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



http://www-1.ibm.com/servers/eserver/zseries/zos/racf/

http://www-1.ibm.com/servers/eserver/zseries/zos/

http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix52.htm

http://docs.sun.com/db?q=solaris+9

http://www.redhat.com/docs/

http://www.microsoft.com/windowsserver2003/proddoc/default.mspx

- Support: http://www.ibm.com/software/data/db2/udb/support.html

- Information center:

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp

- Documentation: http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs.d2w/en_main

- DB2 product family: http://www.ibm.com/software/data/db2

- Fix packs:

http://www.ibm.com/software/data/db2/udb/support/downloadv8.html

- System requirements:

http://www.ibm.com/software/data/db2/udb/sysreqs.html– Oracle

http://www.oracle.com/technology/documentation/index.html

http://otn.oracle.com/tech/index.html

http://otn.oracle.com/tech/linux/index.html

– Microsoft SQL Server 2000

http://www.msdn.com/library/

http://www.microsoft.com/sql/v Directory server applications

– IBM Directory Server http://publib.boulder.ibm.com/tividd/td/IBMDS/IDSapinst52/en_US/HTML/ldapinst.htm http://www.ibm.com/software/network/directory

– Sun ONE Directory Server

http://docs.sun.com/app/docs/coll/S1_DirectoryServer_52v WebSphere Application Server

Additional information is available in the product directory or Web sites. http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp http://www.redbooks.ibm.com/

v WebSphere embedded messaging

http://www.ibm.com/software/integration/wmq/

v IBM HTTP Server

http://www.ibm.com/software/webservers/httpservers/library.html

Related Publications

Information that is related to Tivoli Identity Manager Server is available in the

following publications:

v The Tivoli Software Library provides a variety of Tivoli publications such as

white papers, datasheets, demonstrations, redbooks, and announcement letters.

The Tivoli Software Library is available on the Web at:

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

v The Tivoli Software Glossary includes definitions for many of the technical terms

related to Tivoli software. The Tivoli Software Glossary is available from the

Glossary link of the Tivoli Software Library Web page at:

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

viii IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide

http://www.ibm.com/software/data/db2/udb/support.html

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp

http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs.d2w/en_main

http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs.d2w/en_main

http://www.ibm.com/software/data/db2

http://www.ibm.com/software/data/db2/udb/support/downloadv8.html

http://www.ibm.com/software/data/db2/udb/sysreqs.html

http://www.oracle.com/technology/documentation/index.html

http://otn.oracle.com/tech/index.html

http://otn.oracle.com/tech/linux/index.html

http://www.msdn.com/library/

http://www.microsoft.com/sql/

http://publib.boulder.ibm.com/tividd/td/IBMDS/IDSapinst52/en_US/HTML/ldapinst.htm

http://publib.boulder.ibm.com/tividd/td/IBMDS/IDSapinst52/en_US/HTML/ldapinst.htm

http://www.ibm.com/software/network/directory

http://docs.sun.com/app/docs/coll/S1_DirectoryServer_52

http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp

http://www.redbooks.ibm.com/

http://www.ibm.com/software/integration/wmq/

http://www-3.ibm.com/software/webservers/httpservers/library.html

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

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

Accessing publications online

IBM posts publications for this and all other Tivoli products, as they become

available and whenever they are updated, to the Tivoli software information center

Web site. Access the Tivoli software information center at the following Web

address:


Click the I character in the A-Z list, and then click the Tivoli Identity Manager

link to access the product library.

Note: If you print PDF documents on other than letter-sized paper, set the option

in the File → Print window that allows Adobe Reader to print letter-sized

pages on your paper.

Accessibility

The product documentation includes the following features to aid accessibility:

v Documentation is available in convertible PDF format to give the maximum

opportunity for users to apply screen-reader software.

v All images in the documentation are provided with alternative text so that users

with vision impairments can understand the contents of the images.

Support information

If you have a problem with your IBM software, you want to resolve it quickly. IBM

provides the following ways for you to obtain the support you need:

v Searching knowledge bases: You can search across a large collection of known

problems and workarounds, Technotes, and other information.

v Obtaining fixes: You can locate the latest fixes that are already available for your

product.

v Contacting IBM Software Support: If you still cannot solve your problem, and

you need to work with someone from IBM, you can use a variety of ways to

contact IBM Software Support.

For more information about these ways to resolve problems, see Appendix C,

“Support information,” on page 109.

Conventions used in this book

This reference uses several conventions for special terms and actions and for

operating system-dependent commands and paths.

Typeface conventions

This guide uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwise

difficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spin

buttons, fields, folders, icons, list boxes, items inside list boxes,

multicolumn lists, containers, menu choices, menu names, tabs, property

sheets), labels (such as Tip:, and Operating system considerations:)

Preface ix


v Keywords and parameters in text

Italic

v Words defined in text

v Emphasis of words (words as words)

v New terms in text (except in a definition list)

v Variables and values you must provide

Monospace

v Examples and code examples

v File names, programming keywords, and other elements that are difficult

to distinguish from surrounding text

v Message text and prompts addressed to the user

v Text that the user must type

v Values for arguments or command options

Operating system differences

This guide uses the UNIX® convention for specifying environment variables and

for directory notation.

When using the Windows command line, replace $variable with %variable% for

environment variables and replace each forward slash (/) with a backslash (\) in

directory paths. The names of environment variables are not always the same in

Windows and UNIX. For example, %TEMP% in the Windows operating system is

equivalent to $tmp in a UNIX operating system.

Note: If you are using the bash shell on a Windows system, you can use the UNIX

conventions.

Definitions for HOME and other directory variables

The following table contains the default definitions that are used in this guide to

represent the HOME directory level for various product installation paths. You can

customize the installation directory and HOME directory for your specific

implementation. If this is the case, you need to make the appropriate substitution

for the definition of each variable represented in this table.

The value of path varies for these operating systems:

v Windows: drive:\Program Files

v AIX: /usr

v Other UNIX: /opt

Path Variable Default Definition Description

DB_INSTANCE_HOME Windows:

path\IBM\SQLLIB

UNIX:

v AIX, Linux: /home/dbinstancename

v Solaris: /export/home/dbinstancename

The directory that

contains the

database for Tivoli

Identity Manager.

x IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide


LDAP_HOME v For IBM Directory Server Version 5.2

Windows:

path\IBM\LDAP

UNIX:

– AIX, Linux: path/ldap

– Solaris: path/IBMldaps

path/IBM/LDAP

v For IBM Directory Server Version 6.0

Windows:

path\IBM\LDAP\V6.0

UNIX:

path/IBM/LDAP/V6.0

– AIX, Solaris

– Linux: opt/ibm/ldap/V6.0

v For Sun ONE Directory Server

Windows:

path\Sun\MPS

UNIX:

/var/Sun/mps

The directory that

contains the

directory server

code.

IDS_instance_HOME For IBM Directory Server Version 6.0

Windows:

drive\

ibmslapd-instance_owner_name

The value of drive might be C:\ on

Windows systems. An example of

instance_owner_name might be ldapdb2.

For example, the log file might be

C:\idsslapd-ldapdb2\logs\ibmslapd.log.

UNIX:

INSTANCE_HOME/idsslapd-instance_name

On Linux and AIX systems, the default

home directory is the

/home/instance_owner_name directory. On

Solaris systems, for example, the directory

is the /export/home/ldapdb2/idsslapd-ldapdb2 directory.

The directory that

contains the IBM

Directory Server

Version 6.0 instance.

HTTP_HOME Windows:

path\IBMHttpServer

UNIX:

path/IBMHttpServer

The directory that

contains the IBM

HTTP Server code.

Preface xi


ITIM_HOME Windows:

path\IBM\itim

UNIX:

path/IBM/itim

The base directory

that contains the

Tivoli Identity

Manager code,

configuration, and

documentation.

WAS_HOME Windows:

path\WebSphere\AppServer

UNIX:

path/WebSphere/AppServer

The WebSphere

Application Server

home directory

WAS_MQ_HOME Windows:

path\ibm\WebSphere MQ

UNIX:

path/mqm

The directory that

contains the

WebSphere MQ

code.

WAS_NDM_HOME Windows:

path\WebSphere\DeploymentManager

UNIX:

path/WebSphere/DeploymentManager

The home directory

on the deployment

manager

Tivoli_Common_Directory Windows:

path\ibm\tivoli\common\CTGIM

UNIX:

path/ibm/tivoli/common/CTGIM

The central location

for all

serviceability-related

files, such as logs

and first-failure

capture data

Summary of changes made to the RACF adapter

Summary of changes for SC32-1490-08 Ninth Edition (June

2004)

This document contains information previously presented in the IBM Tivoli Identity

Manager RACF Adapter Installation and Configuration Guide, SC32-1490-07, which

supports the RACF Adapter, Eighth Edition (November 2004).

Changed information

v Changed the term agent to adapter.

v Updated the version from 4.5.1 to 4.6.

v Applied the new 4.6 updates to the document.

Summary of changes for SC32-1490-07 Eighth Edition

(November 2004)

This document contains information previously presented in the IBM Tivoli Identity

Manager RACF Adapter Installation and Configuration Guide, SC32-1490-06, which

supports the RACF Adapter, Seventh Edition (November 2004).

Changed information

v Minor changes.

xii IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide

Summary of changes for SC32-1490-06 Seventh Edition

(November 2004)

Changed information

v Event notification is now supported.

v Filtered reconciliation is now supported.

v Code page support has been implemented, using the default code page of

IBM-1047.

v Documentation changes from user requests:

– Improved documentation on implementing APPC/MVS and related

transactions.

– Improved documentation on utilization of surrogate user ID’s, for business

unit filtering

Summary of changes for SC32-1490-05 Sixth Edition (August

2004)

Changed information

v “ITIMEXIT” on page 85 includes updated information on zero and non-zero

return codes.

Preface xiii

xiv IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide

Chapter 1. Overview of the RACF adapter

An adapter is a program that provides an interface between a managed resource

and the Tivoli Identity Manager Server. Adapters might or might not reside on the

managed resource and the Tivoli Identity Manager Server manages access to the

resource by using your security system. Adapters function as trusted virtual

administrators on the target platform, performing such tasks as creating login IDs,

suspending IDs, and performing other functions administrators normally run

manually. The adapter runs as a service, independent of whether or not a user is

logged on to the Tivoli Identity Manager Server.

The IBM Tivoli Identity Manager RACF Adapter enables connectivity between the

Tivoli Identity Manager Server and a system running the MVS RACF server. This

installation guide provides the basic information that you need to install and

configure the RACF Adapter components. This chapter provides an overview of

the adapter and features of the adapter.

Tivoli Identity Manager works in conjunction with RACF security in an MVS

environment. The adapter coordinates communication between the Tivoli Identity

Manager Server and remote servers operating on other systems.

The RACF Adapter provides a method to receive provisioning requests issued from

Tivoli Identity Manager and process these requests to add, modify, delete, and

extract user information from an IBM RACF database. It does this by converting

Directory Access Markup Language (DAML) requests (using ERMA libraries for

movement of requests and information) issued from Tivoli Identity Manager to a

corresponding RACF command and then forwarding them through a series of

APPC requests to a command executor tasked to fulfill the command. The

command executor receives the formatted RACF command string, determines its

origin and scope of authority, and issues the command through TSO. Results of the

command execution are returned, including success or failure information.

The RACF Adapter is comprised of three components; the Adapter proper, the

Command Executor, and the Reconciliation Processor (refer to Figure 1 on page 2).

The RACF Adapter was designed in this manner because RACF commands must

be APF-authorized, which is not permitted from within the Unix System Services

environment. An additional benefit of this design is in the event of an APPC/MVS

transaction failure, there will be no cascading failure of the adapter process.

© Copyright IBM Corp. 2003, 2005 1

Note: Each instance of an APPC connection will correspond to a separate instance

of a command executor, allowing for multithreading from the adapter.

Adapter proper

The Adapter proper receives and processes requests from Tivoli Identity

Manager and then requests and receives acknowledgements through an

APPC connection to the Command Executor. The binaries of the Adapter

proper and related external files reside within the Unix System Services

environment of z/OS (OS/390).

Command Executor

The Command Executor, written in REXX, operates as an APPC/MVS

transaction that is triggered from an incoming request from the Adapter.

APPC requests will consist of a command to be executed, and, optionally, a

RACF user ID assumed as the identity or origin for the command. If a

RACF user ID is not provided with the request sent from the Adapter

proper, the command is sent under the default identity set for the adapter

after installation. The Command Executor executes completely within the

APPC/MVS environment.

Reconciliation Processor

The Reconciliation Processor is a series of programs, written in C, that

operate as an APPC/MVS transaction that is triggered by an incoming

request to the adapter. The APPC transaction may be accompanied with an

optional RACF user ID. The RACF user ID may be utilized (based upon

adapter configuration settings) for a scope-of-authority, or partial,

reconciliation. The Reconciliation Processor may either execute the RACF

database unload utility (IRRDBU00), or, may be provided with an existing

input file, produced by the RACF database unload utility.

The following procedure reviews the actions taken when a command is issued

against a RACF resource by proxy, using theTivoli Identity Manager RACF

Adapter.

1. A request is issued to alter one or more attributes on the Tivoli Identity

Manager user session or policy to the RACF Adapter to utilize the DAML

protocol.

ServiceProvider

Agent

CommandExecutor

ReconciliationProcessor

RACFDatabase

Z/OS HostDAML

Protocol

APPC (LU6.2)Protocol

RACF commands toIRRDBU00 to unload database

update.

UNIXSystemServices

Figure 1. The RACF Adapter

2 IBM Tivoli Identity Manager: RACF Adapter Installation and Configuration Guide

2. The Adapter proper residing within Unix System Services receives the

command and composes a TSO command string from the information.

Optionally, a RACF user ID accompanies the request, which will be the identity

of the issuer of the command. Authorization for commands issued through the

RACF Adapter is controlled through assignment of RACF user ID’s and RACF

resource profiles from within RACF.

3. The Adapter proper sends a series of APPC requests containing the command

to the Command Executor component.

4. The Command Executor executes the RACF command string it receives.

5. The Command Executor relays the results of the command execution back to

the Adapter.

6. The Adapter component relays the results of the altered attributes back to the

Tivoli Identity Manager that issued the request.

Note: When a Recon command is issued from Tivoli Identity Manager, the Recon

Processor component will execute IRRDBU00 to unload the RACF database.

This will create a file containing the entire contents of the RACF database.

The Recon Processor will then identify the Recon requestor’s scope of

authority and parse the file, discarding any information that is beyond the

requestor’s authority before returning the information to the Adapter proper

component.

RACF considerations

While this adapter does not require any APF authorization, there are RACF

environment issues to consider.

The RACF adapter operates in two basic modes.

If there is no operational RACF ID specified on the Tivoli Identity Manager service

form when a request is issued, the RACF user ID the adapter utilizes requires

specific privileges. For example, if the adapter administers all users within the

RACF database, it should operate with the SYSTEM SPECIAL RACF attribute. If

Tivoli Identity Manager performs operations against only a portion of the RACF

database, the adapter must be associated with a group assigned GROUP SPECIAL

privileges, for the portion of the RACF database it will administer. The following

figure depicts the above scenario:

Chapter 1. Overview of the RACF adapter 3

If operations carried out will be performed under a RACF ID specified on the

Tivoli Identity Manager service form, the RACF ID the adapter is started with does

not require any special privileged attributes. It does, however, require surrogate

authority to run functions under the identity of the RACF ID specified on the

Tivoli Identity Manager service form. The ID specified on the Tivoli Identity

Manager service form must have authority to perform the administration functions

requested by the Tivoli Identity Manager Server.

The following picture shows the above scenario:

Tivoli Identity

Manager ServerZ/OS Platform

RACF SSL

Service FormAgent operating

in UNIX System

Services

Command

Processor

Operating in

APPC/MVS

“RACF ID under which

requests will be

processed” field on

service form is .blank

RACF ID

assigned to

agent is

“ ”ITIAGNT

RACF ID used

for processing

requests will be

“ ”ITIAGNT

Figure 2. No operational RACF ID provided on the Tivoli Identity Manager service form

Tivoli Identity

Manager ServerZ/OS Platform

RACF SSL

Service FormAgent operating

in UNIX System

Services

Command

Processor

Operating in

APPC/MVS

“RACF ID under which

requests will be

processed” field on

service form is set to

“ ”.ADMINX

RACF ID

assigned to

agent is

“ ”ITIAGNT

RACF ID used

for processing

requests will be

“ ”ADMINX

ADMINX

Figure 3. Operational RACF ID provided on the Tivoli Identity Manager service form


RACF resources that require consideration are as follows:

FIELD class profile USER.segment.**, with UPDATE

FIELD class profiles are required when the adapter, or surrogate, does not

have the SYSTEM SPECIAL attribute.

FACILITY class profile STGADMIN.IGG.DEFDEL.UALIAS, with READ

The STGADMIN.IGG.DEFDEL.UALIAS may be required if catalog aliases

are created in the ITIMEXIT or ITIMEXEC adapter exit points.

FACILITY class profile IRR.PASSWORD.RESET, with UPDATE

IRR.PASSWORD.RESET is required if the effective RACF ID performing

password changes does not have the SYSTEM SPECIAL RACF attribute.

SURROGAT class profile ATBALLC.userid, with READ

The surrogate profile is required if the adapter RACF ID differs from the

RACF ID under which commands and reconciliations are executed.

APPCLU class profile vtamnode.appcname.appcname, with SESSION segment

The APPCLU profile is required.

FACILITY class profile BPX.NEXT.USER, with APPLDATA(’uid/’)

BPX.NEXT.USER is required if AUTOUID support is used.

UNIXPRIV class profile SHARED.IDS, with xxxx access

The adapter, or surrogate, will require access to this profile if the Tivoli

Identity Manager Server will be creating RACF ID’s with OMVS segments

where duplicate UID’s are created.

CLAUTH with class of USER

CLAUTH of USER will be required if the adapter, or surrogate, RACF ID

will create RACF users, when the creating ID does not have SYSTEM

SPECIAL.

Note: Details on the use of these RACF profiles are provided later in this

document.

APPC transactions must be registered. APPCCMD and APPCRECO jobstreams

must be customized and executed to register these transactions with APPC/MVS.

The VSAM file must be created for use by the reconciliation process. The RACF ID

specified on the service form or the default RACF ID configured for the adapter

must have UPDATE access to this file.

Chapter 1. Overview of the RACF adapter 5


Chapter 2. Adapter interactions with the Tivoli Identity

Manager Server

By default, the RACF adapter does not enable SSL, nor does it install any digital

certificates. If you enable SSL, post configuration steps are required.

The RACF adapter is designed to perform functions as requested by the Tivoli

Identity Manager server. These basic functions are to add, modify or delete objects

in RACF, and to supply RACF data to Tivoli Identity Manager.

The communications path is established using TCP/IP. Additionally, SSL (Secure

Sockets Layer) is implemented to secure the communications between Tivoli

Identity Manager and the RACF adapter.

SSL requires the use of digital certificates and private keys to establish

communications between endpoints. The RACF endpoint is considered a server.

When the SSL protocol is utilized, the server endpoint must contain (as a

minimum) a digital certificate and private key. The client endpoint must have (as a

minimum) either a copy of the digital certificate of the server endpoint, or access

to the Certificate Authority that signed the RACF adapter’s certificate. SSL

communication is enabled by default, which requires the generation and

installation of a digital certificate and a private key on the adapter. If you are

generating a self-signed certificate, the certificate must be installed on the Tivoli

Identity Manager server. If you do not have a certificate/key pair to install, turn

SSL communications off until one is obtained and installed.

On the z/OS host, the default TCP/IP port utilized for adapter/server

communications is port 45580. This port number may be configured to utilize

another port of your choosing. This port number must be coded on an Tivoli

Identity Manager service form that references the z/OS host.

Additionally, the adapter requires the ability to be configured through a utility

called agentCfg. This utility communicates to the RACF adapter through TCP/IP.

The TCP/IP port number utilized for this purpose is dynamic; it is not a

configurable item. This allows for multiple instances of a RACF adapter to coexist

on the same z/OS platform. Although the port numbers utilized are dynamic, only

a specific range of port numbers may be utilized. Any instance of the RACF

adapter will attempt to listen on the lowest numbered port in the range, provided

it is not already in use by another instance of the adapter. The range of TCP/IP

port numbers utilized for adapter configuration is 44970 through 44994. This range

of port numbers is not configurable.

Depending upon your installation’s requirements, you may choose to restrict the

use of these ports for the use of the RACF adapter. The preferred method of

protecting the use of these ports is utilizing RACF protection, by defining profiles

in the RACF SERVAUTH resource class. For further information, please reference

z/OS Communications Server, IP Configuration Guide, (Document Number SC31-8775).



Chapter 3. Installing and configuring the RACF adapter

Installing and configuring the RACF Adapter involves several steps that you must

complete in the appropriate sequence. Review the prerequisites before you begin

the installation process. You can also create an account on the managed resource

for the adapter to use.

Basic installation

The following lists the basic procedures necessary to install, configure, and run the

adapter:

1. Upload the distribution data set downloaded from IBM’s web site to the MVS

host.

2. Install MVS executables

3. Install UNIX executables

4. Configure UNIX component

5. Configure MVS backend component

a. Set up RACF environment specifics

b. Set up started task JCL6. Import the adapter profile into the Tivoli Identity Manager Server.

7. Configure server

8. Activate the RACF Adapter.

Prerequisites

Table 1 identifies hardware, software, and authorization prerequisites for installing

the RACF Adapter. Verify that all of the prerequisites have been met before

installing the RACF Adapter.

Table 1. Prerequisites to install the adapter

Operating System v z/OS version 1.4

v z/OS version 1.5

v z/OS version 1.6

Network Connectivity TCP/IP network

Server Communication Communication should be tested with a

low-level communications ping from the

Tivoli Identity Manager Server to the MVS

Server. This makes troubleshooting easier if

you encounter installation problems.

Tivoli Identity Manager Server Version 4.6

Organizations with multiple RACF databases should have an RACF Adapter

installed on an MVS host that manages the database.

A single RACF database can be managed by a single instance of the RACF adapter.

Support for Sysplex failover is not implemented. However, in the event a

participating image of the Sysplex is inoperative, an alternate instance of the


adapter may be started on a different image within the Sysplex. You must already

have this type of environment set up and the necessary resources available. The

related service instance on the Tivoli Identity Manager Server may require

updating, if the alternate image is known through a different IP address.

Installation worksheet

Use the following worksheet to document information required to install and

configure the RACF Adapter. Complete this worksheet before starting the

installation procedure. The worksheet identifies the information you need to

modify during the installation process.

Make a copy of the worksheet for each server where you are installing the RACF

Adapter. For example, if you have five Windows servers where you are installing

the Lotus Notes Agent, you need five copies of the worksheet.

Table 2. Installation worksheet

Option Description, default, note Value

MVS data set name The MVS data set high level qualifier

for upload and installation.

APPC/MVS logical

unit name

If APPC/MVS Logical Unit (LU)

names are left unspecified, the UNIX

System Services component will

utilize the APPC/MVS baselu value

that was declared while configuring

the APPC/MVS.

Your installation may wish to use a

separate set of LU’s for use with the

RACF adapter, to avoid interference

with your installation’s baselu

definitions. If this is the case, then you

must know these two LU names.

These LU’s must be defined and

activated, prior to execution of the

RACF Adapter.

v Originating LU name, if desired.

This LU must be configured into

APPC/MVS with NOSCHED.

v Destination LU name, if desired.

This LU must be configured into

APPC/MVS with SCHED(ASCH).

For additional information, please

refer to: z/OS MVS Planning:

APPC/MVS Management, Document

Number SA22-7599.

Adapter instance

name

The default is racfagent. There is no

maximum length, but the length

should be manageable. This value will

be specified in the config.sh UNIX

System Services shell script.

APPC/MVS

reconciliation

transaction name

The default is ITIMRECO. The

recommended length is eight

characters. The JCL member is

APPCRECO.


Table 2. Installation worksheet (continued)


APPC/MVS

command executor

transaction name

The default is ITIMCMD. The

recommended length is eight

characters. The JCL member is

APPCCMD.

VSAM file name This file was created with the JCL

ITIMVSAM and is referenced in the

JCL APPCRECO.

VSAM file size Size in cylinders. This file was created

with JCL ITIMVSAM.

Started task name There is a maximum of seven

characters, specified in the started JCL

ITIAGNT task.

Adapter port number The default is 45580. This value is

specified in the config.sh UNIX

System Services shell script.

Default certificate

and key

The default certificate and key are

provided in ./data/damlserver.pfx. A

certificate other than the default must

be created and installed manually. See

Chapter 5, “Configuring SSL

authentication for the RACF adapter,”

on page 71 for more information.

Installation path for

the adapter

The UNIX System Services file system

should have at least 80 megabytes of

space available. This path name is

specified in install.sh and config.sh

UNIX System Services shell script.

Data set size

adjustment

Temporary data set sizes in

reconciliation should be adjusted

according to the size of the RACF

database unload for your installation.

If the VSAM group file is utilized, its

size should be adjusted, following an

initial reconciliation.

For the UNIX System Services

components, it is recommended that

approximately 80 megabytes of space

be available in the file system. If a

separate file system is created for

these components, it should not be

shared with other systems.

Chapter 3. Installing and configuring the RACF adapter 11



APPC/MVS mode

name

For communication to be established

between two end points with

APPC/MVS, SNA (Systems Network

Architecture) requires a set of session

parameters, or a bind image to

accomplish this. This is referred to

through optional specification of a

Mode Name in the RACF adapter.

If left unspecified, APPC/MVS will

generate acceptable session

parameters, allowing communication

to occur.

Optionally, you may specify a named

set of session parameters that have

been predefined. These session

parameters are selected through

specification of a Mode Name, when

configuring the adapter. A Mode

Name is an 8 character string, that

represents a predefined set of session

parameters.

For additional information, please

refer to: z/OS MVS Planning:

APPC/MVS Management, Document

Number SA22-7599.

VSAM file name for

scoped reconciliation

If scoped reconciliation is to be

performed, a VSAM file is required

(job ITIMVSAM). You can name the

VSAM file to correspond to an

adapter instance name.

If scoped reconciliation is NOT

performed, a VSAM file is not

required, and reconciliation

transaction does not require program

steps that execute ITIMGSCP. Also, a

GROUP DD statement is not required

for the ITIMREC2 program step.

Started task name Specify a name for the started task for

an adapter instance. The ITIAGNT

member is the sample JCL provided

for the adapter startup. It is

recommended a component of the

started task name be indicative of the

adapter instance name. It is

recommended that the started task

name be limited to no more than 7

characters, to eliminate ambiguity

when shutting down the adapter.




Adapter port number The TCP/IP port number to be

utilized by the adapter. This will be

entered when configuring the UNIX

System Services component. Each

adapter instance should have a unique

TCP/IP port number. If two adapters

have utilize the same port number,

only one of the adapters may be

active at any one time.

RACF adapter activation checklist

Complete the following checklist for activating the RACF Adapter.

1. Upload the adapter package.

2. Install the MVS executables.

3. Install the UNIX executables.

4. Configure the UNIX component.

5. Configure the MVS backend component.

a. Set up the RACF environment variables.

b. Set up the started task, JCL.6. Install the adapter profile on the Tivoli Identity Manager Server.

7. Configure the server.

8. Activate the RACF Adapter.

9. Run the adapter test to ensure end-to-end connectivity.

Step 1: Upload the adapter package

This procedure describes the process of uploading and receiving the installation

package on the MVS platform.

1. The Tivoli Identity Manager RACF Adapter installation package is available for

download from IBM’s Web site. Contact your IBM account representative for

the Web address and download instructions.

For reference, we will assume this file is named ITIM.UPLOAD.XMI.

2. On MVS, create a sequential file, with RECFM=FB, LRECL=80, with a primary

allocation of 30 megabytes (approximately 25 cylinders on a 3390).


Menu RefList Utilities Help

_____________________________________________________________________________

Data Set Utility

Option ===> A

A Allocate new data set C Catalog data set

R Rename entire data set U Uncatalog data set

D Delete entire data set S Short data set information

blank Data set information V VSAM Utilities

ISPF Library:

Project . . IBMUSER Enter "/" to select option

Group . . . PDS / Confirm Data Set Delete

Type . . . . CNTL

Other Partitioned, Sequential or VSAM Data Set:

Data Set Name . . . ITIM.UPLOAD.XMI

Volume Serial . . . (If not cataloged, required for option "C")

Data Set Password . . (If password protected)

Menu RefList Utilities Help

_____________________________________________________________________________

Allocate New Data Set

Command ===>

Data Set Name . . . : IBMUSER.ITIM.UPLOAD.XMI

Management class . . . (Blank for default management class)

Storage class . . . . (Blank for default storage class)

Volume serial . . . . (Blank for system default volume) **

Device type . . . . . (Generic unit or device address) **

Data class . . . . . . (Blank for default data class)

Space units . . . . . mb (BLKS, TRKS, CYLS, KB, MB, BYTES

or RECORDS)

Average record unit (M, K, or U)

Primary quantity . . 30 (In above units)

Secondary quantity 2 (In above units)

Directory blocks . . 0 (Zero for sequential data set) *

Record format . . . . FB

Record length . . . . 80

Block size . . . . .

Data set name type : (LIBRARY, HFS, PDS, or blank) *

(YY/MM/DD, YYYY/MM/DD

Expiration date . . . YY.DDD, YYYY.DDD in Julian form

Enter "/" to select option DDDD for retention period in days

Allocate Multiple Volumes or blank)

( * Specifying LIBRARY may override zero directory block)

( ** Only one of these fields may be specified)

3. From your workstation, upload, in BINARY, the ITIM.UPLOAD.XMI file from

your workstation to the MVS pre-allocated file you just created.


C:\temp>ftp mvs.mycompany.com

Connected to 192.168.1.1.

220-FTPD1 IBM FTP CS V1R4 at mvs.mycompany.com, 18:42:22 on 2003-11-10

220 Connection will close if idle for more than 5 minutes.

User (192.168.1.1:(none)): ibmuser

331 Send password please.

Password:

230 IBMUSER is logged on. Working directory is "IBMUSER.".

ftp> binary

200 Representation type is Image

ftp> put itim.upload.xmi

200 Port request OK.

125 Storing data set IBMUSER.ITIM.UPLOAD.XMI

250 Transfer completed successfully.

ftp: 19627440 bytes sent in 20.58Seconds 953.71Kbytes/sec.

ftp> quit

221 Quit command received. Goodbye.

C:\temp>

4. Execute the following command from the TSO shell command prompt:

RECEIVE INDATASET(ITIM.UPLOAD.XMI)

When prompted for parameters, accept the defaults by pressing Enter. This will

create a partitioned dataset named ITIM.UPLOAD.

In ITIM.UPLOAD will be four members:

Table 3. RACF Adapter package contents

INSTALL1 A REXX exec that generates JCL used to unpack and install the remainder of

the installables.

XCNTL XMIT format installation data set.

XEXEC XMIT format REXX execs.

XLOAD XMIT format MVS load library with executables.

XTAR XMIT format TAR file, to be installed in UNIX System Services.

The directories and files that will be created during the installation process are

show in the following table:


Table 4. Install directories and files

MVS load library

ITIMGSCP Group tree scoping build

program

ITIMRECO Stage 1 reconciliation,

reformatting and

transformation.

ITIMREC2 Stage 2 reconciliation,

scoping and conveyance to

adapter proper.

UNIX System Services directory

./lib ErmApiDaml.so DAML protocol DLL

libicudata26.1.dll ICU (International

Components for Unicode)

data DLL

libicui18n26.1.dll ICU DLL

libicuuc26.1.dll ICU DLL

libAdkApi.dll ADK (Agent Developer Kit)

library DLL

libErmApi.dll ERMA (Enrole Remote

Management API) library

DLL

./bin certTool Tool to create digital

certificates.

agentCfg Adapter configuration tool.

Can only be utilized once

adapter is initialized.

racfAgent Main RACF adapter

executable.

regis Registry creation tool.

ermtool Tool to test adapter, without

a server.

IsamTool Tool to debug problems with

Event Notification ISAM file.

./log Will contain the logs created

by adapter.

./data Will contain the Adapter

Registry (or registries)

Step 2: Install the MVS executables

Execute the REXX exec called INSTALL1 to create an MVS job to unpack the

remainder of the ITIM.UPLOAD file.

This REXX script allows for the generation of a batch job stream to unpack the

MVS components, or the files may be interactively unpacked. This script may be

run repeatedly. If the batch job stream is generated, it may also be re-executed.

Execute the exec from the TSO shell command prompt:

exec ’ibmuser.itim.upload(install1)’


You will be prompted for a high level qualifier for four MVS data sets to be

extracted. You will also be prompted for a UNIX System Services directory into

which two files will be placed. The UNIX System Services directory must exist,

and you must have permission to create these files in the directory.

This script will gives the option of creating a batch job stream or installing the files

during the execution of the script. The following scenario reflects the instream

installation of the files. If a batch job is chosen to be generated, the member

INSTALLB will be placed into the data set where INSTALL1 exists.

##########################################################

# #

# Tivoli Identity Manager RACF agent installation #

# ...step 1... #

# #

##########################################################

This is step 1 in the installation process which will

unpack the file you are executing this REXX exec from.

There will be 4 output files created from this exec,

and two files will be placed in the USS file system.

The default high level qualifier for these data sets will be

--------> IBMUSER.ITIM

Do you want to change this high level qualifier? (Y/N)

n

You must provide a Unix System Services directory into which

two files must be placed.

This directory must already exist.

The files transfered into Unix System Services will be:

1) ’IBMUSER.ITIM.CNTL(INSTALL2)’ as file ’install.sh’

2) ’IBMUSER.ITIM.CNTL(INSTALL3)’ as file ’config.sh’

3) ’IBMUSER.ITIM.TAR’ as file ’racf.tar’.

This directory name is CaSe SeNsItIvE!

Please enter a fully qualified Unix directory path:

/u/ibmuser/itim

The directory chosen is /u/ibmuser/itim.

Is this directory name correct? (Y/N)

y

The path used will be /u/ibmuser/itim.

Do you wish to create a batch job stream, or would you rather

complete the file extraction online?

Enter ’BATCH’ or ’ONLINE’ (case insensitive):

online

This exec will exit, and execute the following commands.

In the event there is an error, you may re-run this exec,

after having corrected the error.

Here are the commands:

RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XCNTL)’)

DATASET(’IBMUSER.ITIM.CNTL’)

RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XEXEC)’)

DATASET(’IBMUSER.ITIM.EXEC’)

RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XLOAD)’)

DATASET(’IBMUSER.ITIM.LOAD’)

RECEIVE INDA(’IBMUSER.ITIM.UPLOAD(XTAR)’)

DATASET(’IBMUSER.ITIM.TAR’)

OPUT ’IBMUSER.ITIM.CNTL(INSTALL2)’ ’/u/ibmuser/itim/install.sh’

OPUT ’IBMUSER.ITIM.CNTL(INSTALL3)’ ’/u/ibmuser/itim/config.sh’

OPUT ’IBMUSER.ITIM.TAR’ ’/u/ibmuser/itim/racf.tar’ BINARY

Now exiting and executing the above commands...

The results from executing the INSTALL1 exec will be the following four MVS data

sets:

v ITIM.CNTL


v ITIM.EXEC

v ITIM.LOAD

v ITIM.TAR

Three UNIX System Services files, placed into the specified directory, named:

v config.sh

v install.sh

v racf.tar

Step 3: Install the UNIX System Services executables

If the INSTALLB job ran successfully or the files were unpacked interactively, there

will be two files in the directory you chose (in this example /u/itim).

You must enter the UNIX System Services shell environment from TSO or a telnet

session with the following command:

omvs

Change to the directory where these files were placed. This will be the install path

entered in step 2 above. Execute the following command:

sh install.sh

When running the adapter UNIX System Services installation script, there are

several items which you must provide information for during the installation:

v The fully qualified adapter installation directory.

v Whether or not you want to install the executables. This only needs to be done

once. If configuring the adapter, it is not required to reinstall the executables.

The following is a sample UNIX System Services shell session, running the

installation script.


IBM

Licensed Material - Property of IBM

5694-A01 (C) Copyright IBM Corp. 1993, 2001

(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.

(C) Copyright Software Development Group, University of Waterloo, 1989.

All Rights Reserved.

U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or

Disclosure restricted by GSA-ADP schedule contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

IBMUSER:/: >cd /u/ibmuser/itim

IBMUSER:/u/ibmuser/itim: >ls -l

total 82880

-rw------- 1 ZFS SYS1 34587 Oct 7 14:32 config.sh

-rw------- 1 ZFS SYS1 9558 Oct 7 14:32 install.sh

-rwx------ 1 ZFS SYS1 42384384 Oct 7 14:32 racf.tar

IBMUSER:/u/ibmuser/itim: >sh install.sh

***********************************************************************

* IBM Tivoli Identity Manager - RACF Agent Installation *

* ...step 2 *

***********************************************************************

Enter racf Agent absolute (or full) installation directory

/u/ibmuser/itim

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

Do you want to install the racf Agent now? (Y/N):

y

Installing racf Agent files

USTAR Version 00

x ., 0 bytes, 0 tape blocks

x ./bin, 0 bytes, 0 tape blocks

x ./bin/agentCfg, 1843200 bytes, 3600 tape blocks

x ./bin/ermtool, 1155072 bytes, 2256 tape blocks

x ./bin/racfAgent, 323584 bytes, 632 tape blocks

x ./bin/racfAgent, 323584 bytes, 632 tape blocks

x ./bin/regis, 1568768 bytes, 3064 tape blocks

x ./bin/CertTool, 5181440 bytes, 10120 tape blocks

x ./bin/IsamTool, 1077248 bytes, 2104 tape blocks

x ./data, 0 bytes, 0 tape blocks

x ./data/damlserver.pfx, 1581 bytes, 4 tape blocks

x ./lib, 0 bytes, 0 tape blocks

x ./lib/libicudata26.1.dll, 17031168 bytes, 33264 tape blocks

x ./lib/libicui18n26.1.dll, 4325376 bytes, 8448 tape blocks

x ./lib/libicuuc26.1.dll, 3174400 bytes, 6200 tape blocks

x ./lib/libAdkApi.dll, 1687552 bytes, 3296 tape blocks

x ./lib/libErmApi.dll, 1003520 bytes, 1960 tape blocks

x ./lib/ErmApiDamlO.so, 3997696 bytes, 7808 tape blocks

x ./log, 0 bytes, 0 tape blocks

Installation ended.

IBMUSER:/u/ibmuser/itim: >

In the above example, we have only installed the adapter executables.

Step 4: Configure the UNIX System Services Component

To configure the UNIX System Services component, you must get into the OMVS

shell. By default, SSL is not enabled, and will not be configured by using the

config.sh script. However, the following example does use the config.sh script.

Change into the directory where the config.sh shell script exists, and execute it.

sh config.sh


You will be prompted as to whether you wish to install or configure. Choose the

option to configure. This configuration process will create what is known as an

adapter registry file, which contains the adapter options, and a digital certificate.

There are many options that may be set within an adapter registry file, but this

initial process will configure those options to get the adapter up, running, and

connected to the server.

What follows is an example session with the config.sh script, navigating through

configuration:

IBMUSER:/u/ibmuser/itim: >ls -l

total 82944

drwxrwxr-x 2 ZFS SYS1 8192 Sep 30 11:57 bin

-rw------- 1 ZFS SYS1 34587 Oct 7 14:32 config.sh

drwxrwxr-x 2 ZFS SYS1 8192 Sep 24 15:00 data

-rw------- 1 ZFS SYS1 9558 Oct 7 14:32 install.sh

drwxrwxr-x 2 ZFS SYS1 8192 Sep 29 09:28 lib

drwxrwxr-x 2 ZFS SYS1 8192 Sep 21 12:00 log

-rwx------ 1 ZFS SYS1 42384384 Oct 7 14:32 racf.tar

IBMUSER:/u/ibmuser/itim: >sh config.sh

***********************************************************************

* IBM Tivoli Identity Manager - RACF Agent Configuration *

* ...step 3 *

***********************************************************************

Enter racf Agent absolute (or full) installation directory

/u/ibmuser/itim

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

No agent name has been chosen, and will default to

-----> racfAgent <-----

Do you wish to change the agent name? (Y/N):

n

Agent name will be racfAgent

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

Do you want to configure the racf Agent now? (Y/N):

y

Creating configuration data

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

The default TCP/IP port number used is 45580.

Do you wish to use a different port number? (Y/N):

n

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

The default APPC transaction name for the command executor

is ITIMCMD.

Do you wish to use a different the transaction name? (Y/N):

n

APPC command executor transaction name is set to ITIMCMD

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

The default APPC transaction name for reconciliation

is ITIMRECO.

Do you wish to use a different the transaction name? (Y/N):

n

APPC reconciliation transaction name is set to ITIMRECO

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


The APPC/MVS BASELU will be the originating Logical Unit (LU)

name.

Do you wish to set a specific originating LU name? (Y/N):

y

Enter a 1 to 8 character APPC/MVS originating LU name:

itimorig

APPC/MVS originating LU name is set to ITIMORIG

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

The APPC/MVS destination logical unit (LU) name will be the

same as the origination LU name, unless specified.

Do you wish to set a specific destination LU name? (Y/N):

y

Enter a 1 to 8 character APPC/MVS destination LU name:

itimdest

APPC/MVS destination LU name is set to ITIMDEST

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

The APPC/MVS ’mode name’ may be allowed to default, or you

may wish to utilize a specific mode name.

Do you wish to set a APPC/MVS mode name? (Y/N):

y

Enter a 1 to 8 character APPC/MVS mode name:

#intersc

APPC/MVS mode name is set to #INTERSC

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

By default, when this agent is requested to set a password,

they will be set as EXPIRED (password change forced at next

logon).

Do you wish the agent to set NON-EXPIRED passwords? (Y/N):

y

PASSEXPIRE agent option is set to FALSE

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

The full set of parameters set for the adapter are as follows:

/u/ibmuser/itim/bin/regis -reg /u/ibmuser/itim/data/RACFAGENT.dat -list -protocol DAML

Registry listing for Agent ’/u/ibmuser/itim/data/RACFAGENT.dat’

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

Specific:ENROLE_VERSION ’4.0’

Specific:APPCCMD ’ITIMCMD’

Specific:APPCRECO ’ITIMRECO’

Specific:APPCOLU ’ITIMORIG’

Specific:APPCDLU ’ITIMDEST’

Specific:APPCMODE ’#INTERSC’

Specific:PASSEXPIRE ’FALSE’

Main:InstallPath ’/u/ibmuser/itim’

Main:Agent_LogDir ’/u/ibmuser/itim/log’

Main:Agent_LogFile ’racfagent.log’

Main:Agent_ConfiguredProt ’DAML’

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

The startup script, if it has not been created,

must exist for the MVS started task to be initiated

Create the racf Agent startup script? (Y/N):

y


Creating startup script

When you edit the started task JCL, on the line that has

the PARM= statement, you will enter the full path and

file name of the script, which is:

/u/ibmuser/itim/bin/racfagent.sh

Configuration ended.

IBMUSER:/u/ibmuser/itim: >

The result of running the USS installation script will be:

v A registry file, in the data/ subdirectory, with the adapter name. (for example,

TESTAGENT.dat)

v A startup script file, for use of the started task JCL, in the bin/ directory. (for

example, testagent.sh). The fully qualified name of this shell script must be

inserted into the started task JCL. For example, if the installation directory is

/u/itim, then the started task JCL will require /u/itim/bin/testagent.sh to be

inserted.

v If or when you wish to add, alter, or remove specific adapter options from a

particular adapter instance, you will have to utilize the agentCfg utility,

described in Chapter 4, “Configuring the RACF adapter in IBM Tivoli Identity

Manager,” on page 39.

For the valid RACF adapter registry options, their values and meanings, refer to

Appendix B, “Registry settings,” on page 107.

For more information on how to use agentCfg to modify registry settings, refer to

“Changing registry settings” on page 63.

Step 5: Configure MVS Components

There are several steps to complete when configuring the MVS components of the

RACF Adapter. The jobs that must be run are contained in the ITIM.CNTL data

set:

1. Register the command executor to APPC/MVS

2. Configure the APPC/MVS reconciliation transaction, and register to

APPC/MVS.

3. OPTIONAL: Create the VSAM file for reconciliation scoping function.

4. Create the started task JCL.

5. Establish a RACF user ID under which the adapter will operate.

OPTIONAL:Establish one or more RACF surrogate user ID’s, under which

requests will be processed.

Modify and submit the APPCCMD job

Modify the APPCCMD job in the ITIM.CNTL data set. You must set the TPNAME

field to a chosen APPC/MVS transaction name. It is highly recommended the

APPC transaction name NOT exceed 8 characters, as this will allow the job name

on the job card match the transaction name. A recommended transaction name is

ITIMCMD. This transaction JCL must reference the ITIM.EXEC library, where

REXX execs reside. It is suggested the job name match the transaction name.


If your installation stores messages in users’ individual message log data sets,

instead of storing user messages in the SYS1.BRODCAST data set, you should

remove the //SYSLBC DD statement from the job stream.

Follow the instructions detailed in the JCL for configuration, taking note of the

chosen APPC/MVS transaction name.

Submit the job. Ensure successful execution. First execution of the job will result in

the first step (transaction deletion) failing. This is expected.

//APPCCMD JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID

//******************************************************************

//*LICENSED MATERIALS - PROPERTY OF IBM

//*

//*SOURCE FILE NAME = APPCCMD

//*

//*(C) COPYRIGHT IBM CORP. 1999, 2003 ALL RIGHTS RESERVED

//*

//*US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION OR

//*DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE CONTRACT WITH IBM CORP.

//******************************************************************

//*

//* THIS JCL IS USED TO REGISTER THE APPC/MVS TRANSACTION

//* FOR THE TIVOLI IDENTITY MANAGER COMMAND TRANSACTION.

//*

//* YOU MUST HAVE RACF UPDATE ACCESS TO THE APPC TRANSACTION PROFILE

//* DATA SET TO EXECUTE THIS JOB. IF YOUR INSTALLATION HAS

//* UTILIZED THE PROGRAM CLASS TO PROTECT THE ATBSDFMU UTILITY,

//* THEN AN AUTHORIZED USER MUST HAVE ACCESS TO THIS UTILITY TO

//* EXECUTE THIS JOB.

//*

//* YOU MUST CUSTOMIZE THIS TRANSACTION, PRIOR TO SUBMITTING THIS

//* JCL TO REGISTER THE TRANSACTION.

//*

//* 1. CUSTOMIZE THE JOB CARD TO REFLECT YOUR INSTALLATION STANDARDS.

//*

//* 2. CHANGE THE ?SYSAPPCTP? TEXT TO REFLECT YOUR INSTALLATION’S

//* APPC/MVS TRANSACTION PROFILE DATA SET. IN MANY INSTALLATIONS,

//* THIS MAY BE "SYS1.APPCTP".

//*

//* 3. CHANGE ?ITIMEXEC? TO REFLECT THE TIVOLI IDENTITY MANAGER

//* AGENT EXEC DATA SET INSTALLED. THIS DATA SET SHOULD CONTAIN

//* ALL THE EXECS UTILIZED BY THE AGENT.

//*

//* 4. CHANGE ?APPCCMD? TO REFLECT THE APPC/MVS TRANSACTION NAME

//* CHOSEN FOR THE COMMAND TRANSACTION. THIS IS THE SAME

//* TRANSACTION NAME CONFIGURED INTO THE UNIX COMPONENT.

//*

//* 5. IF YOU ARE NOT UTILIZING THE SYS1.BRODCAST DATA SET FOR YOUR

//* INSTALLATION, YOU MAY REMOVE THE "SYSLBC" DD STATEMENT, THAT

//* REFERENCES SYS1.BRODCAST.

//*

//*

//* THE FIRST TIME THIS JOB IS RUN, THE "TPDELETE" WILL FAIL, AS

//* THE TRANSACTION DOES NOT EXIST. THIS IS NORMAL.

//*

//*


//TPDELETE EXEC PGM=ATBSDFMU,REGION=0K

//SYSPRINT DD SYSOUT=*

//SYSSDLIB DD DSN=?SYSAPPCTP?,DISP=SHR

//SYSSDOUT DD SYSOUT=*

//SYSIN DD *

TPDELETE

TPNAME(?APPCCMD?)

SYSTEM

//TPADD EXEC PGM=ATBSDFMU,REGION=0K




//SYSIN DD DATA,DLM=XX

TPADD

TPNAME(?APPCCMD?)

SYSTEM

ACTIVE(YES)

TPSCHED_DELIMITER(##)

TAILOR_SYSOUT(NO)

TAILOR_ACCOUNT(NO)

KEEP_MESSAGE_LOG(NEVER)

CLASS(A)

TPSCHED_TYPE(STANDARD)

JCL_DELIMITER(END_OF_JCL)

//?APPCCMD? JOB

//IKJEFT01 EXEC PGM=IKJEFT01,REGION=0K,PARM=’%ITIMCMD’

//SYSPROC DD DSN=?ITIMEXEC?,DISP=SHR

//SYSLBC DD DISP=SHR,DSN=SYS1.BRODCAST

//SYSTSPRT DD SYSOUT=*,FREE=CLOSE

//SYSTSIN DD DUMMY

END_OF_JCL

##

XX

Modify and submit the APPCRECO job

Modify the APPCRECO job stream in the ITIM.CNTL data set. You must set the

TPNAME field to a chosen APPC/MVS transaction name. It is highly

recommended the APPC transaction name NOT exceed 8 characters, as this will

allow the job name on the job card match the transaction name. A recommended

transaction name is ITIMRECO. This transaction JCL must be tailored for your

installation.

Sizes of the temporary data sets must reflect the amount of space consumed by the

output from the RACF IRRDBU00 program for your installation.

The execution step of IRRDBU00 must reference your RACF database properly. If

database updates are mirrored to the RACF backup database, then the execution of

the IRRDBU00 utility may reference the backup data set, for performance

considerations. UPDATE access to the RACF database is required, even though the

RACF utility IRRDBU00 does NOT update the database. This is restriction to the

use of the IRRDBU00 utility.

If partial, or ’scoped’ reconciliation is to be utilized, a VSAM file must be created

(in the ITIMVSAM job), and referenced in the ITIMGSCP program step, and the

ITIMREC2 step.

If only full reconciliation is to be utilized, the VSAM file is not required, the

ITIMGSCP step may be eliminated, and the GROUP dd statement in the ITIMREC2

program step may be eliminated.

Submit the job. Insure successful execution. First execution of the job will result in

the first step (transaction deletion) failing. This is expected.


//APPCRECO JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID

//******************************************************************


//*

//*SOURCE FILE NAME = APPCRECO

//*


//*



//******************************************************************

//*

//* THIS JCL IS USED TO REGISTER THE APPC/MVS TRANSACTION

//* FOR THE TIVOLI IDENTITY MANAGER RECONCILIATION PROCESS.

//*

//* YOU MUST CUSTOMIZE THIS TRANSACTION, PRIOR TO SUBMITTING THIS

//* JCL TO REGISTER THE TRANSACTION.

//*

//* 1. CUSTOMIZE THE JOB CARD TO REFLECT YOUR INSTALLATION STANDARDS.

//*

//* 2. CHANGE THE ?SYSAPPCTP? TEXT TO REFLECT YOUR INSTALLATION’S

//* APPC/MVS TRANSACTION PROFILE DATA SET. IN MANY INSTALLATIONS,

//* THIS MAY BE "SYS1.APPCTP".

//*

//* 3. CHANGE ?ITIMLOADLIB? TO REFLECT YOUR INSTALLATION’S NAME OF

//* THE TIVOLI IDENTITY MANAGER AGENT LOAD LIBRARY.

//*

//* 4. CHANGE ?APPCRECO? TO REFLECT THE APPC/MVS TRANSACTION NAME

//* CHOSEN FOR THE COMMAND TRANSACTION. THIS IS THE SAME

//* TRANSACTION NAME CONFIGURED INTO THE UNIX COMPONENT.

//*

//* 5. FOR THE IRRDBU00 STEP:

//* THIS STEP MAY BE OMITTED, IF YOU WISH TO RUN THE IRRDBU00

//* PROGRAM OUTSIDE OF THIS APPC TRANSACTION.

//*

//* YOU MUST CODE IN ALL THE DATA SETS THAT COMPRISE YOUR

//* INSTALLATION’S RACF DATABASE.

//* THE ?RACFDB1?, AND POTENTIALLY, ?RACFDB2? THROUGH ?RACFDB"N"?

//* WILL HAVE TO BE CODED, TO INCLUDE ALL THE RACF DATA SETS

//* THAT COMPRISE YOUR ENTIRE RACF DATA BASE.

//*

//* THE USER ID THIS TRANSACTION RUNS AS MUST HAVE UPDATE ACCESS

//* TO THE RACF DATABASE, AS THE IRRDBU00 PROGRAM MUST HAVE

//* UPDATE UPDATE ACCESS TO THE FILES THAT COMPRISE THE RACF

//* DATABASE, EVEN THOUGH NO UPDATES OCCUR.

//*

//* IT IS -RECOMMENDED- THAT "NOLOCKINPUT" BE USED AS A

//* EXECUTION PARAMETER TO THE IRRDBU00 PROGRAM. IF "LOCKINPUT"

//* IS SPECIFIED, THEN ANOTHER INSTANCE OF IRRDBU00 MUST BE

//* EXECUTED, WITH THE "UNLOCKINPUT" PARAMETER SPECIFIED.

//*

//* IF YOUR INSTALLATION HAS SET THE ICHRDSNT OPTION TO

//* DUPLICATE ALL UPDATES TO THE BACKUP DATABASE, IT IS

//* SUGGESTED THE BACKUP DATABASE IS SPECIFIED FOR RUNNING

//* IRRDBU00. PLEASE REFER TO THE "RACF SECURITY

//* ADMINISTRATOR’S GUIDE" FOR MORE INFORMATION ABOUT THE RACF

//* DATABASE UNLOAD UTILITY.

//*

//* 6. FOR THE ITIMRECO STEP:

//* IF YOU HAVE CHOSEN NOT TO RUN THE IRRDBU00 UTILITY IN THIS

//* JOBSTREAM, THEN YOU MUST SPECIFY THE APPROPRIATE DATA SET AS

//* INPUT TO THIS PROGRAM ON THE RACFIN DD STATEMENT. INSURE

//* YOU CODE DISPOSITION APPROPRIATELY, AS THE DEFAULT IS TO

//* DELETE THE INPUT FILE.

//*

//* INSURE THE SPECIFICATIONS FOR SPACE REFLECT THE AMOUNT OF

//* SPACE REQUIRED BY YOUR INSTALLATION’S OUTPUT FROM THE RACF

//* DATABASE UNLOAD UTILITY.

//*


//*

//* DO NOT CHANGE ANY OF THE REFERBACKS SPECIFIED IN THIS STEP,

//* AS THEY ARE NECESSARY FOR PROPER OPERATION. YOU MAY CHANGE

//* THE SPECIFICATION OF UNIT=SYSALLDA, TO A PROPER SMS STORAGE

//* CLASS THAT IS INTENDED FOR TEMPORARY DATA SETS.

//*

//* 7. FOR THE ITIMGSCP STEP:

//* THIS IS NOT REQUIRED -ONLY- IF THE RECONCILIATION

//* PROCESS WILL -ALWAYS- BE A FULL RECONCILIATION.

//* IF A ONLY A PORTION OF THE RACF DATABASE IS TO BE

//* RECONCILED, BASED UPON RACF SCOPE-OF-AUTHORITY RULES, THEN

//* THIS STEP, AND THE VSAM FILE DEFINITION, ARE REQUIRED.

//*

//* IF THIS STEP IS USED, CHANGE ?HLQ? TO REFLECT THE

//* VSAM FILE NAME CREATED BY THE ITIMVSAM JOBSTREAM.

//*

//* 8. FOR THE ITIMREC2 STEP:

//* THE GROUP DD STATEMENT IS NOT REQUIRED, ONLY IF

//* RECONCILIATION IS TO -ALWAYS- BE A FULL RECONCILIATION.

//*

//* CHANGE ?HLQ? TO REFLECT THE VSAM FILE CREATED BY THE

//* ITIMVSAM JOBSTREAM.

//*

//* IF ITIMGSCP PROGRAM IS INCLUDED, THEN SPECIFY THE NAME OF

//* THE VSAM FILE PRODUCED BY THE ITIMGSCP, IN THE PRIOR STEP.

//*

//* IF THE ITIMGSCP PROGRAM IS EXCLUDED, THEN YOU MAY OMIT THE

//* GROUP DD STATEMENT FROM THIS STEP.

//*

//* IT IS RECOMMENDED THAT FOLLOWING A RECONCILIATION THAT UTILIZES

//* THE VSAM FILE, THAT A "LISTCAT ENTRY(XXXX) ALL" BE EXECUTED, TO

//* INSPECT THE NUMBER OF EXTENTS THE FILE HAS USED, AND RE-ALLOCATE

//* THE FILE TO REFLECT THE RESULTING AMOUNT OF SPACE IT HAS USED.

//*

//* THE FIRST TIME THIS JOB IS RUN, THE "TPDELETE" WILL FAIL, AS

//* THE TRANSACTION DOES NOT EXIST. THIS IS NORMAL.

//*

//******************************************************************

//TPDELETE EXEC PGM=ATBSDFMU,REGION=0K




//SYSIN DD *

TPDELETE

TPNAME(?APPCRECO?)

SYSTEM

//TPADD EXEC PGM=ATBSDFMU,REGION=0K




//SYSIN DD DATA,DLM=XX

TPADD

TPNAME(?APPCRECO?)

SYSTEM

ACTIVE(YES)

TPSCHED_DELIMITER(##)

TAILOR_SYSOUT(NO)

TAILOR_ACCOUNT(NO)

KEEP_MESSAGE_LOG(NEVER)

CLASS(A)

TPSCHED_TYPE(STANDARD)

JCL_DELIMITER(END_OF_JCL)

//?APPCRECO? JOB

//JOBLIB DD DISP=SHR,DSN=?ITIMLOADLIB?


//*

//IRRDBU00 EXEC PGM=IRRDBU00,PARM=’NOLOCKINPUT’,REGION=0K,COND=(0,NE)


//SYSUDUMP DD SYSOUT=*

//INDD1 DD DISP=SHR,DSN=?RACFDB1?

//*INDD2 DD DISP=SHR,DSN=?RACFDB2?

//*INDD3 DD DISP=SHR,DSN=?RACFDB3?

//OUTDD DD DISP=(,PASS,DELETE),LRECL=4096,RECFM=VB,

// SPACE=(CYL,(200,30),RLSE),

// UNIT=SYSALLDA

//*

//ITIMRECO EXEC PGM=ITIMRECO,REGION=0K,COND=(0,NE)



//SYSOUT DD DUMMY

//RACFIN DD DSN=*.IRRDBU00.OUTDD,DISP=(OLD,DELETE)

//RACF01XX DD DISP=(,PASS,DELETE),

// UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)

//RACF02XX DD DISP=(,PASS,DELETE),

// UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)

//*

//TEMP0205 DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)

//TEMP1205 DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)

//*

//TEMP02XX DD UNIT=SYSALLDA,SPACE=(CYL,(200,30),RLSE)

//*

//SORTIN01 DD DSN=*.TEMP02XX,VOL=REF=*.TEMP02XX,UNIT=AFF=TEMP02XX,

// DISP=(OLD,PASS)

//SORTIN02 DD DSN=*.TEMP0205,VOL=REF=*.TEMP0205,UNIT=AFF=TEMP0205,

// DISP=(OLD,PASS)

//*

//ITIMGSCP EXEC PGM=ITIMGSCP,REGION=0K,COND=(0,NE),

// PARM=’DD:SYSPRINT DD:INPUT DD:OUTPUT’



//INPUT DD DISP=(OLD,PASS),DSN=*.ITIMRECO.RACF01XX

//OUTPUT DD DISP=OLD,AMP=’BUFNI=10,BUFND=10’,DSN=?HLQ?.GROUPS

//*

//ITIMREC2 EXEC PGM=ITIMREC2,REGION=0K,COND=(0,NE)



//GROUP DD DISP=OLD,AMP=’BUFNI=10,BUFND=10’,DSN=?HLQ?.GROUPS

//RACF01XX DD DISP=(OLD,DELETE),DSN=*.ITIMRECO.RACF01XX

//RACF02XX DD DISP=(OLD,DELETE),DSN=*.ITIMRECO.RACF02XX

//*

END_OF_JCL

##

XX

Modify and submit the ITIMVSAM job

If partial, or scoped reconciliation is to be utilized, edit the ITIMVSAM job stream

in the ITIM.CNTL data set. Change the name of the VSAM file to reflect the name

chosen in the APPCRECO job stream. The size of this VSAM file should be

checked, following a reconciliation, to insure proper sizing of the VSAM data set.

This VSAM data set contains one record per group in the RACF database. The

records are variable length, and their length depends upon the level of depth

within the RACF group tree structure. Using the default maximum VSAM record

size of 512 will allow for a RACF group tree depth of 29 groups. The maximum

record length depends upon the maximum depth of the RACF group tree. The

default maximum record length of 512 will allow for a RACF database of group

tree depth of 29.

The specific calculation is as follows:

33 + ( 16 * "N" )


Where ’n’ is the maximum depth of the RACF group tree. You should set average

record length equal to the max record length chosen, which will lessen ci/ca split

activity. Maximum record length may be 32,767, where the maximum depth of the

RACF group tree is 2044. Utilize the smallest reasonable record size that is

representative of your installation’s RACF group tree structure.

This job may be run at any time, as long as a reconciliation process is not

executing. The VSAM file does not require initialization. The content is not

relevant beyond the life of execution of the reconciliation process, and therefore, is

not required to be backed up.

Submit the job.

//ITIMVSAM JOB ACCT,ITIMAGENT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID

//******************************************************************


//*

//*SOURCE FILE NAME = APPCRECO

//*


//*



//******************************************************************

//*

//* THIS JOB STREAM CREATES THE OPTIONAL VSAM FILE UTILIZED BY THE

//* ITIMRECO TRANSACTION. (THE APPCRECO JOB INSERTS THE ITIMRECO

//* TRANSACTION INTO APPC/MVS.)

//*

//* CHANGE ?HLQ? TO A HIGH LEVEL QUALIFIER OF YOUR CHOOSING.

//*

//* WHETHER THIS FILE WILL RESIDE UPON AN SMS MANAGED VOLUME WILL

//* DEPEND UPON YOUR INSTALLATION’S SMS STANDARDS. YOU MAY HAVE TO

//* SET A PROPER "VOLUME(XXXXXX)" PARAMETER, AND/OR A PROPER

//* "STORCLAS(YYYYYYYY)" PARAMETER.

//*

//* THIS FILE’S CONTENTS ARE BOTH CREATED AND USED WITHIN THE

//* RECONCILIATION PROCESS. ITS CONTENTS ARE NOT NEEDED EITHER PRIOR

//* TO, NOR FOLLOWING A RECONCILIATION. IT DOES NOT NEED TO BE

//* BACKED UP, NOR RESTORED. IT MAY BE RE-CREATED AT ANY TIME. IN

//* EFFECT, IT ITS USE IS TEMPORARY ONLY WITHIN THE RECONCILIATION

//* PROCESS.

//*

//* THIS JOB STREAM IS REQUIRED, ONLY IF THE ITIMGSCP AND ITIMREC2

//* PROGRAMS REQUIRE IT FOR A SCOPED RECONCILIATION PROCESS.

//*

//* PUT ANOTHER WAY, IF ONLY FULL RECONCILIATIONS ARE TO BE PERFORMED,

//* THEN THIS FILE, AND REFERENCES TO IT IN THE RECONCILIATION

//* TRANSACTION, ARE NOT REQUIRED.

//*

//* THIS FILE IS NOT SHARED AT ANY TIME WITH OTHER APPLICATIONS, SO

//* SHAREOPTIONS (1,3) IS APPROPRIATE.

//*

//* THIS FILE MUST HAVE THE "REUSE" ATTRIBUTE, AS IT IS REINITIALIZED

//* EVERYTIME THE ITIMGSCP PROGRAM IS EXECUTED.

//*

//* THERE IS NO NEED TO INITIALIZE THIS VSAM CLUSTER.

//*

//* IT IS RECOMMENDED THAT FOLLOWING A REPRESENTATIVE SIZE

//* RECONCILIATION PROCESS THAT UTILIZES THE VSAM FILE, THAT A

//* "LISTCAT ENTRY(DSN) ALL" BE EXECUTED, TO INSPECT THE NUMBER OF

//* EXTENTS THE FILE HAS USED, AND RE-ALLOCATE THE FILE TO REFLECT

//* THE RESULTING AMOUNT OF SPACE IT HAS USED. INSPECT THE

//* "HIGH-USED-RBA", THE NUMBER OF EXTENTS, NUMBER OF CONTROL AREA

//* AND CONTROL INTERVAL SPLITS.

//*

//* THE MAXIMUM RECORD LENGTH DEPENDS UPON THE MAXIUMU DEPTH OF THE

//* RACF GROUP TREE. THE DEFAULT MAXIUMUM RECORD LENGTH OF 512

//* WILL ALLOW FOR A RACF DATABASE OF GROUP TREE DEPTH OF 29.


//*

//* THE SPECIFIC CALCULATION IS AS FOLLOWS:

//* 33 + ( 16 * "N" )

//* WHERE "N" IS THE MAXIMUM DEPTH OF THE RACF GROUP TREE

//*

//* IT IS RECOMMENDED TO SET AVERAGE RECORD LENGTH EQUAL

//* TO MAX RECORD LENGTH CHOSEN, AS THIS WILL LESSEN CI/CA SPLIT

//* ACTIVITY.

//*

//* MAXIMUM RECORD LENGTH MAY BE 32767, WHERE THE MAXIMUM DEPTH

//* OF THE RACF GROUP TREE IS 2044. IT IS RECOMMENDED YOU UTILIZE

//* THE SMALLEST REASONABLE RECORD SIZE THAT IS REPRESENTATIVE OF

//* YOUR INSTALLATION’S RACF GROUP TREE STRUCTURE.

//*

//******************************************************************

//DEFINE EXEC PGM=IDCAMS,REGION=0K//SYSPRINT DD SYSOUT=*

//SYSIN DD *

DELETE ?HLQ?.GROUPS CLUSTER

SET MAXCC = 0

SET LASTCC = 0

DEFINE CLUSTER(NAME(?HLQ?.GROUPS) -

INDEXED -

KEYS(12 0) -

VOLUME(XXXXXX) -

STORCLAS(YYYYYYYY) -

RECORDSIZE(512 512) -

FREESPACE(30 10) -

SHAREOPTIONS(1 3) -

CYLINDERS(25 5) -

NOIMBED -

NOREPLICATE -

REUSE -

SPEED) -

DATA(CONTROLINTERVALSIZE(4096)) -

INDEX(CONTROLINTERVALSIZE(4096))

Create started task

The member ITIAGNT is sample JCL supplied in the ITIM.CNTL data set. It is

highly recommended the member name of the started task JCL in the procedure

library be seven (7) characters or less, as it will facilitate a less complex method of

shutting down the adapter. It is also recommended the name of the started task

relate to the name of the adapter instance to which it relates.

In the ’PARM=’ component of the EXEC JCL statement is specified the full name of

the UNIX System Services shell script to start the adapter. This script name is

generated from the UNIX System Services configuration step. You must insert this

fully qualified script name into this JCL, once the USS component has been

configured.


//*ITIAGNT JOB ACCT,ITIM,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID

//******************************************************************


//*

//*SOURCE FILE NAME = ITIAGNT

//*


//*



//******************************************************************

//RACFAGNT EXEC PGM=BPXBATCH,REGION=0K,

// PARM=’SH /u/itim/bin/racfagent.sh’

//STDOUT DD PATHOPTS=(OWRONLY,OCREAT,OTRUNC),

// PATH=’/dev/null’,

// PATHMODE=SIRWXU

//STDERR DD PATHOPTS=(OWRONLY,OCREAT,OTRUNC),

// PATH=’/dev/null’,

// PATHMODE=SIRWXU

Configure RACF access

Determine your needs and configure how the adapter will access RACF

information.

RACF user ID

The adapter must run under a valid RACF user ID, with an OMVS segment, and a

valid UID. This user’s default group must have an OMVS segment with a valid

GID. The adapter must be able to acquire sufficient storage for operation, using the

OMVS segment ASSIZEMAX parameter.

Unless surrogate user ID’s are being used, the adapter must at least be connected

GROUP SPECIAL over a group of users that will be managed. If the adapter has

GROUP SPECIAL, it will require CLASS AUTHORITY of USER to be able to create

and remove user ID’s from the system (CLAUTH(USER)). This user ID should be

defined as RACF ’PROTECTED’. This is accomplished with the NOPASSWORD

operand on the ADDUSER (or ALTUSER) command.

In the following commands, the use of SYS1 as owner and DFLTGRP may be

changed to a different group of your choosing. If the TIM adapter is to manage all

accounts on this RACF database, then the following definition would define this

user:

ADDUSER ITIAGNT OWNER(SYS1) DFLTGRP(SYS1) SPECIAL AUDITOR NOPASSWORD

ALTUSER ITIAGNT OMVS(UID(uu) PROG(’/bin/sh’) HOME(’/u/itim’) ASSIZEMAX(2147483647))

If the started task JCL is called ITIAGNT, then the following STARTED class profile

should be defined:

RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) GROUP(SYS1) TRACE(YES))

SETROPTS RACLIST(STARTED) REFRESH

The ″TRACE(YES)″ operand indicates to RACF that there will be a message

displayed upon the console, indicating that this STARTED class profile was utilized

in starting this adapter.

In the following example, group xxxx indicates the group which the ITIM adapter

will have RACF scope-of-authority over. To define the ITIM adapter as a GROUP

SPECIAL user, the following is an example of making this defintion:


ADDUSER ITIAGNT DFLTGRP(xxxx) OWNER(xxxx) CLAUTH(USER) NOPASSWORD

CONNECT ITIAGNT GROUP(xxxx) SPECIAL AUDITOR

RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) GROUP(xxxx) TRACE(YES))


Additionally, if the GROUP SPECIAL attribute is utilized, then the adapter may

require the ability to manage non-RACF segment information. The adapter, or

surrogate, user ID(s), must have access to the appropriate FIELD class profile(s) to

manage these segments.

If the adapter RACF user ID is to be allowed to manage all non-RACF segments,

then you may define a FIELD class profile as follows:

RDEFINE FIELD USER.*.** UACC(NONE)

PE USER.*.** AC(ALTER) ID(ITIAGNT) CLASS(FIELD)

SETROPTS RACLIST(FIELD) REFRESH

If the adapter user ID has SYSTEM SPECIAL, it will be assumed the adapter will

be managing the entire RACF database. If this is the case, there is no issue with the

FIELD class profiles, or CLAUTH(USER).

You may have to create a RACF STARTED class profile, allowing the adapter

started task to run under this specific user id. An example of this definition is as

follows:

RDEFINE STARTED ITIAGNT.* STDATA(USER(ITIAGNT) TRACE(YES))


User ID propagation

The adapter running in UNIX System Services must have the ability to propagate

the RACF user ID it is running as, to the APPC/MVS environment. This is

accomplished through the definition of one or more profiles in the RACF APPCLU

general resource class.

There are two ways this may be configured:

Use of a single APPC/MVS base logical unit:

By default, the APPC/MVS baselu will be utilized by the RACF adapter,

both for the originating and destination logical units.

If this method is utilized, only one RACF APPCLU profile needs to be

defined.

The form of the RACF command to define this profile could take two

forms.

1. If the APPC/MVS LUADD statement takes the default, or has specified

NONQN, then this command will take the following form:

RDEFINE APPCLU netid.baselu.baselu SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

2. If the APPC/MVS LUADD statement has specified NQN, then this

command will take the following form:

RDEFINE APPCLU netid.baselu.netid.baselu SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

In the above examples, netid is the VTAM NETID (Network ID) selected

for use for VTAM in your environment. The baselu specifies the VTAM

logical unit name for the BASELU defined to APPC/MVS. The xxxxxxxx in

the SESSKEY field is a session key, or password, utilized for security when

the APPC/MVS sessions are initiated.


Once this profile has been defined, an MVS console command must be

issued to VTAM to inform VTAM of this profile being defined or updated:

F VTAM,PROFILES,ID=baselu

For example, if your installation’s VTAM NETID is set to MYNET and

your APPC/MVS BASELU is configured as MVSLU01, and NONQN has

been specified or defaulted, the RACF APPCLU profile could be defined as

follows:

RDEFINE APPCLU MYNET.MVSLU01.MVSLU01 SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

Using the above example values, where the LUADD statement has

specified NQN, the RACF APPCLU profile could be defined as follows:

RDEFINE APPCLU MYNET.MVSLU01.MYNET.MVSLU01 SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

Use of a two APPC/MVS logical units:

Your installation may wish to use two separate logical units, not utilizing

the APPC/MVS BASELU definition.

If this method is utilized, two RACF APPCLU profiles need to be defined.

The form of the RACF command to define these profiles could take two

forms:

1. If the APPC/MVS LUADD statements have defaulted or specified

NONQN, then the commands will take the following form (this

example implies that NONQN is used for BOTH logical units):

RDEFINE APPCLU netid.origin.dest SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

RDEFINE APPCLU netid.dest.origin SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

2. If the APPC/MVS LUADD statements has specified NQN, then these

commands will take the following form (This example implies that

NQN is specified for both logical units):

RDEFINE APPCLU netid.origin.netid.dest SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

RDEFINE APPCLU netid.dest.netid.origin SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

Once these profiles have been defined, twoMVS console commands must

be issued to VTAM to inform VTAM of this profile being defined or

updated:

F VTAM,PROFILES,ID=origin

F VTAM,PROFILES,ID=dest

In the above examples, netid is the VTAM Network ID (NETID) selected

for use for VTAM in your environment. The origin and dest specify the

VTAM logical unit names utilized as the originating and destination logical

units defined to APPC/MVS. The xxxxxxxx in the SESSKEY field is a

session key, or password, utilized for security when the APPC/MVS

sessions are initiated.

For example, if your installation’s VTAM NETID is set to MYNET, your

APPC/MVS origin logical unit is named ITIMORIG, dest logical unit is

named ITIMDEST, and NONQN has been specified or defaulted, the

RACF APPCLU profiles will be defined as follows:


RDEFINE APPCLU MYNET.ITIMORIG.ITIMDEST SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

RDEFINE APPCLU MYNET.ITIMDEST.ITIMORIG SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

Using the above example values, where the LUADD statements have

specified NQN, the RACF APPCLU profiles would be defined as follows:

RDEFINE APPCLU MYNET.ITIMORIG.MYNET.ITIMDEST SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

RDEFINE APPCLU MYNET.ITIMDEST.MYNET.ITIMORIG SESSION(CONVSEC(ALREADYV)

SESSKEY(xxxxxxxx))

Surrogate user ID

If a single adapter will be performing requests for multiple Tivoli Identity Manager

service instances on the server, then surrogate user ID’s must be defined to RACF,

and filled in on the Tivoli Identity Manager service forms.

For the adapter to perform requests using these surrogate user ID’s, you must

define one or more RACF SURROGAT class profiles.

If the adapter RACF user ID is ITIAGNT, and the surrogate RACF user ID is

UNIT1, then the following commands would define the profile:

RDEFINE SURROGAT ATBALLC.UNIT1 UACC(NONE)

PERMIT ATBALLC.UNIT1 CLASS(SURROGAT) AC(READ) ID(ITIAGNT)

SETROPTS RACLIST(SURROGAT) REFRESH

In the above example, the RACF user ID UNIT1 will be the user ID utilized on the

Tivoli Identity Manager Server, in the service definition form, on the RACF User

with Scope-of-Authority over Business Unit field.

When surrogate user ID’s are utilized, the tasks of altering and fetching RACF data

is accomplished under the authority of the surrogate RACF user ID, NOT the

RACF user ID the adapter proper is running as. The SURROGAT class profile must

be permitted to be used by the RACF user ID for the adapter proper with read

access.

Authorization to set and reset passwords

When the adapter RACF user ID, or the surrogate RACF user ID(s) do not have

SYSTEM SPECIAL, then they must have the ability to set passwords over those

users it manages. This is accomplished through the FACILITY class profile named

IRR.PASSWORD.RESET.

The default for the PASSEXPIRE option is TRUE, which means all passwords set

from the Tivoli Identity Manager Server will be EXPIRED passwords, requiring the

user to change their password upon first use. In this instance, the adapter (or

surrogates) will only need READ access to the IRR.PASSWORD.RESET profile:

RDEFINE FACILITY IRR.PASSWORD.RESET UACC(NONE)

PERMIT IRR.PASSWORD.RESET CLASS(FACILITY) AC(READ) ID(ITIAGNT)

SETROPTS RACLIST(FACILITY) REFRESH

If the adapter option PASSEXPIRE is set to FALSE, the Tivoli Identity Manager

adapter will only be setting non-expired passwords. In this instance, the adapter

(or surrogates) may require UPDATE access to the IRR.PASSWORD.RESET profile,

if these users do not have RACF SYSTEM SPECIAL.


RDEFINE FACILITY IRR.PASSWORD.RESET UACC(NONE)

PERMIT IRR.PASSWORD.RESET AC(UPDATE) ID(ITIAGNT)


If surrogate RACF user ID’s are being utilized, the user ID specified in the above

PERMIT command will reflect the surrogate user ID, not the adapter RACF user

ID that starts the adapter.

Refer to the z/OS 1.4 RACF Security Administrator’s guide for more information.

AUTOUID support

If you are running on z/OS 1.4 or above, and wish to allow the Tivoli Identity

Manager Server to take advantage of AUTOUID support for OMVS segments, then

you must define the following profile:

RDEFINE FACILITY BPX.NEXT.USER APPLDATA(’nn/mm’) UACC(NONE)


Where ’nn’ is a starting OMVS UID to be assigned, and ’mm’ is the next OMVS

GID to be assigned. (The GID is shown here for completeness).


Shared UID support

If you wish the Tivoli Identity Manager Server to be able to provision a shared

OMVS UID number, the adapter, or surrogate user ID’s must have permission to

do so.

If your installation is running z/OS 1.4 or above, and the SHARED.IDS profile is

defined in the UNIXPRIV class, definition of duplicate UID’s for multiple users is

prevented. If you wish the Tivoli Identity Manager to define UID’s to multiple

users, you must permit it to do so, by adding the RACF user ID (representing the

adapter) to have read access to the resource profile:

PE SHARED.IDS CLASS(UNIXPRIV) AC(READ) ID(ITIAGNT)

SETROPTS CLASS(UNIXPRIV) REFRESH

Where the RACF user ID set in the permit command is either the adapter ID or the

surrogate ID that will effectively be utilizing executing the RACF command.

If surrogate RACF user ID’s are being utilized, the user ID specified in the above

PERMIT command will reflect the surrogate user ID, not the adapter RACF user

ID that starts the adapter.


Step 6: Configure communication

Configure the Tivoli Identity Manager Server to communicate with the RACF

adapter. The following steps must be performed on the host where the Tivoli

Identity Manager Server resides.

Importing the adapter profile into the Tivoli Identity Manager

Server

Before you can add an adapter as a service to the Tivoli Identity Manager Server,

the server must have an adapter profile to recognize the adapter as a service. The

files that are packaged with the RACF Adapter include the adapter JAR file,


racf2Profile.jar. Using the Import feature of the Tivoli Identity Manager Server, you

can import the adapter profile into the server as a service profile.

The racf2Profile.jar file includes all of the files that are needed to define the

adapter schema, account form, service form, and profile properties. The

racf2Profile.jar file will be referenced in this document to make any changes to the

schema or the profile. You will be required to extract the files from the JAR file,

make changes to the necessary files, and repackage the JAR file with the updated

files.

An adapter profile defines the types of resources that the Tivoli Identity Manager

Server can manage. You must import the adapter profile into the Tivoli Identity

Manager Server before using the RACF Adapter. The profile is used to create a

RACF Adapter service on the Tivoli Identity Manager Server and to communicate

with the adapter.

Before you begin to import the adapter profile, verify that the following conditions

are met:

v The Tivoli Identity Manager Server must be installed and running.

v You must have root or Administrator authority on the Tivoli Identity Manager

Server.

In order to import the adapter profile, complete the following steps:

1. Log into the Tivoli Identity Manager Server using an account that has the

authority to perform administrative tasks.

2. On the Main Menu Navigation Bar, select the Configuration tab.

3. On the Configuration window, select Import/Export → Import tabs.

4. On the Import window, in the File to Upload field, type the location of the

racf2Profile.jar file, or click Browse to locate the file.

5. Click the Import data into Identity Manager link to import the adapter profile

into the Tivoli Identity Manager Server.

v If the adapter profile import completes successfully, the following message is

displayed:

Profile installation complete.

v If the adapter profile import fails, the following message is displayed:

Profile installation failed.

When you import the adapter profile, if you receive an error related to the

schema, the trace.log file will contain information about that error. The

trace.log file location is specified by the handler.file.fileDir property that

is defined in the Tivoli Identity Manager enRoleLogging.properties file,

which is in the Tivoli Identity Manager \data directory.

Creating a RACF service

After the adapter profile is imported into the Tivoli Identity Manager Server, you

must create a provisioning service to allow Tivoli Identity Manager to

communicate with the adapter.

In order to create a provisioning service, complete the following steps:

1. Log into the Tivoli Identity Manager Server using an account that has the

authority to perform administrative tasks.

2. On the Main Menu Navigation Bar, click the Provisioning tab.

3. On the Provisioning window, click the Manage Services tab.


4. On the Manage Services window, click Add.

5. From the list of service types, select RACF Profile, and then click Continue.

The RACF Adapter service form is displayed. The service form contains the

following fields:

Service Name

Specify a name that defines this RACF service on the Tivoli Identity

Manager Server. Service Name is a required field.

Service Description

Specify a description that will identify this service for your

environment. Service Description is not a required field.

URL Specify the location and port number of the RACF Adapter. The port

number is defined in the protocol configuration using the agentCfg

program. For additional information about protocol configuration

settings, see “Changing protocol configuration settings” on page 41.

URL is a required field.

If https is specified as part of the URL, the adapter must be configured

to use SSL authentication. If the adapter is not configured to use SSL

authentication, specify http for the URL. For additional information

about configuring the adapter to use SSL authentication, see Chapter 5,

“Configuring SSL authentication for the RACF adapter,” on page 71.

User Id

Specify the name that has been defined in the adapter registry on the

z/OS platform. The default value is agent. User Id is a required field.

Password

Specify the password for the user ID. The default value is agent.

Password is a required field.

RACF ID under which requests will be processed

Specify a RACF user ID, other than the one that is used by the adapter.

This user ID should have group special authority over a subset of users

within the RACF database. RACF ID is not required.

Owner

Specify the service owner, if any. Owner is an optional field.

Service Prerequisite

Specify an existing Tivoli Identity Manager service that is a prerequisite

for the RACF service. Service Prerequisite is an optional field.6. To verify the connection, press Test.

7. To create the service, press Submit.

Step 7: Starting and stopping the adapter

It is preferable to start the RACF Adapter as a started task, where the started task

JCL has been customized and installed into a system procedure library.

To start, issue the MVS console start command:

START ITIAGNT

Where ITIAGNT is the name of the JCL procedure representing the adapter.


The adapter may also be started as a batch job stream, or may be started from

UNIX System Services, by initiating the UNIX System Services script to start the

adapter.

When the ITIAGNT task is running, it will listen on two IP ports. One port is for

adapter communication between the ITIM server and this adapter and the other

port is utilized for the agentCfg utility.

If the UNIX System Services environment is running with _BPX_SHAREAS=YES,

run the MVS stop command to stop the adapter, for example:

STOP ITIAGNT

or

P ITIAGNT

If the adapter is initiated as a started task, you may stop the RACF Adapter by

issuing an MVS CANCEL command, as follows:

CANCEL ITIAGNT



Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity

Manager

Use the adapter configuration program, agentCfg, to view or modify the RACF

Adapter parameters. All changes that you make to parameters with this tool take

effect immediately.

Starting the adapter configuration tool

In order to start the adapter configuration tool, agentCfg, for RACF Adapter

parameters, complete these step:

Note: The agentCfg program requires DLLs from the ./lib directory. As such, the

./lib directory must be in your LIBPATH environment variable, prior to

execution of agentCfg.

1. Log into the RACF Adapter system. Logon to the MVS system through TSO.

2. Enter the Unix System Services shell environment, with the OMVS command.

You can optionally directly enter the Unix System Services environment

through a telnet session.

3. In the command prompt window, change to the /bin directory for the adapter.

For example, type the following command, if the RACF Adapter directory is in

the default location: (Assume a user called ″itim″ has /home/itim as the home

directory.)

# cd home/itim/RACFAgent/bin

4. Type the following command:

agentCfg -agent RACFAgent

The adapter name is the name chosen when configuring your adapter. You can

find the adapter names active by executing agentCfg as follows:

agentCfg -list

You can also use agentCfg to view or change configuration settings from a

remote computer. See the table in “Accessing help and additional options” on

page 68 for procedures on using additional arguments.

5. At the Enter configuration key for Agent ’RACFAgent’: prompt, type the

configuration key for the RACF Adapter.

The default configuration key is agent. You must change the configuration key

once installation completes, to prevent unauthorized access to the configuration

of the adapter. See “Changing protocol configuration settings” on page 41 for

procedures to change the configuration key.

The Main Configuration Menu is displayed.


RACFAgent 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:

From the Main Menu, you can configure the protocol, view statistics, and modify

settings, including configuration, registry, and advanced settings.

Table 5. Options for the main configuration menu

Option Configuration task For more information

A Viewing configuration settings See page 40.

B Changing protocol configuration

settings

See page 41.

C Configuring event notification See page 44.

D Changing the configuration key See page 61.

E Changing activity logging settings See page 61.

F Changing registry settings See page 63.

G Changing advanced settings See page 64.

H Viewing statistics See page 66.

I Changing code page settings See page 66.

Viewing configuration settings

The following procedure describes how to view the RACF Adapter configuration

settings.

1. At the Agent Main Configuration Menu, type A. The configuration settings for

the RACF Adapter are displayed. The following screen is an example of the

RACF Adapter configuration settings.


Configuration Settings

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

Name : RACFAgent

Version : 4.6

ADK Version : 4.36

ERM Version : 4.36

enRole Version : 4.0

License : NONE

Asynchronous 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 : DAML

Configured Protocols : DAML

Logging Enabled : TRUE

Logging Directory : /home/itim/RACFAgent/log

Log File Name : RACFAgent.log

Max. log files : 3

Max.log file size (Mbytes) : 1

Debug Logging Enabled : TRUE

Detail Logging Enabled : FALSE

Thread Logging Enabled : FALSE

Press any key to continue

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

Changing protocol configuration settings

The RACF Adapter uses the DAML protocol to communicate with the Tivoli

Identity Manager Server. By default, when the adapter is installed, the DAML

protocol is configured to be used in nonsecure mode. In order to configure a secure

environment, you must configure the DAML protocol to use SSL and install a

certificate. Refer to “Installing the certificate” on page 80 for more information

about installing certificates.

In previous versions of this adapter, you could add and remove protocols.

However, in the latest version of this adapter, the DAML protocol is the only

supported protocol that you can use. Therefore, you will not need to add or

remove a protocol.

In order to configure the DAML protocol for the RACF Adapter, complete the

following steps:

1. At the Agent Main Configuration Menu, type B. The DAML protocol is

configured and available by default for the RACF Adapter.

Agent Protocol Configuration Menu

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

Available Protocols: DAML

Configured Protocols: DAML

A. Add Protocol.

B. Remove Protocol.

C. Configure Protocol.

X. Done

Select menu option

2. At the Agent Protocol Configuration Menu, type C. The Configure Protocol

Menu is displayed.

3. At the Configure Protocol Menu, type C. The Protocol Properties Menu for the

configured protocol is displayed with protocol properties. The properties on

your menu might be different from the ones shown in the examples.

Chapter 4. Configuring the RACF adapter in IBM Tivoli Identity Manager 41

The following screen is an example of the DAML protocol properties:

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. VALIDATE_CLIENT_CE FALSE ;Require client certificate.

I. REQUIRE_CERT_REG FALSE ;Require registered certificate.

X. Done

Select menu option:

4. Type the letter of the menu option for the protocol property that you want to

configure.

See Table 6 below for additional information about the properties that you can

configure for the DAML protocol.

Table 6. Options for the DAML protocol menu

Option Configuration task

A The following prompt is displayed:

Modify Property ’USERNAME’:

Type a user ID, for example, admin.

This value is the user ID that the Tivoli Identity Manager Server uses to

connect to the adapter.

B The following prompt is displayed:

Modify Property ’PASSWORD’:

Type a password, for example, admin.

This value is the password for the user ID that the Tivoli Identity

Manager Server uses to connect to the adapter.

C The following prompt is displayed:

Modify Property ’MAX_CONNECTIONS’:

Enter the maximum number of concurrent open connections that the

adapter supports.

The default number is 100.

D The following prompt is displayed:

Modify Property ’PORTNUMBER’:

Type a different port number.

This value is the port number that the Tivoli Identity Manager Server

uses to connect to the adapter. The default port number is 45580.


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


E The following prompt is displayed:

Modify Property ’USE_SSL’:

Enter TRUE or FALSE to specify whether a secure SSL connection will

be used to connect to or from the adapter.

The default value is FALSE.

You must install a certificate when USE_SSL is set to TRUE. For more

information on certificate installation, see “Installing the certificate” on

page 80.

F The following prompt is displayed:

Modify Property ’SRV_NODENAME’:

Type a server name or an IP address, for example, 9.38.215.20.

This value is the DNS name or IP address of the Tivoli Identity Manager

Server that is used for event notification and asynchronous request

processing.

Note: If your platform supports Internet Protocol version 6 (IPv6)

connections, you can specify an IPv6 server.

G The following prompt is displayed:

Modify Property ’SRV_PORTNUMBER’:

Type a different port number to access the Tivoli Identity Manager

Server.

This value is the port number that the adapter uses to connect to the

Tivoli Identity Manager Server. The default port number is 9443.

H The following prompt is displayed:

Modify Property ’VALIDATE_CLIENT_CE’:

Type TRUE to require the Tivoli Identity Manager Server to send a

certificate when it communicates with the adapter.

Type FALSE to allow the Tivoli Identity Manager Server to communicate

with the adapter without a certificate. The default value is FALSE.

Notes:

1. If you set this option to TRUE, you must configure options D

through H.

2. The property name is actually VALIDATE_CLIENT_CERT. It is

truncated by agentCfg to fit onto the screen.

3. You must use CertTool to install the appropriate CA certificates and

optionally register the Tivoli Identity Manager Server certificate. For

more information on using CertTool, see “Managing SSL certificates

using CertTool” on page 77.


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


I The following prompt is displayed:

Modify Property ’REQUIRE_CERT_REG’:

This value only applies when option H is set to TRUE.

Type TRUE to require the client certificate from the Tivoli Identity

Manager Server to be registered with the adapter before it will accept an

SSL connection.

Type FALSE to require the client certificate only be verified against the

list of CA certificates. The default value is FALSE.

For more information on certificates, see Chapter 5, “Configuring SSL

authentication for the RACF adapter,” on page 71.

5. At the prompt, change the value, and press Enter.

The Protocol Properties Menu is displayed with your new settings.

If you do not want to change the value, just press Enter to return to the

Protocol Properties Menu.

6. Repeat steps 4 and 5 to configure as many protocol properties as you need to.

7. At the Protocol Properties Menu, type X to exit the menu.

Configuring event notification

Event notification is a feature of the RACF Adapter that updates the Tivoli Identity

Manager Server at set intervals. Event notification detects changes that are made

on the managed resource and updates the Tivoli Identity Manager Server with the

changes. You can enable event notification if you want to have updated

information from the managed resource sent back to the Tivoli Identity Manager

Server between full reconciliations. Event notification is not intended to replace

reconciliations on the Tivoli Identity Manager Server.

When event notification is enabled, a database of the reconciliation data is kept on

the machine where the adapter is installed. The database is updated with the

changes that are requested by the Tivoli Identity Manager Server and will stay in

sync with the server. You can specify an interval for the event notification process

to compare the database to data that currently exists on the managed resource.

When the interval has elapsed, any differences between the managed resource and

the database are forwarded to the Tivoli Identity Manager Server and updated in

the local snapshot database.

There are several basic steps to enabling event notification. These steps assume that

the adapter has been deployed on the managed host and is communicating

successfully with the Tivoli Identity Manager server.

Required information

Implementation of event notification requires the following information:

v If Secure Sockets Layer (SSL) is utilized for communications between the Tivoli

Identity Manager server and the adapter on the managed resource, Tivoli

Identity Manager’s digital certificate must be obtained to be installed into the

adapter’s registry.


v The IP address of the hosting platform of Tivoli Identity Manager must be

known.

v The IP port of the hosting platform of Tivoli Identity Manager must be known.

You will require one of the following port numbers:

– The SSL port, if SSL communications is utilized, or

– The non-SSL port, if SSL is not utilized.

These ports are actually the port numbers of the Web application server on the

Tivoli Identity Manager server. When Tivoli Identity Manager is utilizing

WebSphere, the default SSL port is 9443, and the non-SSL port is 9080.

v The pseudo Distinguished Name (DN) of the Tivoli Identity Manager service

defined on the Tivoli Identity Manager server must be known, and defined into

an event notification context in the adapter’s registry. The DN is NOT a typical

LDAP DN, and is unique for the use of Tivoli Identity Manager. It identifies a

specific service instance defined on the Tivoli Identity Manager server. Details on

determining this target DN are detailed below.

v Optionally, there are credentials passed to an adapter, to identify the service

instance to the managed resource adapter. Use of these attributes depends upon

the specific adapter being utilized. These credentials are additional information

that allow the adapter to connect to the managed resource, or discretely identify

different areas of the managed resource.

Example definition

This section provides an example definition for demonstration purposes. This

example uses the following variables:

v SSL will be utilized for communications.

v The IP address of the host where Tivoli Identity Manager executes is 9.38.214.54.

v The IP port of the host of the web application server’s SSL port is 9443.

v We will name the adapter context RACF.

v For the RACF adapter, there is an optional attribute that constitutes additional

credentials to the adapter. On the service form, there is a field labeled RACF ID

under which requests will be processed. In this example, the value of this field

is ADMNBU1.

v Because SSL is utilized, the adapter will be receiving a digital certificate from the

Tivoli Identity Manager server. In this case, the certificate is self signed, so the

certificate itself must be installed into the adapter registry as a Certificate

Authority (CA) certificate.

v The pseudo DN of the Tivoli Identity Manager services as a target of event

notification is:

erservicenname=z/OS RACF 4.5.1016 ENTEST, o=Acme Inc, ou=Acme,dc=my_suffix

The details below describe how this pseudo-DN is constructed.

Setting the protocol properties

Usually, SSL will be utilized. This will have already been determined while

configuring the adapter, outside of the topic of event notification. All of these

properties are defined under the DAML protocol environment.

In the following example, the Tivoli Identity Manager host IP and port addresses

will be set through the agentCfg utility.


BETA451017 4.5.1017 Agent Main Configuration Menu

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








H. Statistics.


X. Done

Select menu option:b

Agent Protocol Configuration Menu

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

Available Protocols : DAML

Configured Protocols: DAML

A. Add Protocol.

B. Remove Protocol.

C. Configure Protocol.

X. Done

Select menu option:c

Configure Protocol Menu

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

A. DAML

X. Done

Select menu option:a


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





E. USE_SSL TRUE ;Use SSL secure connection

F. SRV_NODENAME ----- ;Event Notif. Server name.




X. Done

Select menu option:f

Modify Property ’SRV_NODENAME’: 9.38.215.20


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










X. Done


Select menu option:g

Modify Property ’SRV_PORTNUMBER’: 9443


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










X. Done

Select menu option:x

Configure Protocol Menu

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

A. DAML

X. Done


Installing the CA certificate into the adapter

Tivoli Identity Manager and its adapters are typically configured to utilize SSL for

communications, where server-side authentication is employed. This means that

the adapter must identify itself to the server, when the Tivoli Identity Manager

server contacts the adapter. The adapter must have installed a private key and

corresponding digital certificate. The server must have installed a Certificate

Authority certificate that signed the adapter’s certificate.

When event notification is employed, the adapter side must contact the Tivoli

Identity Manager server. In this case, the Tivoli Identity Manager server identifies

itself to the adapter. Because of this, you must install the Certificate Authority

digital certificate (which signed the Tivoli Identity Manager server’s digital

certificate) into the adapter’s registry.

When event notification is configured and enabled, you must install the Tivoli

Identity Manager server’s CA certificate into the adapter’s environment. This is not

the certificate in the /itim46/cert directory, but the certificate of the web

application server (such as WebSphere). The CA certificate is the digital certificate,

which signed the certificate presented in the SSL handshake. If the server is using a

simple self-signed digital certificate, then the server’s certificate acts also as a CA

certificate. In this case, only the server’s digital certificate is required.

The adapter ships with the WebSphere self-signed digital certificate. If you are

utilizing a different Java application server, you must install its CA certificate

The server’s self-signed certificate, or CA signing certificate must be obtained in an

exported X.509 DER form, and transferred to the adapter host. It should be stored

into the ./data directory, for subsequent installation by utilizing the certTool utility

(provided with the adapter). Because the certificate is in DER form, binary file

transfer of the certificate to the adapter platform is necessary. A text file transfer

will not work.


There are many different ways this certificate may be obtained and transferred to

the adapter host.

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

Web server :

1. Open Internet Explorer.

2. Attempt connection to the Tivoli Identity Manager server platform, utilizing

HTTPS (HTTP over SSL). The following URL is an example:

https://9.38.215.20:9443/enrole/login

3. Press Enter, and a dialog box will be displayed, indicating security alert. This

is because the certificate presented by the site to your Web browser is not

issued by a company you have chosen to trust. Click on the View Certificate

button.

4. A dialog box shows details of the certificate presented to your browser. Select

the tab across the top titled Details.

5. Click the Copy to File button to launch the certificate export wizard. Click

Next to proceed.

6. You will now be provided with a choice of formats in which the digital

certificate of the Tivoli Identity Manager server may be exported. Select DER

encoded X.509 (.CER), then click Next.

7. Specify a directory and a file name on your local workstation to store the

certificate. Click Next.

8. A completion dialog indicates the success of the export wizard. Note of the

full path of the File Name in this display. Click OK to close the success dialog

box.

9. Click OK again to close the certificate dialog box.

10. The security alert dialog box is displayed. Click either:

v Yes to connect to the Tivoli Identity Manager server, or

v No to deny the connection.

Either choice is irrelevant, since you have now captured the certificate to your

workstation.

11. The exported certificate must now be transferred to the host where the

adapter resides. The following example shows an FTP session, transferring the

certificate to the adapter host:


C:\temp>dir *.cer

Volume in drive C is Local Disk

Volume Serial Number is 289F-D3F5

Directory of C:\temp

10/26/2004 04:37p 742 rhea.cer

1 File(s) 742 bytes

0 Dir(s) 3,924,729,856 bytes free

C:\temp>ftp 9.38.214.54

Connected 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)): agntusr

331 Send password please.

Password:

230 JOHNY is logged on. Working directory is "JOHNY.".

ftp> cd /u/itim/data

250 HFS directory /u/itim/data is the current working directory

ftp> bin

200 Representation type is Image

ftp> put rhea.cer

200 Port request OK.

125 Storing data set /u/itim/data/rhea.cer

250 Transfer completed successfully.

ftp: 742 bytes sent in 0.02Seconds 37.10Kbytes/sec.

ftp> quit

221 Quit command received. Goodbye.

C:\temp>exit

12. Now connect to the adapter host so that you can execute the certTool utility

and install the certificate you have just uploaded. Here is a sample terminal

session on the adapter host to do the installation:


/u/itim/data/data:>ls -al

total 10328

drwxrwxr-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 RACFAGENT.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/data/data:>../bin/certTool -agent racfagent

IBM Tivoli Agent DAML Protocol Certificate Tool 4.60

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

Main menu - Configuring agent: RACFAGENT

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

A. Generate private key and certificate request

B. Install certificate from file

C. Install certificate and key from PKCS12 file

D. View current installed certificate

E. List CA certificates

F. Install a CA certificate

G. Delete a CA certificate

H. List registered certificates

I. Register certificate

J. 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: RACFAGENT

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












X. Quit

Choice: x

13. The self-signed digital certificate for the Tivoli Identity Manager server is now

installed in the managed host adapter, as a CA certificate. This will allow the

event notification process to connect to the Tivoli Identity Manager server

utilizing SSL.


Adding an event notification context

Event Notification updates the Tivoli Identity Manager Server at set intervals, with

information that has changed since the last server initiated reconciliation. The

following procedure is an example of adding an event notification context.

The example menu shows all the options displayed when Event Notification is

enabled. If Event Notification is disabled, not all of the options are displayed. In

order to set Event Notification for the Tivoli Identity Manager Server, complete the

following steps:

1. At the Agent Main Configuration Menu, type C. The Event Notification Menu is

displayed.

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. Enabled

B. 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.

X. Done

Select menu option:

Note: This menu shows all the options that are displayed when Event

Notification is enabled. If Event Notification is disabled, all of the

options will not be displayed.

2. Type the letter of the menu option that you want to change.

Option A must be enabled in order for the values of the other options to take

affect.

Press Enter to return to the Agent Event Notification Menu without changing

the value.

Table 7. Options for the event notification menu


A If this option is enabled, the adapter updates the Tivoli Identity Manager

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 7. Options for the event notification menu (continued)



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 once event notification completes

before it is run again. The event notification process is resource intense,

therefore this value must not be set to run too frequently.


Enter new cache size[5]:

Type a different value to change the processing cache size.

D If this option is selected, event notification is started.

E The Event Notification Entry Types Menu is displayed. See “Setting

attributes to be reconciled” on page 58 for more information.

F The following prompt is displayed:

Enter new thread priority [1-10]:

Type a different thread value to change the event notification process

priority.

Setting the thread priority to a lower value reduces the impact that the

event notification process has on the performance of the adapter. A

lower value might also cause event notification to take longer.

G The following prompt is displayed:

Context name:

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

H A menu listing the available contexts is displayed. See “Modifying an

event notification context” on page 59 for more information.

I The Remove Context Menu is displayed. Select the context to remove.

The following prompt is then displayed:

Delete context context1? [no]:

Press Enter to exit without deleting the context, or type Yes and press

Enter to delete the context.

J The Event Notification Contexts are displayed in the following format:

Context Name : Context1

Target DN :

erservicename=context1,o=IBM,

ou=IBM,dc=com

--- Attributes for search request ---

{search attributes listed}

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

3. To add an event notification context, select option F to add a context. You will

be prompted for a context name, then returned to the Event Notification Menu:


Select menu option:F

Enter new context name: RACF

Event Notification Menu

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

* Reconciliation interval : 1 day(s)

* Next Reconciliation time : 22 hour(s) 24 min(s). 52 sec(s).

* Configured Contexts : RACF

A. Enabled

B. 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.

X. Done

Select menu option:

4. If you changed the value for options B, C, E, or F, press Enter. The other

options are automatically changed when you type the corresponding letter of

the menu option.

The Event Notification Menu is displayed with your new settings.

Configuring the target DN for event notification contexts

Once an event notification context has been added, it must be modified through

option G to add information to the context. At minimum, a target pseudo DN must

be specified. To determine how to construct this target DN, refer to “Determining

pseudo-distinguished name values” on page 55.

Select menu option: G

Modify Context: RACF

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

A. Set attributes for search

B. Target DN:

X. Done

Select menu option:b

Enter Target DN: erservicenname=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,

ou=Acme,dc=my_suffix


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


B. Target DN: erservicenname=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,

ou=Acme,dc=my_suffix

X. Done

Select menu option:


Specifying attributes for search

For some adapters, you may need to specify an attribute/value pair for one or

more contexts. These attribute/value pairs, which are defined within the context

under Set attributes for search, serve multiple purposes:

v When multiple service instances on the Tivoli Identity Manager server reference

this adapter, each service instance must allow for specification of an

attribute/value pair, so the adapter will know which service instance is

requesting work.

v This attribute will be passed to the event notification process, when the event

notification interval has occurred or is manually initiated. This will allow the

adapter to process information indicated by this attribute/value pair.

v When a server initiated reconciliation process is initiated, the adapter will be

directed to entirely replace the local database that represents this service

instance.

Below is a partial list of possible attribute/value pairs that may be specified for Set

attributes for search. Please reference current schema information for the various

adapter types for accurate information.

Table 8. Attributes for search

Service type Form label Attribute name Value

racf2profile RACF ID under which

requests will be

processed

erracfrequester A group special

RACF user ID

which manages

users within this

service.

ernt40profile Domain Server Name erntdomainservername The domain name

of the Windows NT

server being

managed. For

example:

\\mydomain

w2kprofile Base Point DN erw2kdomainname The Windows 2000

base point,

describing the

subset of the

domain to be

managed. For

example:

xxxxxxxxx

Exchange2kProfile Base Point DN erw2kdomainname The Windows 2000

base point,

describing the

subset of the

domain to be

managed. For

example:

xxxxxxxxx


Table 8. Attributes for search (continued)

Service type Form label Attribute name Value

ADProfile Base Point DN eradbasepoint The Windows 2000

base point,

describing the

subset of the

domain to be

managed. For

example:

xxxxxxxxx

Select menu option:g

Modify Context Menu

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

A. RACF

X. Done



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


B. Target DN:


Reconciliation Attributes Passed to Agent for context: RACF

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

A. Add new attribute

B. Modify attribute value

C. Remove attribute

X. Done


Attribute name : erracfrequester

Attribute value: admnbu1

Reconciliation Attributes Passed to Agent for context: RACF

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

01. erracfrequester ’admnbu1’

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



C. Remove attribute

X. Done


Determining pseudo-distinguished name values

The Target DN field holds the pseudo-distinguished name of the service that

receives event notification updates. To assist in determining the correct entries, this

name may be considered to contain the following components, in the order

A+B+C+D+E:


Note: None of the Tivoli Identity Manager defined components of the pseudo DN

should contain commas, as the comma is used to delimit between fields of

the resulting pseudo DN.

Table 9. Name values and their descriptions

Component Item Description

A erServicename The value of the erServicename attribute of the

service

B Zero or more

occurrences of ou

and/or 1.

In the event the service is not directly associated

with the organization, additional specification of ou,

and l must be specified.

The specification of these values, will be in reverse

order of their appearance within the Tivoli Identity

Manager organization chart.

C o The value of the o attribute of an organization to

which the service belongs, at the highest level.

This may be determined by examining the Tivoli

Identity Manager organization chart.

D ou This ou component is established at Tivoli Identity

Manager installation.

This is found in the Tivoli Identity Manager

configuration file named enRole.properties, on

configuration item named enrole.defaulttenant.id=

E dc The dc component was established at Tivoli Identity

Manager installation.

This is the root suffix of the LDAP environment.

This is found in the Tivoli Identity Manager

configuration file named enRole.properties, on

configuration item named enrole.ldapserver.root=

EXAMPLE ONE:

A:

The service name on the Tivoli Identity Manager server is z/OS RACF

4.5.1016 ENTEST. This name will become component A of the pseudo-DN:

erservicename=z/OS RACF 4.5.1016 ENTEST

B:

Here is an example display of the Tivoli Identity Manager organization

chart, indicating the location of the service within this organization:

Table 10. Organization chart example

+ Identity Manager Home Tivoli Identity Manager Home

+ Acme Inc Base organization o

Since this service is directly associated with the organization at the top of

the organization chart, there will be no component B required.

C:

The organization this service is associated with, shown on the Tivoli

Identity Manager organization chart is named Acme Inc. This will become

component C of the pseudo-DN:

o=Acme Inc

D:


Through examination, or prior knowledge, of the contents of the

enRole.properties definition file on the Tivoli Identity Manager server, the

value of the property named enrole.defaulttenant.id= will become

component D of the pseudo-DN. Here is an excerpt from the file:

###########################################################

## Default tenant information

###########################################################

enrole.defaulttenant.id=Acme

Thus, the D component of the pseudo-DN will be: ou=Acme

E:



value of the property named enrole.ldapserver.root= will become

component E of the pseudo-DN. Here is an excerpt from the file:

###########################################################

## LDAP server information

###########################################################

enrole.ldapserver.root=dc=my_suffix

Thus, the E component of the pseudo-DN will be:

dc=my_suffix

Putting all the components together results in the following pseudo-DN

(A+C+D+E; no component B was required):

erservicename=z/OS RACF 4.5.1016 ENTEST,o=Acme Inc,ou=Acme,dc=my_suffix

EXAMPLE TWO:

A:

The service name on the Tivoli Identity Manager server is Irvine Sales.

This name will become component A of the pseudo-DN:

erservicename=Irvine Sales

B:

Here is an example display of the Tivoli Identity Manager organization

chart, indicating the location of the service within this organization:

Table 11. Organization chart example

+ Identity Manager Home Tivoli Identity Manager Home

-Acme Inc Base organization o

- Irvine

Sales

LocationOrganizational Unit

lou

The Irvine Sales service is defined under organizational unit (ou) named

Sales, which is defined under location (l) named Irvine.

Component B of the pseudo-DN will be:

ou=Sales,l=Irvine

C:

The organization this service is associated with, shown on the Tivoli

Identity Manager organization chart is named Acme Inc. This will become

component C of the pseudo-DN:


o=Acme Inc

D:



value of the property named enrole.defaulttenant.id= will become

component D of the pseudo-DN. Here is an excerpt from the file:

###########################################################

## Default tenant information

###########################################################

enrole.defaulttenant.id=Acme

Thus, the D component of the pseudo-DN will be:

ou=Acme

E:



value of the property named enrole.ldapserver.root= will become

component E of the pseudo-DN. Here is an excerpt from the file:

###########################################################

## LDAP server information

###########################################################

enrole.ldapserver.root=dc=my_suffix

Thus, the E component of the pseudo-DN will be:

dc=my_suffix

Putting all the components together results in the following pseudo-DN

(A+C+D+E; no component B was required):

erservicename=Irvine Sales, ou=Sales,l=Irvine o=Acme Inc,ou=Acme,dc=my_suffix

Setting attributes to be reconciled

Setting attributes to be reconciled consists of selecting attributes that will trigger

event notifications when their values change. Attributes that change frequently

(password age or last successful logon, for example) can be omitted.

Note: The event notification entry types and attributes will NOT appear until the

first reconciliation, with event notification enabled, has been performed.

1. Type E (Set attributes to be reconciled) at the Event Notification Menu.

The Event Notification Entry Types Menu appears.

Select menu option:e

Event Notification Entry Types

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

A. erRacfAcct

B. erRacfGrp

X. Done

Select menu option:

2. Type A for attributes returned during a user reconciliation or type B for

attributes returned during a group reconciliation.

The Event Notification Attribute Listing for the selected reconciliation type

appears.


Note: The default setting lists all attributes the adapter supports.


Event Notification Attribute Listing

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

{A} ** eraccountstatus {B} ** erracconxml {C} ** erracuclauth

{D} ** erracucredate {E} ** erracudfltgrp {F} ** erracuinstdata

{G} ** erracuisadsp {H} ** erracuisaudit {I} ** erracuisgrpacc

{J} ** erracuisomvsseg {K} ** erracuisoper {L} ** erracuisprotect

{M} ** erracuisrestrict {O} ** erracuisspecial {Q} ** erracuistsoseg

{R} ** erracuisuaudit {S} ** erraculogtime {T} ** erracuname

(p)rev Page 1 of 2 (n)ext

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

X. Done

Select menu option:

3. Type the letter option of the attribute to exclude from an event notification.

Attributes that are marked with the asterisks are returned during the event

notification. Attributes that are not marked with asterisks are not returned

during the event notification.

Modifying an event notification context

An event notification context corresponds to a service on the Tivoli Identity

Manager Server. Some adapters support multiple services. One RACF Adapter can

have several Tivoli Identity Manager services, by specifying a different base point

for each service. You can have multiple event notification contexts, but you must

have at least one adapter. In the example screen below, note that Context1,

Context2, and Context3 are 3 different contexts, all having a different base point.

In order to modify an event notification context, complete the following steps:

1. At the Event Notification Menu, type H. The Modify Context Menu is

displayed.

Modify Context Menu

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

A. Context1

B. Context2

C. Context3

X. Done

Select menu option:

2. Type the letter of the menu option that you want to modify. The Modify

Context Menu for the selected context is displayed.


B. Target DN:

C. Delete Baseline Database

X. Done

Select menu option:

Table 12. Options for the modify context menu


A Adding search attributes for event notification See page 60.

B Configuring the target DN for event notification

contexts

See page 60.


Table 12. Options for the modify context menu (continued)


C Removing the baseline database for event

notification contexts

See page 61.

Adding search attributes for event notification

For some adapters, you might need to specify an attribute-value pair for one or

more contexts. These attribute-value pairs, which are defined by completing the

steps below, serve multiple purposes:

v When multiple services are supported by a single adapter, each service needs to

specify one or more attributes to differentiate it from the other services.

v The search attributes are passed to the event notification process, once the event

notification interval has occurred or is started manually. For each context, a full

search request is sent to the adapter. Additionally, the attributes specified for

that context are passed to the adapter.

v When the Tivoli Identity Manager Server initiates a reconciliation process, the

adapter replaces the local database that represents this service with the new

database.

In order to add search attributes, complete the following steps:

1. At the Modify Context Menu for the context, type A. The Reconciliation

Attribute Passed to Agent Menu is displayed.

Reconciliation Attributes Passed to Agent for Context: Context1

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

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



C. Remove attribute

X. Done

Select menu option:

2. Type the letter of the menu option that you want to change.

The supported attribute names will be displayed with two asterisks (**) in front

of each name. When you type the letter of an attribute, it will toggle the

asterisks on and off. Attributes without asterisks will not be updated during an

event notification.

The Reconciliation Attributes Passed to Agent Menu is displayed with the

changes displayed.

Configuring the target DN for event notification contexts

The target DN field holds the unique name of the service that receives event

notification updates.

In order to configure the target DN, complete the following steps:

1. At the Modify Context Menu for the context, type B. The following prompt is

displayed:

Enter Target DN:

2. Type the target DN for the context, and press Enter. The target DN for the

event notification context must be in the following format:

erservicename=erservicename,o=organizationname,ou=tenantname,rootsuffix


Each element of the DN is defined as follows:

Table 13. 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 in which

the organization is in. If this is an enterprise

installation, this is the name of the

organization.

rootsuffix Specifies the root of the directory tree. This

value is the same as the value of Identity

Manager DN Location which is specified

during the Tivoli Identity Manager Server

installation.

The Modify Context Menu is displayed with the new target DN listed.

Removing the baseline database for event notification contexts

This option is only available after a context is created and a reconciliation is run on

the context to create a Baseline Database file.

At the Modify Context Menu for the context, type C. The Modify Context Menu is

displayed with the Delete Baseline Database option removed.

Changing the configuration key

You use the configuration key as a password to access the configuration tool for

the adapter.

In order to change the RACF Adapter configuration key, complete the following

steps:

1. At the Main Menu prompt, type D.

2. Change the value of the configuration key, and press Enter.

Press Enter to return to the Main Configuration Menu without changing the

configuration key. The default configuration key is agent. Make sure that you

choose high-quality passwords that cannot be easily guessed.

The following message is displayed:

Configuration key successfully changed.

The configuration program exits, and the Main Menu prompt is displayed.

Changing activity logging settings

When you enable logging, Tivoli Identity Manager maintains a dated log file of all

transactions, RACFAgent.log. By default, the log file is in the \log directory.

In order to change the RACF Adapter activity logging settings, complete the

following steps:

1. At the Main Menu prompt, type E.

The Agent Activity Logging Menu is displayed. The following example shows

the default activity logging settings.


Agent Activity Logging Menu

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

A. Activity Logging (Enabled).

B. Logging Directory (current: /home/itim/RACFAgent/Log).

C. Activity Log File Name (current: RACFAgent.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. Done

Select menu option:

2. Type letter of the menu option that you want to change.

Option A must be enabled in order for the values of the other options to take

effect.

Press Enter to return to the Agent Activity Logging Menu without changing the

value.

Table 14. Options for the activity logging menu


A Set this option to enabled to have the adapter maintain a dated log file

of all 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.


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 request are stored in the logging file that is in this directory.


Enter log file name:

Type a different value for the log file name. When the logging option is

enabled, details about each access request are stored in the logging file.

D The following prompt is displayed:

Enter maximum size of log files (mbytes):

Type a new value, for example, 10. The oldest data is archived when the

log file reaches the maximum file size. File size is measured in

megabytes. It is possible for the activity log file size to exceed disk

capacity.

E The following prompt is displayed:

Enter maximum number of log files to retain:

Type a new value up to 100, for example, 5. The adapter automatically

deletes the oldest activity logs beyond the specified limit.


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


F If this option is set to enabled, the adapter includes the debug

statements 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 file

of all transactions. The detail logging option must be used for diagnostic

purposes only. Detailed logging enables more messages from the adapter

and 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.

H If this option is set to enabled, the adapter maintains a log file of all

transactions in the Agent Development Kit (ADK) and library files. Base

logging will substantially increase 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 will contain thread IDs, in addition

to a date and timestamp on every 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.

3. Press Enter if you changed the value for option B, C, D, or E. The other options

are changed automatically when you type the corresponding letter of the menu

option.

The Agent Activity Logging Menu is displayed with your new settings.

Changing registry settings

In order to change the RACF Adapter registry settings, complete the following

steps:

Refer to Appendix B, “Registry settings,” on page 107 for a table containing the

valid registry options, their values and meanings.

1. At the Main Menu, type F. The Registry Menu is displayed.


RACFAgent 4.6 Agent Registry Menu

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

A. Modify Non-encrypted registry settings.

B. Modify encrypted registry settings.

C. Multi-instance settings.

X. Done

Select menu option:

2. See the following procedures on modifying registry settings.

Modifying non-encrypted registry settings

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

Menu is displayed.

Agent Registry Items

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

01. APPCCMD ’ITIMCMD’

02. APPCRECO ’ITIMRECO’

03. ENROLE_VERSION ’4.0’

04. PASSEXPIRE ’FALSE’

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

Page 1 of 1



C. Remove attribute

X. Done

Select menu option:

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

an attribute.

Table 15. Attribute configuration option descriptions


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.

The non-encrypted registry settings menu reappears and displays your new

setting(s).

Changing advanced settings

You can change the RACF Adapter thread count settings for the following types of

requests:

v System Login Add

v System Login Change

v System Login Delete

v Reconciliation

These settings determine the maximum number of requests that the RACF Adapter

processes concurrently. In order to change these settings, complete the following

steps:


1. At the Main Menu prompt, type G.

The Advanced Settings Menu is displayed. The following example shows the

default thread count settings.

RACFAgent 4.6 Advanced Settings Menu

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

A. Single Thread Agent (current:TRUE)

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)

J. Thread Priority Level (1-10) (current:4)

X. Done

Select menu option:

2. Type letter of the menu option that you want to change. For a description of

each option, see Table 16.

Table 16. Options for the advanced settings menu

Option Description

A Forces the adapter to allow only one request at a time.

The default value is TRUE.

B Controls how many simultaneous ADD requests can run at one time.

The default value is 3.

C Controls how many simultaneous MODIFY requests can run at one time.


D Controls how many simultaneous DELETE requests can run at one time.


E Controls how many simultaneous SEARCH requests can run at one time.


F Determines whether the adapter allows pre- and post-exec functions.

Enabling this option is a potential security risk.

The default value is FALSE.

G This option is no longer supported.

H This option is no longer supported.

I Currently, this adapter does not support processing filters directly. This

option must always be FALSE.

J Sets the thread priority level for the adapter.


3. Change the value, and press Enter.

The Advanced Settings Menu is displayed with your new settings.


Viewing statistics

In order to view an event log for the RACF Adapter, complete the following steps:

1. At the Main Menu prompt, type H.

The activity history for the adapter is displayed.

RACFAgent 4.6 Agent Request Statistics

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

Date Add Mod Del Ssp Res Rec

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

10/19/2004 000000 000004 000000 000000 000000 000004

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

X. Done

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

Changing code page settings

Default adapter code page locale

The default code page setting for adapters is US-ASCII for ASCII based adapters.

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

Obtaining a list of valid code pages

To obtain a list of valid code page locale names, you need to run agentCfg as

follows:

agentCfg -ag adaptername -codepages

The adapter must already be activated, and the adapter configuration key will

have to be entered. This will display the list of valid code page names available for

this adapter. The following is a partial session with agentCfg displaying a list of

valid code pages:


IBMUSER:/u/ibmuser/racfagent/bin: >agentCfg -ag racfagent -codepages

Enter configuration key for Agent ’racfagent’:

List of codepage supported by ICU :

UTF-8

UTF-16

UTF-16BE

UTF-16LE

UTF-32

UTF-32BE

UTF-32LE

UTF16_PlatformEndian

UTF16_OppositeEndian

UTF32_PlatformEndian

UTF32_OppositeEndian

ISO-8859-1

US-ASCII

.

.

.

ibm-37_P100-1995,swaplfnl













ibm-16804_X110-1999,swaplfnl

ebcdic-xml-us

IBMUSER:/u/ibmuser

Setting the code page

In order to change the code page settings for the RACF Adapter, complete the

following steps:

1. At the Main Menu prompt, type I.

The Code Page Support Menu for the adapter is displayed.

RACFAgent 4.6 Codepage Support Menu

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

* Configured codepage: US-ASCII

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

*

*******************************************

* Restart Agent After Configuring Codepages

*******************************************

A. Codepage Configure.

X. Done

Select menu option:

2. Type A to configure a code page.

Note: The RACFAgent uses unicode, therefore this option is not applicable.

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


Once a code page has been selected, you must restart the adapter for the setting to

take effect.

Here is a sample session with agentCfg, altering the default code page, from US

EBCDIC (IBM-1047) to Spanish EBCDIC (IBM-1145):

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

Enter configuration key for Agent ’racfagent’:

RACFAGENT 4.6 Agent Main Configuration Menu

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








H. Statistics.


X. Done

Select menu option:i

RACFAGENT 4.5.1017 Codepage Support Menu

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

* Configured codepage: IBM-1047-s390

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

*

*******************************************


*******************************************


X. Done


Enter Codepage: ibm-1145

RACFAGENT 4.5.1017 Codepage Support Menu

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

* Configured codepage: ibm-1145

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

*

*******************************************


*******************************************


X. Done


Accessing help and additional options

In order to access the agentCfg help menu and use the help arguments, complete

the following steps:

1. At the Main Menu prompt, type X. The DOS command prompt is displayed,

and you are in the \bin directory.

2. Type agentCfg -help at the prompt to view the help menu.

The following list of possible commands is displayed:


-version ; Show version

-hostname < value> ; Target nodename to connect to (Default:Local host IP 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

-confidencetest ; Confidence test

-setup ; Confidence test setup

-help ; Display this help screen

Table 17 describes each argument.

Table 17. Arguments and descriptions for the agentCfg help menu

Argument Description

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

-hostname <value> Use the -hostname argument with any of the following

arguments to specify a different host:

v -findall

v -list

v -tail

v -agent

Enter a host name or IP address as the value.

-findall Use this argument to search and display all port addresses

between 44970 and 44994 and their assigned adapter names.

This option will timeout on unused port numbers, so it might

take several minutes to complete.

Add the -hostname argument to search a remote host.

-list Use this argument to display the adapters that are installed

on the local host of the RACF Adapter. By default, the first

time you install an adapter, it is either assigned to port

address 44970 or to the next available port number. All

subsequently installed adapters are then assigned to the next

available port address. Once an unused port is found, the

listing stops.

Use the -hostname argument to search a remote host.

-agent <value> Use this argument to specify the adapter that you want to

configure. Enter an adapter name as the value. Use this

argument with the -hostname argument to modify the

configuration setting from a remote host. You can also use

this argument with the -tail argument.

-tail Use this argument with the -agent argument to display the

activity log for an adapter. Add the -hostname argument to

display the log file for an adapter on a different host.

-schema This option is no longer supported.

-portnumber <value> Use this argument with the -agent argument to specify the

port number that is used for connections for the agentCfg

tool.

-netsearch <value> Use this argument with the -findall argument to display all

active adapters on the system. You must specify a subnet

address as the value.


Table 17. Arguments and descriptions for the agentCfg help menu (continued)

Argument Description

-confidencetest Use this argument to run a test to add, modify, search, and

delete a request to the adapter. The confidence test allows

you to test the connection between the adapter and the MVS

RACF. This allows you to verify that the adapter can connect

to MVS RACF without the Tivoli Identity Manager Server.

-setup Use this argument, along with the −confidence argument, to

configure the confidence test.

-help Use this argument to display the Help information for the

agentCfg command.

3. Type agentCfg and one or more of the supported arguments at the prompt.

You must type agentCfg before every argument to run the adapter

configuration tool.

Type agentCfg -list to list all of the adapters on the local host IP address.

Note that the default node for the Tivoli Identity Manager Server is 44970. The

output is similar to the following output:

Agent(s) installed on node ’127.0.0.1’

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

RACFAgent (44970)

Type agentCfg -agent RACFAgent to display the Main Menu of the agentCfg

tool, which is used to view or modify the RACF Adapter parameters.

Type agentCfg -list -hostname 192.9.200.7 to list the adapters on a host

whose IP address is 192.9.200.7. Note that the default node for the RACF

Adapter is 44970. The output is similar to the following output:

Agent(s) installed on node ’192.9.200.7’

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

RACFAgent (44970)

Type agentCfg -agent RACFAgent -hostname 192.9.200.7 to display the Main

Menu of the agentCfg tool for a host whose IP address is 192.9.200.7. Use the

menu options to view or modify the RACF Adapter parameters.


Chapter 5. Configuring SSL authentication for the RACF

adapter

In order to establish a secure connection between a Tivoli Identity Manager

adapter and the Tivoli Identity Manager Server, you must configure the adapter

and the server to use the Secure Sockets Layer (SSL) authentication with the

default communication protocol, DAML. By configuring the adapter for SSL, you

ensure that the Tivoli Identity Manager Server verifies the identity of the adapter

before a secure connection is established.

You can configure SSL authentication for connections that originate from the Tivoli

Identity Manager Server or from the adapter. Typically, the Tivoli Identity Manager

Server initiates a connection to the adapter in order to set or retrieve the value of a

managed attribute on the adapter. However, depending on the security

requirements of your environment, you might need to configure SSL authentication

for connections that originate from the adapter. For example, if the adapter uses

events to notify the Tivoli Identity Manager Server of changes to attributes on the

adapter, you can configure SSL authentication for Web connections that originate

from the adapter to the Web server used by the Tivoli Identity Manager Server.

In a production environment, you need to enable SSL security; however, for testing

purposes you might want to disable SSL. If an external application that

communicates with the adapter (such as the Tivoli Identity Manager Server) is set

to use server authentication, you must enable SSL on the adapter to verify the

certificate that the application presents.

This chapter presents an overview of SSL authentication, certificates, and how to

enable SSL authentication using the CertTool utility.

Overview of SSL and digital certificates

When you deploy Tivoli Identity Manager in an enterprise network, you must

secure communication between the Tivoli Identity Manager Server and the

software products and components with which the server communicates. The

industry-standard SSL protocol, which uses signed digital certificates from a

certificate authority (CA) for authentication, is used to secure communication in a

Tivoli Identity Manager deployment. Additionally, SSL provides encryption of the

data exchanged between the applications. Encryption makes data transmitted over

the network intelligible only to the intended recipient.

Signed digital certificates enable two applications connecting in a network to

authenticate each other’s identity. An application acting as an SSL server presents

its credentials in a signed digital certificate to verify to an SSL client that it is the

entity it claims to be. An application acting as an SSL server can also be configured

to require the application acting as an SSL client to present its credentials in a

certificate, thereby completing a two-way exchange of certificates. Signed

certificates are issued by a third-party certificate authority for a fee. Some utilities,

such as those provided by OpenSSL, can also issue signed certificates.

A certificate-authority certificate (CA certificate) must be installed to verify the

origin of a signed digital certificate. When an application receives another

application’s signed certificate, it uses a CA certificate to verify the originator of


the certificate. A certificate authority can be well-known and widely used by other

organizations, or it can be local to a specific region or company. Many applications,

such as Web browsers, are configured with the CA certificates of well−known

certificate authorities to eliminate or reduce the task of distributing CA certificates

throughout the security zones in a network.

Private keys, public keys, and digital certificates

Keys, digital certificates, and trusted certificate authorities are used to establish and

verify the identities of applications.

SSL uses public key encryption technology for authentication. In public key

encryption, a public key and a private key are generated for an application. Data

encrypted with the public key can only be decrypted using the corresponding

private key. Similarly, the data encrypted with the private key can only be

decrypted using the corresponding public key. The private key is

password-protected in a key database file so that only the owner can access the

private key to decrypt messages that are encrypted using the corresponding public

key.

A signed digital certificate is an industry-standard method of verifying the

authenticity of an entity, such as a server, client, or application. In order to ensure

maximum security, a certificate is issued by a third-party certificate authority. A

certificate contains the following information to verify the identity of an entity:

Organizational information

This section of the certificate contains information that uniquely identifies

the owner of the certificate, such as organizational name and address. You

supply this information when you generate a certificate using a certificate

management utility.

Public key

The receiver of the certificate uses the public key to decipher encrypted

text sent by the certificate owner to verify its identity. A public key has a

corresponding private key that encrypts the text.

Certificate authority’s distinguished name

The issuer of the certificate identifies itself with this information.

Digital signature

The issuer of the certificate signs it with a digital signature to verify its

authenticity. This signature is compared to the signature on the

corresponding CA certificate to verify that the certificate originated from a

trusted certificate authority.

Web browsers, servers, and other SSL-enabled applications generally accept as

genuine any digital certificate that is signed by a trusted certificate authority and is

otherwise valid. For example, a digital certificate can be invalidated because it has

expired or the CA certificate used to verify it has expired, or because the

distinguished name in the digital certificate of the server does not match the

distinguished name specified by the client.

Self-signed certificates

You can use self-signed certificates to test an SSL configuration before you create

and install a signed certificate issued by a certificate authority. A self-signed

certificate contains a public key, information about the owner of the certificate, and

the owner’s signature. It has an associated private key, but it does not verify the

origin of the certificate through a third-party certificate authority. Once you


generate a self-signed certificate on an SSL server application, you must extract it

and add it to the certificate registry of the SSL client application.

This procedure is the equivalent of installing a CA certificate that corresponds to a

server certificate. However, you do not include the private key in the file when

you extract a self-signed certificate to use as the equivalent of a CA certificate.

Use a key management utility to generate a self-signed certificate and a private

key, to extract a self-signed certificate, and to add a self-signed certificate.

Where and how you choose to use self-signed certificates depends on your security

requirements. In order to achieve the highest level of authentication between

critical software components, do not use self-signed certificates, or use them

selectively. For example, you can choose to authenticate applications that protect

server data with signed digital certificates, and use self-signed certificates to

authenticate Web browsers or Tivoli Identity Manager adapters.

If you are using self-signed certificates, in the following procedures you can

substitute a self-signed certificate for a certificate and CA certificate pair.

Certificate and key formats

Certificates and keys are stored in files with the following formats:

.pem format

A privacy-enhanced mail (.pem ) format file begins and ends with the

following lines:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

A .pem file format supports multiple digital certificates, including a

certificate chain. If your organization uses certificate chaining, use this

format to create CA certificates.

.arm format

An .arm file contains a base-64 encoded ASCII representation of a

certificate, including its public key, but not its private key. An .arm file

format is generated and used by the IBM Key Management utility.

.der format

A .der file contains binary data. A .der file can only be used for a single

certificate, unlike a .pem file, which can contain multiple certificates.

.pfx format (PKCS12)

A PKCS12 file is a portable file that contains a certificate and a

corresponding private key. This format is useful for converting from one

type of SSL implementation to a different implementation. For example,

you can create and export a PKCS12 file using the IBM Key Management

utility, then import the file to another machine using the CertTool utility.

The use of SSL authentication

When you start the adapter, the available connection protocols are loaded. The

DAML protocol is the only available protocol that supports the use of SSL

authentication. You can specify to use the DAML SSL implementation.

The DAML SSL implementation uses a certificate registry to store private keys and

certificates. The location of the certificate registry is managed internally by the

Chapter 5. Configuring SSL authentication for the RACF adapter 73

CertTool key and certificate management tool; therefore, you do not specify the

location of the registry when you perform certificate management tasks.

For more information on the DAML protocol, see “Changing protocol

configuration settings” on page 41.

Configuring certificates for SSL authentication

Use the following procedures to configure the adapter for one-way or two-way SSL

authentication using signed certificates. In order to perform these procedures, use

the CertTool utility.

Configuring certificates for one-way SSL authentication

In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager

adapter are set to use SSL. Client authentication is not set on either application.

The Tivoli Identity Manager Server operates as the SSL client and initiates the

connection. The adapter operates as the SSL server and responds by sending its

signed certificate to the Tivoli Identity Manager Server. The Tivoli Identity

Manager Server uses the CA certificate that is installed to validate the certificate

sent by the adapter.

In Figure 4, Application A operates as the Tivoli Identity Manager Server, and

Application B operates as the Tivoli Identity Manager adapter.

In order to configure one-way SSL, perform the following tasks for each

application:

1. On the adapter, complete these steps:

a. Start the CertTool utility.

b. In order 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 separate

private key and places the private key in the PENDING_KEY registry

value.

2) Submit the CSR to the certificate authority using the instructions

supplied by the CA. When you submit the CSR, specify that you want

the root CA certificate returned with the server certificate.2. On the Tivoli Identity Manager Server, complete one of these steps:

Hello

Tivoli Identity ManagerServer (SSL client)

KeystoreCA

CertificateA

1

Send Certificate B

Tivoli Identity Manageradapter (SSL server)C

CertificateA

Verify

Figure 4. One-way SSL authentication (server authentication)


v If you are configuring the use of a signed certificate issued by a well-known

CA, ensure that the Tivoli Identity Manager Server has stored the root

certificate of the CA (CA certificate) in its keystore. If the keystore does not

contain the CA certificate, extract the CA certificate from the adapter and add

it to the keystore of the server.

v If you are configuring the use of self-signed certificates:

– If you generated the self-signed certificate on the Tivoli Identity Manager

Server, the certificate is already installed in its keystore.

– If you generated the self-signed certificate using the key management

utility of another application, extract the certificate from that application’s

keystore and add it to the keystore of the Tivoli Identity Manager Server.

Configuring certificates for two-way SSL authentication

In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager

adapter are set to use SSL and the adapter is set to use client authentication. Once

sending its certificate to the Tivoli Identity Manager Server, the adapter requests

identity verification from the server, which sends its signed certificate to the

adapter. Both applications are configured with signed certificates and

corresponding CA certificates.

In Figure 5, the Tivoli Identity Manager Server operates as Application A, and the

Tivoli Identity Manager adapter operates as Application B.

The following procedure assumes that you have already configured the adapter

and Tivoli Identity Manager Server for one-way SSL authentication using the

procedure described in “Configuring certificates for one-way SSL authentication”

on page 74. Therefore, if you are using signed certificates from a CA:

v The adapter is configured with a private key and a signed certificate that was

issued by a CA.

v The Tivoli Identity Manager Server is configured with the CA certificate of the

CA that issued the signed certificate of the adapter.

In order to complete the certificate configuration for two-way SSL, perform the

following tasks:

CHello

KeystoreCA

CertificateA

CertificateB

CertificateA

CACertificate

B

Send Certificate A

Tivoli Identity Manageradapter (SSL server) C

Tivoli Identity ManagerServer (SSL client)

Send Certificate AVerify

Verify

Send Certificate B

Figure 5. Two-way SSL authentication (client authentication)


1. On the Tivoli Identity Manager Server, create a CSR and private key, obtain a

certificate from a CA, install the CA certificate, install the newly signed

certificate, and extract the CA certificate to a temporary file.

2. On the adapter, add the CA certificate that was extracted from the keystore of

the Tivoli Identity Manager Server to the adapter.

When you have finished the two-way certificate configuration, each application has

its own certificate and private key and the CA certificate of the CA that issued the

certificates for each application.

Configuring certificates when the adapter operates as an SSL

client

In this scenario, the adapter operates as an SSL client in addition to operating as

an SSL server. This scenario applies if the adapter initiates a connection to the Web

server (used by the Tivoli Identity Manager Server) to send an event notification.

For example, the adapter initiates the connection and the Web server responds by

presenting its certificate to the adapter.

Figure 6 illustrates how a Tivoli Identity Manager adapter operates as an SSL sever

and an SSL client. When communicating with the Tivoli Identity Manager Server,

the adapter sends its certificate for authentication. When communicating with 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 the

identity of the adapter, which sends its signed certificate to the Web server (not

shown in the illustration). In order to enable two-way SSL authentication between

the adapter and Web server, use the following procedure:

1. 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 using the CertTool utility.

4. Add the CA certificate corresponding to the signed certificate of the adapter to

the Web server.

TivoliIdentityManagerAdapter

TivoliIdentityManagerServer

CA Certificate ACertificate ACA Certificate C

Certificate C

Web server

A B

C

Hello

Certificate A

Hello

Certificate C

Figure 6. Tivoli Identity Manager adapter operating as an SSL server and an SSL client


For more information on configuring certificates when the adapter initiates a

connection to the Web server (used by the Tivoli Identity Manager Server) to send

an event notification, see the Tivoli Identity Manager Information Center.

Managing SSL certificates using CertTool

The procedures in this section describe how to use the CertTool utility to manage

private keys and certificates.

This section includes instructions for performing the following tasks:

v “Starting CertTool.”

v “Generating a private key and certificate request” on page 79.

v “Installing the certificate” on page 80.

v “Installing the certificate and key from a PKCS12 file” on page 80.

v “Viewing the installed certificate” on page 81.

v “Viewing CA certificates” on page 81.

v “Installing a CA certificate” on page 81.

v “Deleting a CA certificate” on page 81.

v “Viewing registered certificates” on page 82.

v “Registering a certificate” on page 82.

v “Unregistering a certificate” on page 82.

Starting CertTool

In order to start the certificate configuration tool, CertTool, for the RACF Adapter,

complete these steps:

1. Log into the RACF Adapter.

2. Change to the bin directory for the adapter. For example, if the RACF Adapter

directory is in the default location, type the following command:

# cd home/itim/RACFAgent/bin

3. Type CertTool -agent RACFAgent at the prompt. The Main Menu is displayed:

Main menu - Configuring agent: RACFAgent

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












X. Quit

Choice:

From the Main Menu, you can generate a private key and certificate request, install

and delete certificates, register and unregister certificates, and list certificates. The

following sections summarize the purpose of each group of options.


The first set of options (A through D) allows you to generate a CSR and install the

returned signed certificate on the adapter.


Generate a CSR and the associated private key that is sent to the certificate

authority. For more information on option A, see “Generating a private key

and certificate request” on page 79.


Install a certificate from a file. This file must be the signed certificate

returned by the CA in response to the CSR that is generated by option A.

For more information on option B, see “Installing the certificate” on page

80.

C. Install certificate and key from a PKCS12 file

Install a certificate from a PKCS12 format file that includes both the public

certificate and a private key. If options A and B are not used to obtain a

certificate, the certificate that you use must be in PKCS12 format. For more

information on option C, see “Installing the certificate and key from a

PKCS12 file” on page 80.


View the certificate that is installed on the system. For more information

on option D, see “Viewing the installed certificate” on page 81.

The second set of options enable you to install root CA certificates on the adapter.

A CA certificate is used by the Tivoli Identity Manager adapter to validate the

corresponding certificate presented by a client, such as the Tivoli Identity Manager

Server.


Show the installed CA certificates. The adapter only communicates with

Tivoli Identity Manager Servers whose certificates are validated by one of

the installed CA certificates.


Install a new CA certificate so that certificates generated by this CA can be

validated. The CA certificate file can either be in X.509 or PEM encoded

formats. For more information on how to install a CA certificate, see

“Installing a CA certificate” on page 81.


Remove one of the installed CA certificates. For more information on how

to delete a CA certificate, see “Deleting a CA certificate” on page 81.

The remaining options (H through K) apply to adapters that must authenticate the

application (for example, the Tivoli Identity Manager Server or the Web server) to

which the adapter is sending information. These options enable you to register

certificates on the adapter. For Tivoli Identity Manager Version 4.5 or earlier, the

signed certificate of the Tivoli Identity Manager Server must be registered with an

adapter to enable client authentication on the adapter. If you do not intend to

upgrade an existing adapter to use CA certificates for client authentication, the

signed certificate presented by the Tivoli Identity Manager Server must be

registered with the adapter.

If you configure the adapter to use event notification, or client authentication is

enabled in DAML, then you must install the CA certificate corresponding to the

signed certificate of the Tivoli Identity Manager Server using the Install a CA

certificate option, option F.



List all registered certificates that will be accepted for communications. For

more information on listing registered certificates, see “Viewing registered

certificates” on page 82.

I. Register a certificate

Register a new certificate. The certificate to be registered be in Base 64

encoded X.509 format or PEM. For more information on registering

certificates, see “Registering a certificate” on page 82.


Unregister (remove) a certificate from the registered list. For more

information on unregistering certificates, see “Unregistering a certificate”

on page 82.


Export a previously installed certificate and private key. You will be

prompted for the filename and a password for encryption. For more

information on exporting a certificate and key to a PKCS12 file, see

“Exporting a certificate and key to PKCS12 file” on page 82.

Generating a private key and certificate request

A certificate signing request is an unsigned certificate that is a text file. When you

submit an unsigned certificate to a certificate authority, the CA signs the certificate

with the private digital signature that is included in their corresponding CA

certificate. When the CSR is signed, it becomes a valid certificate. A CSR contains

information about your organization, such as the organization name, country, and

the public key for your Web server.

In order to generate a CSR file, complete these steps:

1. At the Main Menu of the CertTool, type A. The following message and prompt

are displayed:

Enter values for certificate request (press enter to skip value)

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

2. At the Organization prompt, type your organization name, and press Enter.

3. At the Organizational Unit prompt, type the organizational unit, and press

Enter.

4. At the Agent Name prompt, type the name of the adapter you are requesting

a certificate for, and press Enter.

5. At the Email prompt, type the e-mail address for the contact person for this

request, and press Enter.

6. At the State prompt, type the state in which the adapter resides (if the adapter

is in the United States), and press Enter. Some certificate authorities do not

accept two letter abbreviations for states, so you must type the full name of

the state.

7. At the Country prompt, type the country in which the adapter resides, and

press Enter.

8. At the Locality prompt, type the name of the city in which the adapter

resides, and press Enter.

9. At the Accept these values prompt, type Y to accept the values displayed, or

type N to re-enter the values, and press Enter.

The private key and certificate request are generated once the values are

accepted.


10. At the Enter name of file to store PEM cert request prompt, type the name of

the file that you want to use to store the values you specified during the

previous steps, and press Enter.

11. Press Enter to continue. The certificate request and input values are written to

the file you specified, and the Main Menu is displayed again.

You can now request a certificate from a trusted CA by sending the .pem file that

you just generated to a certificate authority vendor.

Example of certificate signing request

Your CSR file will look similar to the following example:

-----BEGIN CERTIFICATE REQUEST-----

MIIB1jCCAT8CAQAwgZUxEjAQBgNVBAoTCWFjY2VzczM2MDEUMBIGA1UECxMLZW5n

aW5lZXJpbmcxEDAOBgNVBAMTB250YWdlbnQxJDAiBgkqhkiG9w0BCQEWFW50YWdl

bnRAYWNjZXNzMzYwLmNvbTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3Ju

aWExDzANBgNVBAcTBklydmluZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA

mR6AcPnwf6hLLc72BmUkAwaXcebtxCoCnnTH9uc8VuMHPbIMAgjuC4s91hPrilG7

UtlbOfy6X3R3kbeR8apRR9uLYrPIvQ1b4NK0whsytij6syCySaFQIB6V7RPBatFr

6XQ9hpsARdkGytZmGTgGTJ1hSS/jA6mbxpgmttz9HPECAwEAAaAAMA0GCSqGSIb3

DQEBAgUAA4GBADxA1cDkvXhgZntHkwT9tCTqUNV9sim8N/U15HgMRh177jVaHJqb

N1Er46vQSsOOOk4z2i/XwOmFkNNTXRVl9TLZZ/D+9mGZcDobcO+lbAKlePwyufxK

Xqdpu3d433H7xfJJSNYLYBFkrQJesITqKft0Q45gIjywIrbctVUCepL2

-----END CERTIFICATE REQUEST-----

Installing the certificate

Once you receive your certificate from your trusted CA, you install it in the

registry of the adapter. In order to install the certificate, complete these steps:

1. If you received the certificate as part of an e-mail message, copy the text of the

certificate to a text file, and copy that file to the bin directory for the adapter.

For example,

home/itim/RACFAgent/bin

2. At the Main Menu of the CertTool, type B. The following prompt is displayed:

Enter name of certificate file:

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

3. At the Enter name of certificate file prompt, type the full path to the

certificate file, and press Enter.

The certificate is installed in the registry for the adapter, and the Main Menu is

displayed again.

Installing the certificate and key from a PKCS12 file

If you do not use the CertTool utility to generate a CSR to obtain a certificate, you

must install both the certificate and private key, which must be stored in a PKCS12

file. The CA might send a password−protected file, or PKCS12 file (a file with the

.pfx extension), which includes both the certificate and private key. In order to

install the certificate from this PKCS12 file, complete these steps:

1. Copy the PKCS12 file to the bin directory for the adapter. For example,

home/itim/RACFAgent/bin

2. At the Main Menu for the CertTool, type C. The following prompt is displayed:

Enter name of PKCS12 file:

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

3. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file

that has the certificate and private key information, and press Enter. For

example, DamlSrvr.pfx.

4. At the Enter password prompt, type the password to access the file, and press

Enter.


The certificate and private key are installed in the adapter registry, and the Main

Menu is displayed.

Viewing the installed certificate

In order to list the certificate that is installed on your system, at the Main Menu of

CertTool, type D.

The installed certificate is listed, and the Main Menu is displayed. The following

example lists an installed certificate:

The following certificate is currently installed.

Subject: c=US,st=California,l=Irvine,o=DAML,cn=DAML Server

Installing a CA certificate

If you are using client authentication, you need to install a CA certificate. The CA

certificate you install is issued by a certificate authority vendor.

In order to install a CA certificate that was extracted into a temporary file,

complete the following steps:

1. At the Main Menu prompt, type F (Install a CA certificate).

The following prompt is displayed:


2. At the Enter name of certificate file prompt, type the name of the certificate

file, such as DamlCACerts.pem, and press Enter.

The certificate file is opened, and the following prompt is displayed:

[email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng

Install the CA? (Y/N)

3. At the Install the CA prompt, type Y to install the certificate, and press Enter.

The certificate file is installed in the CACerts.pem file.

Viewing CA certificates

CertTool only installs one certificate and one private key. In order to list the CA

certificate that is installed on the adapter, type E at the Main Menu prompt.

The installed CA certificates are displayed and the Main Menu is displayed. The

following example lists an installed CA certificate:

Subject: o=IBM,ou=SampleCACert,cn=TestCA

Valid To: Wed Jul 26 23:59:59 2006

Deleting a CA certificate

In order to delete a CA certificate from the adapter directories, complete the

following steps:

1. At the Main Menu prompt, type G.

A list of all CA certificates installed on the adapter is displayed.

0 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Engineering,cn=Eng

1 - [email protected],c=US,st=California,l=Irvine,o=IBM,ou=Support,cn=Support

Enter number of CA certificate to remove:

2. At the Enter number of CA certificate to remove prompt, type the number of

the CA certificate that you want to remove, and press Enter.

The CA certificate is deleted from the CACerts.pem file, and the Main Menu is

displayed.


Viewing registered certificates

Only requests that present a registered certificate will be accepted by the adapter

when client validation is enabled.

In order to view a list of all registered certificates available to the adapter, at the

Main Menu prompt, type H.

The registered certificates are displayed and the Main Menu is displayed. The

following example lists registered certificates:



Registering a certificate

In order to register a certificate for the adapter, complete the following steps:

1. At the Main Menu prompt, type I.



2. At the Enter name of certificate file prompt, type the name of the certificate

file that you want to register, and press Enter.

The subject of the certificate is displayed, and a prompt is displayed, for

example:


Register this CA? (Y/N)

3. At the Register this CA prompt, type Y to register the certificate, and press

Enter.

The certificate is registered to the adapter, and the Main Menu is displayed.

Unregistering a certificate

In order to unregister a certificate for the adapter, complete the following steps:

1. At the Main Menu prompt, type J.

The registered certificates are displayed. The following example lists registered

certificates:



2. Type the number of the certificate file that you want to unregister, and press

Enter.

The subject of the selected certificate is displayed, and a prompt is displayed,

for example:


Unregister this CA? (Y/N)

3. At the Unregister this CA prompt, type Y to unregister the certificate, and

press Enter.

The certificate is removed from the registered certificate list for the adapter, and

the Main Menu is displayed.

Exporting a certificate and key to PKCS12 file

In order to export a certificate and key to a PKCS12 file for the adapter, complete

the following steps:

1. At the Main Menu prompt, type K.



Enter name of PKCS12 file:

2. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file

for the installed certificate or private key, and press Enter.

3. At the Enter Password prompt, type the password for the PKCS12 file, and

press Enter.

4. At the Confirm Password prompt, type the password again, and press Enter.

The certificate or private key is exported to the PKCS12 file, and the Main

Menu is displayed.



Chapter 6. Customizing the RACF adapter

There are two REXX execs provided with the installation, that allow an installation

to tailor the RACF Adapter to perform specific functions based upon an

installation’s needs:

v “ITIMEXIT”

v “ITIMEXEC” on page 86

ITIMEXIT

This REXX exec is executed in response to a processing request. There are four

instances implemented where this exit will get control:

Pre add processing

The request to add a user has been received, but not yet processed.

Post add processing

The request to add a user has been completed successfully

Pre delete processing

The request to delete a user has been received, but not yet processed.

Post delete processing

The request to delete a user has been completed successfully.

Exit processing may indicate success (return code zero), or failure (non-zero return

code) to be conveyed to the RACF Adapter. For the pre-add and pre-delete exits,

any non-zero return code will fail the processing of the current RACF user being

processed. For the post-add and post-delete exits, a non-zero return code will

return a warning for the current RACF user being processed.

The environment in which the exit exec gets control is within a TSO batch

environment, running within the APPC/MVS environment. You may call other

programs, and/or perform file I/O as necessary. Processing is performed under the

authority of the RACF ID that will perform the RACF commands to accomplish

the function. Any valid TSO command may be performed, as long as it does not

attempt to prompt a terminal user for input.

The ITIMEXIT exec should always be present, whether or not it performs any

functions. The sample ITIMEXIT provided has an exit 0 as the first executable

statement. You must modify or alter this exit to meet your needs.

The sample exit provides some function you may wish to use or customize to your

needs. Some examples of its use are:

v Defining a user’s catalog alias in one or more master catalogs at POST ADD exit

time.

v Defining a user’s data set profile at POST ADD exit time.

v Defining a user’s OMVS (Unix System Services) home directory at POST ADD

exit time.

v Deleting a users data set profiles at PRE DELETE exit time.

v Deleting a user’s catalog alias at POST DELETE exit time.


Be aware that any of the above functions that you wish to make the exit capable of

doing, must have proper RACF authorization given to the processing ID.

The following information is made available to the exit:

Table 18. ITIMEXIT processing information

Parameter # Meaning Possible values When present

1 Verb

Indicates what

operation is calling

the exit.

ADD or DELETE Always

2 Object

The object name of

the transaction.

USER indicating this

is a RACF user object

being processed.

Always

3 Prepost

Qualifies whether

this is PRE or POST

processing entry to

the exit.

PRE or POST Always

4 Name

The name of the

RACF object.

The RACF user ID

being processed.

Always

5 Dfltgrp

The RACF user ID’s

default group.

What was specified

from the Tivoli

Identity Manager

Server for this user’s

default group.

Only at PRE-ADD or

POST-ADD exit. Not

present for DELETE

processing.

6 Owner

The RACF user ID’s

owner.

What was specified

from the Tivoli

Identity Manager

Server for this user’s

owner.

Only at PRE-ADD or

POST-ADD exit. Not

present for DELETE

processing.

ITIMEXEC

This exit is provided for backward compatibility with the prior version of the

RACF Adapter.

There is no provision for passing back to the RACF Adapter the success or failure

of processing within the exit. There is no way to convey the success or failure of

exit processing back to the Tivoli Identity Manager Server. As such, any return

codes are ignored.

The environment in which the exit exec gets control is within a TSO batch

environment, running within the APPC/MVS environment. You may call other

programs, and/or perform file I/O as necessary. Processing is performed under the

authority of the RACF ID that will perform the RACF commands to accomplish

the function. Any valid TSO command may be performed, as long as it does not

attempt to prompt a terminal user for input.


Table 19. ITIMEXEC processing information

Parameter # Source Value When present

1 Tivoli Identity

Manager attribute of

erRacfExecname

The value of

erRacfExecname

Always, as this

attribute’s presence

indicates this exit

should be invoked.

2 Tivoli Identity

Manager attribute of

erRacfExecvar

The value of

erRacfExecvar

Depends upon the

request generated by

the Tivoli Identity

Manager Server.

This exit will ONLY be invoked if the erRacfExecname attribute has been sent by

the Tivoli Identity Manager Server to the adapter. The erRacfExecvar attribute will

optionally be present, depending upon the processing that occurs on the Tivoli

Identity Manager Server.

Chapter 6. Customizing the RACF adapter 87


Chapter 7. Troubleshooting the adapter

Troubleshooting is the process of determining why a product does not function as

it is designed to function. This chapter provides information to use while

attempting to identify and resolve problems related to the RACF Adapter

installation. It also provides information about troubleshooting errors that occur

due to improper input during installation.

Adapter log files

When the RACF Adapter is initially configured, a default directory is chosen to

contain the log files, which contain activity from the adapter.

The log files are kept within the Unix System Services file system, typically, under

the installation path of the adapter, in a sub directory of log/.

The adapter log name is the adapter instance name, followed by an extension of

.log. When the extension is simply .log, this is the current log file. Older log files

will have a slightly different extension, such as .log_001, .log_002 and so on.

For instance, if an installation path name is /usr/itim, and the adapter name

configured is racfagent, then you will find the log files in the /usr/itim/log/

directory, and you will find one or more files named racfagent.log,

racfagent.log_001, racfagent.log_002, and so on.

You may use the UNIX tail command, obrowse, or any other UNIX based utility

to inspect these adapter logs.

Adapter logging is configured with the agentCfg program. Each instance of an

adapter may have a different directory, but by default, will all be contained in the

same directory underneath the installation path.

The size of a log file, the number of log files, the directory path, and the detail

level of logging are all configured with the agentCfg program.

Please refer to Chapter 4, “Configuring the RACF adapter in IBM Tivoli Identity

Manager,” on page 39 for details.



Appendix A. Agent attributes

In order for access to be granted, a target platform requires certain information

about the user. This information is collected in the Access Request Form (a value

for each attribute) during the Access Request process and is sent to the adapter by

the Tivoli Identity Manager Server. The adapter uses these values to create the user

access. Which attributes are needed depends upon the transaction requested, such

as System Login Add or Database Login Change.

Once the adapter software is installed on a platform and the adapter is defined by

Agent Maintenance, you identify the attribute data needed to create the user

access. You identify these attributes to Tivoli Identity Manager when defining the

Access Request Form for access through Request Maintenance.

Agent attributes by object

The following MVS RACF keywords can be used to create or modify RACF Access

Request Forms. MVS RACF requires only a user ID, password, and Default Group

for valid access. Be sure you include these keywords when creating the MVS RACF

Access Request Forms. A * denotes attributes for future release.

Note: Reconciliations return group data as well as user data.

erRacUser

This class represents a user account on the RACF database. There is one base user

object for each user defined in a RACF database.

Table 20. erRacUser attribute information

Attribute Data type Maximum length

Single or multiple

value

Read or

write Required?

erAccountStatus

Whether this user is in REVOKED

status, or not.

Boolean Bit Single RW No

erPassword

Password of user. Must be

alphanumeric, and can include ’@#$’.

Case insensitive.

String 8 Single RW No

erRacfExecName

Exec name - not a RACF attribute,

but for compatibility with old

RASEXEC.

String 44 Single W No

erRacfExecVar

Exec Attribute - not a RACF

attribute, but for compatibility with

old RASEXEC.


erRacfRequester

RACF ID of requesting user. This is

the ID of the person within Identity

Manager who is making the

provisioning request.



Table 20. erRacUser attribute information (continued)


Single or multiple

value

Read or

write Required?

erRacUCategory

B1 Security categories.

String 8 Multiple RW No

erRacUClauth

A list of RACF resource classes this

user has rights to administer. Any

class in the Class Descriptor Table

(CDT), and USER is valid. GROUP

and DATASET are invalid.


erRacUCreDate

Date user was created.

Date Single R No

erRacUDfltgrp

Name of existing group that is the

initial and default group this user is

associated with.

String 8 Single RW Yes

erRacUInstData

Installation defined data that may be

associated with a user.


erRacUIsADSP

User may or may not automatically

create discrete data set profiles.


erRacUIsAudit

User has system auditor ability.


erRacUIsCatalog

Run Script to create catalog Alias for

this user.

Boolean Bit Single W No

erRacUIsCICSSeg

CICS segment is present.

User CICS information. Since this is

an optional object, its presence has

meaning, even if it contains no

values for attributes. CICS this

information assigns the user specific

characteristics.


erRacUCICSIsForc

Whether this user will be forced off

if current system fails over to a

backup system.


erRacUCICSOpclas

Operator class. Valid values are 1 to

24.

Integer 2 Multiple RW No

erRacUCICSOpid

Operator ID. 1 to 3 characters. Any

value acceptable.


erRacUCICSPrty

Operator priority, value may be 0 to

255.

Integer 3 Single RW No




Single or multiple

value

Read or

write Required?

erRacUCICSTimout

User timeout value, in the form of

HHMM.

Time 4 Single RW No

erRacUIsDCESeg

DCE segment is present.

DCE information. This information

describes the user in the context of a

DCE (Distributed Computing

Environment). Since this is an

optional object, its presence has


values for attributes.


erRacUDCEIsAutoL

Whether this user should be

automatically identified to DCE

through AUTOLOGIN or not.


erRacUDCEHomeC

DCE Home Cell name.


erRacUDCEHomeU

UUID for the cell that this user is

defined to. String must have the

delimiter of ″-″ in character positions

9, 14, 19, and 24. The general format

for the UUID string is

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, in which x represents

a valid numeric or hexadecimal

character.


erRacUDCEName

DCE Principal name.


erRacUDCEUUID

UUID of this instance of the user.

This string must have the delimiter

of ″-″ in character positions 9, 14, 19,

and 24. The general format for the

UUID string is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, in which x

represents a valid numeric or

hexadecimal character.


erRacUIsDFPSeg

DFP segment is present.

The following attributes are user

DFP information. Since this is an



values for attributes. DFP uses this

information to determine data

management and disk storage

characteristics when a user creates a

new data set.


Appendix A. Agent attributes 93



Single or multiple

value

Read or

write Required?

erRacUDFPAppl

Name of a user defined application.


erRacUDFPData

DATACLAS name to be used for

new file creation.


erRacUDFPMgmt

MGMTCLAS name to be used for

new file creation.


erRacUDFPStor

STORCLAS name to be used for new

file creation.


erRacUIsEimSeg

EIM segment is present.

EnterPrise Identity Management

(EIM). This object contains a name

from the LDAPBIND general

resource profile class, of the user as

it is known to the Enterprise Identity

Mapping environment. Since this is

an optional object, its presence has




erRacUEimLDAPNam

Name of profile in the LDAPBIND

class.


erRacUIsGrpacc

Permits group level access of

UPDATE to the group under the

High Level Qualifier of any dataset

profile created through ADSP by this

user.


erRacUIsKerbSeg

Kerberos segment is present.

Kerberos information. This object

describes Kerberos information that

relates to this instance of the user.

Since this is an optional object, its

presence has meaning, even if it

contains no values for attributes.


erRacUKerbIsDES

Single length DES keys allowed.


erRacUKerbIsDES3

Triple DES keys allowed.


erRacUKerbIsDESD

Double DES keys allowed.





Single or multiple

value

Read or

write Required?

erRacUKerbName

Kerberos Principal name. can consist

of any character except the @+

(X’7C’) character. It is highly

recommended that you avoid using

any of the EBCDIC variant characters

be avoided to prevent problems

between different code pages.


erRacUKerbTickMx

Maximum ticket life, in seconds.

Valid value range is 1 to

2,147,483,647.


erRacUIsLangSeg

Language segment is present.

User Language information. Since

this is an optional object, its presence

has meaning, even if it contains no



erRacULangPrime

Primary user language.


erRacULangSec

Secondary user language.


erRacUIsLNotes

Lotus Notes segment present.

Lotus Notes information. This object

contains a Lotus Notes short name,

of the user as it is known to this

RACF system. Since this is an





erRacULnotesSNam

Lotus Notes Short Name. You can

specify the following characters:

upper and lower case alphabetic (A

through Z, and a through z), 0

through 9, & (X’50’), - (X’60’), .

(X’4B’), _ (X’6D’), and (X’40’). The

hex values shown are EBCDIC.


erRacUIsNDSSeg

NDS segment is present.





Single or multiple

value

Read or

write Required?

erRacUIsNetvSeg

NetView segment is present.

NetView information. This object

may or may not be present. It

contains attributes that describe this

user’s instance in the IBM Netview

environment. Since this is an





erRacUNetvCons

Console name user will assume

when console commands are issued.


erRacUNetvCtl

Only the specific values are allowed

Default is ’Specific’. Values allowed

are: General Global Specific.


erRacUNetvDomain

List of commands a Netview

operator my run in another Netview

Domain.


erRacUNetvGSpan

Not well documented. The best

information found within Netview

documentation indicates this is a

maximum of 8 characters.


erRacUNetvIC

Initial command to be run when this

Netview user enters the Netview

subsystem.


erRacUNetvIsGMF

Whether this user may utilize the

Netview Graphic Monitor Facility or

not.


erRacUNetvIsMR

Whether this user may receive

unsolicited messages or not.


erRacUNetvOpclas

Netview Operator classes. May be a

values of 1 to 2040.

Integer 4 Multiple RW No

erRacUIsOMVSSeg

OMVS segment is present.

OMVS (Unix) information. Since this

is an optional object, its presence has







Single or multiple

value

Read or

write Required?

erRacUOMVSCPU

Maximum CPU time, in seconds, this

user may accumulate before

processes will be purged. Valid value

range 7 to 2,147,483,647.


erRacUOMVSFiles

Maximum number of files per

process. Valid value range is 3 to

262,143.


erRacUOMVSHome

Home directory of user. Case

sensitive. Path must be valid for user

may use the shell.


erRacUOMVSIsHome

This attribute is set to true, if the

home (erRacUOMVSPath) directory

is to be created.


erRacUOMVSIsShar

If NOT set, and the UID specified is

already assigned, and Shared UID

support is enabled, the UID

assignment may fail.


erRacUOMVSMmap

Maximum number of pages for

memory mapped files. Valid value

range is 1 to 16,777,216.


erRacUOMVSProc

Maximum processes per user. Valid

value range is 3 to 32,767.


erRacUOMVSShell

Shell program for user. Case

sensitive. Must be a valid shell name

for user to use the shell. Should be a

fully qualified name, as the

environment has not yet been

established.


erRacUOMVSStor

Maximum amount of storage, in

bytes, this user may use. Valid value

range is 10,485,760 to 2,147,483,647.


erRacUOMVSThread

Maximum number of threads per

process. Valid value range is 0 to

100,000. Must be non-zero to allow

use of ptthread_create.





Single or multiple

value

Read or

write Required?

erRacUOMVSuid

Unix uid assigned to this user. Valid

values are 0 to 2,147,483,647. Zero (0)

means superuser.’*’ means that the

UID will be automatically assigned.

Specific profiles for AUTOUID

support must be set up prior to its

usage.


erRacUIsOper

User has system Operations ability

(ability to read/modify any file).


erRacUIsOperSeg

Operparm segment is present.

Operparm information. Attributes

describe settings as a system

operator. Since this is an optional

object, its presence has meaning,

even if it contains no values for

attributes.


erRacUOpAltgrp

Alternate Console group used in

recovery.

Character 8 Single RW No

erRacUOpAuth

Console Authority. Valid values are:

v Master

v All

v Info

v Cons

v Io

v Sys


erRacUOpAuto

Whether or not the extended console

can receive messages which have

been automated by the MPF facility.


erRacUOpCmdsys

Console name or ’*’. A-Z, 0-9, @, #, $

are valid values, in addition to ’*’.


erRacUOpDom

Valid values are ’Normal’, ’All’, or

’None’.


erRacUOpKey

One to 8 character key to display

information from all consoles with

this key. Valid values are A-Z, 0-9, @,

#, $.





Single or multiple

value

Read or

write Required?

erRacUOpLevel

Level of information that can be

displayed. Valid values are:

v NB

v R

v CE

v E

v IN

v ALL

If ALL is specified, no others may be

specified.

Character 3 Multi RW No

erRacUOpLogcmd

Valid values are SYSTEM or NONE.


erRacUOpMform

Message form of the messages

displayed upon the extended

console. Valid values are:

v J

v M

v S

v T

v X

Character Bit Multi RW No

erRacUOpMigid

Whether or not a migration ID is to

be assigned to this extended console.


erRacUOpMonitor

Valid values are:

v JOBNAMES or JOBNAMEST

v SESS or SESST

v STATUS


erRacUOpMscope

Valid system names for which

messages can be received from. Valid

values are system names, ’*’ and

’*ALL’.


erRacUOpRoutCode

The Routing Codes this console is to

receive. Value range is 1 to 128.

Integer 3 Multi RW No

erRacUOpStor

Valid value range is 1 to 2000.


erRacUOpUD

Whether or not this console is to

receive undeliverable messages.


erRacUIsProtect

User may not be signed on to with a

password.





Single or multiple

value

Read or

write Required?

erRacUIsPrxSeg

PROXY segment is present.

PROXY segment information. This

object contains a name from the

LDAPBIND general resource profile

class, of the user as it is known to

the Enterprise Identity Mapping

environment. Since this is an





erRacUPrxBindDN

Bind DN of user on target host.

Binary 1023 Single RW No

erRacUPrxBindHst

A URL of a host, which the local

z/OS LDAP server will contact on

user’s behalf.

Binary 1023 Single RW No

erRacUPrxBindPW

Bind password for

erRacUPrxBindDN.


erRacUIsRestrict

User cannot be granted access

through UACC or ID(*) in resource

profiles.


erRacUIsSpecial

User has system Special. System

Security Administrator.


erRacUIsTSOSeg

TSO segment is present.

User TSO information. Since this is

an optional object, its presence

allows a user access to the

time-sharing environment, even if all

attribute values are null.


erRacUTSOAcct

Name of a user defined application.


erRacUTSOCmd

Initial command to be executed upon

connecting to TSO.


erRacUTSODest

Default destination for system

output. Must begin with A-Z, @#$,

remaining data may be numeric.


erRacUTSOHold

Default system output class for the

held queue. Must be alphanumeric.





Single or multiple

value

Read or

write Required?

erRacUTSOMsg

Default system output message class.

Must be alphanumeric.


erRacUTSOJob

Default system job execution class.



erRacUTSOMax

Maximum amount of storage user

may request. Amount is specified in

K bytes. Zero means no limit.


erRacUTSOProc

Default TSO logon procedure. Must

begin with A-Z, @#$, remaining data

may be numeric.


erRacUTSOSize

Requested amount of storage to be

used by this session. Zero means no

limit.


erRacUTSOSlbl

Default Security Label. See notes

about B1 support. Should probably

be excluded.


erRacUTSOSout

Default system output message class.



erRacUTSOUnit

Default allocation unit name.


erRacUTSOUdata

Hexadecimal value, defined by the

user installation. Typically, this is

unused.


erRacUIsUaudit

All user’s activity will be logged.


erRacUIsWASeg

Work attribute is present.

Work Attribute information. It

describes user location specifics. This

object is/was primarily created for

APPC/MVS. Since this is an optional

object, its presence has meaning,

even if it contains no values for

attributes.


erRacUWAAcct

Account number. This field only has

(real) meaning for APPC/MVS tasks.





Single or multiple

value

Read or

write Required?

erRacUWAAcct

Account number. This field only has

(real) meaning for APPC/MVS tasks.


erRacUWAAddr1

Address line 1.


erRacUWAAddr2

Address line 2.


erRacUWAAddr3

Address line 3.


erRacUWAAddr4

Address line 4.


erRacUWABldg

Building.


erRacUWADept

Department.


erRacUWAName

Name.


erRacUWARoom

Room.


erRacULogdate

Date user last signed on. Field is set

to current date if password has been

reset, or if the user’s account status

has been resumed.

Date Single R No

erRacULogtime

Time user last signed on. Field is set

to current time if password has been

reset, or if the user’s account status

has been resumed.

Time Single R No

erRacUModel

The name of a data set profile this

user may use as a model for creating

new data set profiles.


erRacUName

The name of the defined user. Value

is nullified by setting it to 20 pound

(#) signs:

####################


erRacUOwner

Name of existing user or group that

owns this user account.





Single or multiple

value

Read or

write Required?

erRacUPassdate

Date user is required to change

password. If 0, current password

must be changed upon initial use.

Date Single R No

erRacUPWInterval

Password interval. May be between 0

and 255. Zero means no password

interval. Maximum value imposed by

RACF system wide options.


erRacUPWNoExpire

Whether or not a password assigned

to this user is to be noted as ’not

expired’. Must be used in

conjunction with the ’erPassword’.

This has no meaning without a

password. This field have been

removed from the schema. It will

instead be an adapter option.


erRacUResumeDate

MM/DD/YY date field, indicates

future date when this account is to

be reactivated (RESUMEd).

Date 8 Single RW No

erRacURevokeDate



be inactivated (revoked).

Date 8 Single RW No

erRacUSeclabel

B1 Security Label. User’s default

security label.


erRacUSeclevel

B1 Security Level.


erRacUWhenDays

Days of the week a user may sign

on. Valid values are:

v SUNDAY

v MONDAY

v TUESDAY

v WEDNESDAY

v THURSDAY

v FRIDAY

v SATURDAY

v ANYDAY

String 9 Multi RW No

erRacUWhenTime

Time range when user may sign on

to the system.

Time 9 Single RW No

erUid

ID of user on RACF being created,

updated or deleted.



erRacConnect

This class represents a user’s connection to a group within RACF. The following

connect object is associated with the base user object, and must have at least 1, but

may have over 7,000 occurrences, but typically no more than 100. Varies upon

customer environment.



Single or multiple

value

Read or

write Required?

erRacConAuth

Group authority. Valid values are:

v USE

v CREATE

v CONNECT

v JOIN


erRacConCDate

Connect entry creation date.

Date 7 Single R No

erRacConCount

Connect count. Max value of 65,535.

Integer 5 Single R No

erRacConGroup

Name of group to which user is

connected.


erRacConIsADSP

User may or may not automatically

create discrete data set profiles.


erRacConIsAudit

User has system Auditor ability.


erRacConIsGrpac

Permits group level access of

UPDATE to the group under the

High Level Qualifier of any dataset

profile created through ADSP by this

user.


erRacConIsOper

User has system Operations ability

(ability to read/modify any file).


erRacConIsSpec

UUser has system Special. System

security Administrator.


erRacConLogdate

Date user last signed on, using this

group as default group or specified

group.

Date Single R No

erRacConLogtime

Time user last signed on, using this

group as default group or specified

group.

Time Single R No




Single or multiple

value

Read or

write Required?

erRacConOwner

Owner of this connect entry.


erRafConResumDt



be reactivated (RESUMEd).

Date 8 Single R No

erRacConRevokDt



be inactivated (revoked).

Date 8 Single R No

erRacConUACC

Default universal access to all data

set and TAPEVOL profiles created by

this user. Valid Values are:

v NONE

v READ

v UPDATE

v CONTROL

v ALTER


erRacConXML

This attribute will actually carry an

XML string that represents all the

data for a single connect entry. It will

carry all the information that

comprises a RACF connect entry.

This is due to the server flattening

out all the data elements.

String ??? Multi RW Yes

erRacGroup

This class represents a group definition within RACF. The RACF group represents

a group definition within the RACF database. Its presence is required to allow

Identity Manager to understand the RACF group tree structure, to know what

groups are within or outside of management policy. This information is read-only,

and is not managed nor updated by Identity Manager at this time. Although

optional segments are provided in this documentation, implementation of them is

to be decided later.



Single or multiple

value

Read or

write Required?

erRacGrpCDate

Creation date of this group.

Date 8 Single RW Yes

erRacGrpData

Installation data, user defined

purpose.


erRacGrpDFPAppl

DFP segment, DATAAPPL field.





Single or multiple

value

Read or

write Required?

erRacGrpDFPData

DFP segment, Data class.


erRacGrpDFPMgmt

DFP segment, management class.


erRacGrpDFPStor

DFP segment, storage class.


erRacGrpIsDFP

Indicates presence of DFP segment

information.


erRacGrpIsOMVS

Indicates presence of OMVS segment

information.


erRacGrpIsTME

Indicates presence of TME role

segment information.


erRacGrpIsUni

Indicates this is a Universal Group

(Unlimited number of users

connected).


erRacGrpName

Name of group to which user is

connected.


erRacGrpOMVSGid

OMVS Group ID. Valid values are 0

to 2,147,483,647.


erRacGrpOwner

Owner of this group.


erRacGrpSubgrp

Subordinate groups to this group.


erRacGrpSuper

Superior group to this group.


erRacGrpTMERole

Role groups that this group is part

of.


erRacGrpTUACC

Terminal Universal Access utilized or

not.



Appendix B. Registry settings

For the RACF adapter, the following table contains valid registry options, their

values and meanings.

Table 23. Registry settings and additional information

Option

attribute

Default value Valid values Function and meaning Required?

APPCCMD ITIMCMD 1 to 64 EBCDIC

characters, case

sensitive.

This is the APPC/MVS back end

command executor transaction name.

No

APPCRECO ITIMRECO 1 to 64 EBCDIC

characters, case

sensitive.

This is the APPC/MVS back end

reconciliation transaction name.

No

PASSEXPIRE TRUE TRUE, FALSE, or

TRUEADD

When defaulted, or set to TRUE, all

password changes executed are expired

passwords, requiring change upon next

logon.

If set to FALSE, all password changes will

be set to non-expired passwords.

When set to TRUEADD, a password for a

new user will be set to EXPIRED. A

password set on an existing user will be

set to non-EXPIRED.

In each case, READ or UPDATE access to

the FACILITY class profile,

IRR.PASSWORD.RESET will be required.

No

SCOPING None TRUE, FALSE If this registry attribute is not specified,

then the function of a scoped

reconciliation is based upon the presence

of a RACF ID specified on the service

form.

If there is an ID in the service form, a

scoped recon will be performed.

If it is left blank, a full recon will be

performed.

If this registry attribute is set to TRUE it

will always perform a scoped recon,

based upon the RACF ID the it is

executing as, either the specified

surrogate (from the service form) or the

adapter’s RACF ID.

If this registry attribute is set to FALSE it

will always perform a full recon,

irrespective of the RACF ID it is

executing as.

Yes


Table 23. Registry settings and additional information (continued)

Option

attribute

Default value Valid values Function and meaning Required?

APPCOLU None 1 to 8 EBCDIC

characters, case

sensitive, must be

upper case.

This is the originating APPC/MVS logical

unit, from which the adapter will

communicate.

No

APPCDLU None 1 to 8 EBCDIC

characters, case

sensitive, must be

upper case.

This is the destination APPC/MVS logical

unit, to which the adapter will

communicate. THIS LU MUST BE ON

THE SAME HOST AS THE ’APPCOLU’.

No

APPCMODE None 1 to 8 EBCDIC

characters, case

sensitive, must be

upper case.

This is the VTAM ’LOGMODE’ entry to

be utilized by the APPC connection. The

modetable utilized by the APPCOLU

logical unit must have this LOGMODE

entry defined within it.

No


Appendix C. Support information

This section describes the following options for obtaining support for IBM

products:

v “Searching knowledge bases”

v “Obtaining fixes” on page 110

v “Contacting IBM Software Support” on page 110

Searching knowledge bases

If you have a problem with your IBM software, you want it resolved quickly. Begin

by searching the available knowledge bases to determine whether the resolution to

your problem is already documented.

Search the information center on your local system or

network

IBM provides extensive documentation that can be installed on your local

computer or on an intranet server. You can use the search function of this

information center to query conceptual information, instructions for completing

tasks, reference information, and support documents.

Search the Internet

If you cannot find an answer to your question in the information center, search the

Internet for the latest, most complete information that might help you resolve your

problem. To locate Internet resources for your product, open one of the following

Web sites:

v IBM Tivoli Identity Manager Performance Tuning Guide

Provides information needed to tune Tivoli Identity Manager Server for a

production environment, available on the Web at:


Click the I character in the A-Z product list, and then, click the Tivoli Identity

Manager link. Browse the information center for the Technical Supplements

section.

v Redbooks and white papers are available on the Web at:

http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliIdentityManager.html

Browse to the Self Help section, in the Learn category, and click the Redbooks

link.

v Technotes are available on the Web at:


v Field guides are available on the Web at:


v For an extended list of other Tivoli Identity Manager resources, search the

following IBM developerWorks Web address:









Obtaining fixes

A product fix might be available to resolve your problem. You can determine what

fixes are available for your IBM software product by checking the product support

Web site:

1. Go to the IBM Software Support Web site

(http://www.ibm.com/software/support).

2. Under Products support pages A to Z, select the letter for your product name.

3. In the list of specific products, click IBM Tivoli Identity Manager.

4. Under Self help, you find a list of fixes, fix packs, and other service updates

for your product.

5. Click the name of a fix to read the description and optionally download the fix.

To receive weekly e-mail notifications about fixes and other news about IBM

products, follow these steps:

1. From the support page for any IBM product, click My support in the upper-left

corner of the page.

2. If you have already registered, skip to the next step. If you have not registered,

click register in the upper-right corner of the support page to establish your

user ID and password.

3. Sign in to My support.

4. On the My support page, click Edit profiles in the left navigation pane, and

scroll to Select Mail Preferences. Select a product family and check the

appropriate boxes for the type of information you want.

5. Click Submit.

6. For e-mail notification for other products, repeat Steps 4 and 5.

For more information about types of fixes, see the Software Support Handbook

(http://techsupport.services.ibm.com/guides/handbook.html).

Contacting IBM Software Support

IBM Software Support provides assistance with product defects.

Before contacting IBM Software Support, your company must have an active IBM

software maintenance contract, and you must be authorized to submit problems to

IBM. The type of software maintenance contract that you need depends on the

type of product you have:

v For IBM distributed software products (including, but not limited to, Tivoli,

Lotus, and Rational products, as well as DB2 and WebSphere products that run

on Windows or UNIX operating systems), enroll in Passport Advantage in one

of the following ways:

– Online: Go to the Passport Advantage Web page

(http://www.lotus.com/services/passport.nsf/WebDocs/

Passport_Advantage_Home) and click How to Enroll

– By phone: For the phone number to call in your country, go to the IBM

Software Support Web site

(http://techsupport.services.ibm.com/guides/contacts.html) and click the

name of your geographic region.v For IBM eServer software products (including, but not limited to, DB2 and

WebSphere products that run in zSeries, pSeries, and iSeries environments), you

can purchase a software maintenance agreement by working directly with an

IBM sales representative or an IBM Business Partner. For more information


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

http://techsupport.services.ibm.com/guides/handbook.html



http://techsupport.services.ibm.com/guides/contacts.html

about support for eServer software products, go to the IBM Technical Support

Advantage Web page (http://www.ibm.com/servers/eserver/techsupport.html).

If you are not sure what type of software maintenance contract you need, call

1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go to

the contacts page of the IBM Software Support Handbook on the Web

(http://techsupport.services.ibm.com/guides/contacts.html) and click the name of

your geographic region for phone numbers of people who provide support for

your location.

Follow the steps in this topic to contact IBM Software Support:

1. Determine the business impact of your problem.

2. Describe your problem and gather background information.

3. Submit your problem to IBM Software Support.

Determine the business impact of your problem

When you report a problem to IBM, you are asked to supply a severity level.

Therefore, you need to understand and assess the business impact of the problem

you are reporting. Use the following criteria:

Severity 1 Critical business impact: You are unable to use the program,

resulting in a critical impact on operations. This condition

requires an immediate solution.

Severity 2 Significant business impact: The program is usable but is

severely limited.

Severity 3 Some business impact: The program is usable with less

significant features (not critical to operations) unavailable.

Severity 4 Minimal business impact: The problem causes little impact on

operations, or a reasonable circumvention to the problem has

been implemented.

Describe your problem and gather background information

When explaining a problem to IBM, be as specific as possible. Include all relevant

background information so that IBM Software Support specialists can help you

solve the problem efficiently. To save time, know the answers to these questions:

v What software versions were you running when the problem occurred?

v Do you have logs, traces, and messages that are related to the problem

symptoms? IBM Software Support is likely to ask for this information.

v Can the problem be re-created? If so, what steps led to the failure?

v Have any changes been made to the system? (For example, hardware, operating

system, networking software, and so on.)

v Are you currently using a workaround for this problem? If so, please be

prepared to explain it when you report the problem.

Submit your problem to IBM Software Support

You can submit your problem in one of two ways:

v Online: Go to the ″Submit and track problems″ page on the IBM Software

Support site (http://www.ibm.com/software/support/probsub.html). Enter

your information into the appropriate problem submission tool.

Appendix C. Support information 111

http://www.ibm.com/servers/eserver/techsupport.html


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

v By phone: For the phone number to call in your country, go to the contacts page

of the IBM Software Support Handbook on the Web

(http://techsupport.services.ibm.com/guides/contacts.html) and click the name

of your geographic region.

If the problem you submit is for a software defect or for missing or inaccurate

documentation, IBM Software Support creates an Authorized Program Analysis

Report (APAR). The APAR describes the problem in detail. Whenever possible,

IBM Software Support provides a workaround for you to implement until the

APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the

IBM product support Web pages daily, so that other users who experience the

same problem can benefit from the same resolutions.

For more information about problem resolution, see Searching knowledge bases

and Obtaining fixes.



Appendix D. 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 in

other countries. Consult your local IBM representative for information on the

products and services currently available in your area. Any reference to an IBM

product, program, or service is not intended to state or imply that only that IBM

product, program, or service may be used. Any functionally equivalent product,

program, or service that does not infringe any IBM intellectual property right may

be used instead. However, it is the user’s responsibility to evaluate and verify the

operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter

described in this document. The furnishing of this document does not give you

any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS

FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or

implied warranties in certain transactions, therefore, this statement may not apply

to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be

incorporated in new editions of the publication. IBM may make improvements

and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for

convenience only and do not in any manner serve as an endorsement of those Web

sites. The materials at those Web sites are not part of the materials for this IBM

product 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 it

believes appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created

programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged should contact:

IBM Corporation

2ZA4/101

11400 Burnet Road

Austin, 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 information and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement, or any equivalent agreement

between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may

vary significantly. Some measurements may have been made on development-level

systems and there is no guarantee that these measurements will be the same on

generally available systems. Furthermore, some measurements may have been

estimated through extrapolation. Actual results may vary. Users of this document

should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of

performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the

suppliers of those products.

Trademarks

The following terms are trademarks or registered trademarks of International

Business Machines Corporation in the United States, other countries, or both:

IBM

IBM logo

AIX

DB2

Novell

SecureWay

Tivoli

Tivoli logo

Universal Database

WebSphere

Lotus is a registered trademark of Lotus Development Corporation and/or IBM

Corporation.

Domino is a trademark of International Business Machines Corporation and Lotus

Development Corporation in the United States, other countries, or both.


Microsoft, Windows, Windows NT, and the Windows logo are trademarks of

Microsoft Corporation in the United States, other countries, or both.

Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation

in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other

countries.

Linux is a trademark of Linus Torvalds in the U.S., other countries, or both.

Sun, Sun Microsystems, and the Sun Logo are trademarks or registered trademarks

of Sun Microsystems, Inc. in the United States and other countries.

Java and all Java-based trademarks are trademarks of Sun

Microsystems, Inc. in the United States, other countries, or

both.

Other company, product, and service names may be trademarks or service marks

of others.

Appendix D. Notices 115


Index

Aaccessibility

pdf format, for screen-reader software ix

statement for documentation ix

text, alternative for document images ix

activity logging 61

adapterprofile purpose 35

adapter attributes 91, 104, 105

adapter form attributes 91

agentCfgarguments 68

changing adapter parametersconfiguration key 61

protocol settings 41

registry settings 63

request processing 64

menusactivity logging 61

advanced settings 65

event notification 44

help 68

Main Configuration 39

registry 63

viewing configuration settings 40

Bbooks

see publications ix

Ccertificate authority

definition 71

certificate signing request (CSR) 80

certificatesCA

available functions 78

deleting 81

installing 81

viewing installed 81

certificate management toolsSee CertTool

definition 71

examplescertificate signing request (CSR) 80

install 80

installationfrom file 80

sample 80

key formats 73

overview 71

private keys and digital certificates 72

protocol configuration toolSee CertTool

register 78

registeredregistering 82

removing 82

certificates (continued)registered (continued)

viewing 82

request 79

self-signed 72

viewinginstalled 81

registered 82


viewing registered 82

CertToolCA certificate

deleting 81

installing 81

viewing 81

certificateinstall 80

register 78

request 79


viewing registered 82

changing adapter parametersaccessing 73, 77

options 78

client authentication 78

install certificate 80

private key, generating 79

registered certificateregistering 82

removing 82

viewing 82

character sets, supported 65

client authentication 75

client validation, SSL 76

configurationkey

changing with agentCfg 61

default value 39, 61

purpose 39

settingschanging with agentCfg 39

default value 40

viewing with agentCfg 40

SSL 74

contextbaseline database 61

deleting 52

listing 52

modifying 59

target DN 60

conventionsHOME directory

Tivoli_Common_Directory xii

DB_INSTANCE_HOME x

HTTP_HOME xi

ITIM_HOME xii

LDAP_HOME xi

WAS_HOME xii

WAS_MQ_HOME xii

WAS_NDM_HOME xii

typeface ix


conventions (continued)UNIX variable, directory notation x

used in this document ix

CSRdefinition 79

file, generating 79

customer supportsee Software Support 110

DDAML protocol

configuring with agentCfg 41

encryptiondefault value 42

type 42

options 42

properties, changing with agentCfgoptions 42

password 42

portnumber 42

require_cert_reg 44

srv_nodename 43

srv_portnumber 43

username 42

validate_client_ce 43

SSL authentication 73

DB_INSTANCE_HOMEDB2 UDB installation directory x

definition x

debug logdefault value 62

enable/disable with agentCfg 61

purpose 63

detail logdefault value 62

enable/disable with agentCfg 61

purpose 63

directoryDB_INSTANCE_HOME x

HTTP_HOME xi

installationDB2 UDB x

IBM Directory Server xi

IBM HTTP Server xi

WebSphere Application Server base product xii

WebSphere Application Server Network Deployment

product xii

WebSphere MQ xii

installation for Sun ONE Directory Server xi

ITIM_HOME xii

LDAP_HOME xi

names, UNIX notation x

WAS_HOME xii

WAS_MQ_HOME xii

WAS_NDM_HOME xii

disabilities, using documentation ix

documentsrelated viii

Tivoli Identity Manager library v

Eenable/disable with agentCfg 61

encrypted registry settings 63

encryptionDAML protocol

default value 42

type 42

SSL 71, 72

environment variableUNIX notation x

event notificationcache size 52

changing with agentCfg 44

contextbaseline database 61

deleting 52

listing 52

modifying 59

search attributes 60

target DN 60

enable/disable 51

reconciliationattributes 52

context 52

intervals 52

modifying 52

process priority 52

starting manually 52

Ffixes, obtaining 110

Hhelp menu for agentCfg 68

accessing with -help command 68

home directoriesDB_INSTANCE_HOME x

HTTP_HOME xi

ITIM_HOME xii

LDAP_HOME xi

WAS_HOME xii

WAS_MQ_HOME xii

WAS_NDM_HOME xii

HTTP_HOMEdefinition xi

IBM HTTP Server installation directory xi

Iimport

adapter profile 34

PKCS12 file 73

information centers, searching to find software problem

resolution 109

installationcertificate 80

directoryDB2 UDB x

IBM Directory Server xi

IBM HTTP Server xi

Sun ONE Directory Server xi

WebSphere Application Server base product xii


product xii

WebSphere MQ xii

profile 34


installation prerequisitesnetwork connectivity 9

operating system 9

server communication 9

Tivoli Identity Manager Server 9

Internet, searching to find software problem resolution 109,

110

ITIM_HOMEdefinition xii

directory xii

Kknowledge bases, searching to find software problem

resolution 109

LLDAP_HOME

definition xi

IBM Directory Server installation directory xi

Sun ONE Directory Server installation directory xi

logsactivity settings, changing 40

debug 61

detail 61

directory, changing with agentCfg 62

display using agentCfg 69

enable/disable, changing with agentCfg 62

file name, changing with agentCfg 61

settings, changing with adapterCfg 62

settings, changing with agentCfglog file name 62

max file size 62

settings, default values 61

trace.log file 35

view events 40

viewing statistics 66

Mmanuals

see publications ix

Nnetwork connectivity prerequisites 9

non-encrypted registry settings 63, 64

Oonline publications

accessing ix

operating system prerequisites 9

Ppassword protected file

See PKCS12 file

passwordschanging configuration key 61

configuration key, default value 39, 61

passwords, changing with agentCfgDAML protocol 42

path names, notation x

pdf format, for screen-reader software ix

PKCS12 filecertificate and key installation 80

export certificate and key 82

portnumberchanging with agentCfg 42

portnumber, changing with agentCfg 42

private keydefinition 71

private key, generating 79

problem determinationdescribing problem for IBM Software Support 111

determining business impact for IBM Software

Support 111

submitting problem to IBM Software Support 111

properties, changing with agentCfg 42

protocolDAML

configuring with agentCfg 41

encryption default value 42

encryption type 42

properties, changing with agentCfg 42

SSLoverview 71

server-to-adapter configuration 74

two-way configuration 75, 76

public key 72

publicationsaccessing online ix

related viii

Tivoli Identity Manager library v

Rreconciliation

attributes 52

context 52

intervals 52

modifying 52

process priority 52

registry settingsencrypted 63

non-encrypted 63, 64

require_cert_reg, changing with agentCfg 44

Sself-signed certificate 72

server communication prerequisites 9

Software Supportcontacting 110

describing problem for IBM Software Support 111

determining business impact for IBM Software

Support 111

submitting problem to IBM Software Support 111

srv_nodename, changing with agentCfg 43

srv_portnumber, changing with agentCfg 43

SSLcertificate installation 71

certificate signing request 79

encryption 71

key formats 73

overview 71

private keys and digital certificates 72

self-signed certificates 72

Index 119

SSL (continued)server-to-adapter configuration 74

two-way configuration 75, 76

SSL implementations, DAML protocol 73

Ttext, alternative for document images ix

thread count settingschanging with agentCfg 64

default values 64

maximum concurrent requests 64

reconciliation requests 65

system login add requests 65

system login change requests 65

system login delete requests 65

Tivoli Identity Manager Adaptercommunication with the server 75, 76

SSL communication 75, 76

Tivoli Identity Manager Servercommunication with the adapter 74

importing adapter profile 34

SSL communication 74

Tivoli Identity Manager Server prerequisites 9

Tivoli software information center ix

Tivoli_Common_Directorydefinition xii

trace.log file 35

two-way configurationSSL

client 75

client and server 76

typeface conventions ix

Uupgrade

adapter profile 35

username, changing with agentCfg 42

UTF8 support 65

Vvalidate_client_ce, changing with agentCfg 43

WWAS_HOME

definition xii

WebSphere Application Server base installation

directory xii

WAS_MQ_HOMEdefinition xii

WebSphere MQ installation directory xii

WAS_NDM_HOMEdefinition xii


installation directory xii

western European character set, support 65


��

Printed in USA

SC32-1490-08

Documents

T l Identity Manager - IBMpublib.boulder.ibm.com/tividd/td/ITIM/SC32-1490-08/en_US/PDF/racf... · ® Identity Manager RACF Adapter Installation and Configuration Guide ... Identity