3 Connector Deployment on IBM RACF

You must install the Reconciliation Agent and Provisioning Agent components of the IBM RACF Advanced connector on the mainframe.

The following section summarizes the procedure:

• Summary of the Deployment Procedure

The following sections describe each deployment step in detail:

1. Verifying Deployment Requirements

2. Uploading the Components of the Reconciliation Agent and Provisioning Agent

3. Modifying the prclib.xmi and parmlib.xmi Files

4. Configuring the Started Tasks

5. Integrating the Exits for the Reconciliation Agent with the Target System Exits

6. Creating an IBM RACF Account

7. Starting Up and Shutting Down the Reconciliation Agent and Provisioning Agent

Summary of the Deployment Procedure

The following steps summarize the procedure to deploy the connector components on the target system:

1. Verify the deployment requirements.

2. Upload the components of the Reconciliation Agent and Provisioning Agent.

3. Modify the prclib.xmi and parmlib.xmi files according to the settings of your target system installation.

4. Configure the started tasks.

5. Integrate the connector exits with the target system exits.

6. Create an IBM RACF account for reconciliation and provisioning operations.

7. Test the setup by starting up and shutting down the Reconciliation Agent and Provisioning Agent.

Verifying Deployment Requirements

Both the Reconciliation Agent and Provisioning Agent need a started task and service account that has the privileges required to run IBM RACF system commands on the mainframe system.

In addition, these agents function under a user account on the mainframe system. This user account must be created by the systems programmer before you deploy the agents.

Note:

Both the Reconciliation Agent and Provisioning Agent user accounts must be placed into an administrative APF-authorized library. These user accounts must have at least the permissions of the SystemAdministrators group on the mainframe. These user accounts have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges.

Environmental Settings and Requirements

Ensure that the following requirements are met on the mainframe:

• The Reconciliation Agent and Provisioning Agent each use memory subpools to manage peak load conditions. These subpools require 1.5 to 2.0 MB of mainframe memory for operations. You configure this while installing the Reconciliation Agent and Provisioning Agent.

• In addition to the program itself, the user account that a program runs under must also have authorization to access subpools on the host platform. This must be configured by the systems programmer.

• Because TCP/IP is used in the message transport layer, an administrator must have authorization to create ports on the mainframe and provide security authorizations.

• The Reconciliation Agent operates by using user exit technology, outside the mainframe operating system. This means it runs on a different LPAR from the operating system.

  Maintaining a specific password format is an example of the objective for which you use custom exits. Oracle Identity Manager exits are engineered to be the last exits called in sequence, allowing existing exits to function normally. After modifying exits within an LPAR, an initial program load (IPL) of the LPAR may be required.

  Note:

  As the systems programmer, you must do an IPL after a system component is changed or modified.

Uploading the Components of the Reconciliation Agent and Provisioning Agent

Perform the following steps to upload the components of the Reconciliation Agent and Provisioning Agent:

1. Extract the contents of the following file from the installation media to a temporary directory on any computer:

   etc/Provisioning and Reconciliation Connector/Mainframe_RACF.zip
   

2. Transmit or FTP the jcl.xmi and linklib.xmi files to the mainframe, each with the following specifications: RECFM=FB, LRECL=80, BLKSIZE=3120, and DSORG=PS.

3. Log in to the TSO environment of the mainframe.

4. Expand the CNTL data sets, and then run the following command from the ISPF command line:

   TSO RECEIVE INDA('IDF.CNTL.XMIT')
   

5. When prompted to specify restore parameters, enter:

   DA('IDF.CNTL')
   

   Note:

   DA is a parameter of the Restore command. It means Dataset.

6. To expand the LINKLIB data set, run the following command from the ISPF command line:

   TSO RECEIVE INDA('IDF.LINKLIB.XMIT')
   

7. When prompted to enter restore parameters, enter:

   DA('IDF.LINKLIB')
   

8. Perform Steps 4 through 7 for the prclib.xmi and parmlib.xmi files included in the Mainframe_RACF.zip file.

9. Copy LOGPWX01 and LOGRIX02 to the LPA load library contained within the appropriate IEASYSxx member of SYS1.PARMLIB.

Modifying the prclib.xmi and parmlib.xmi Files

After you upload the prclib.xmi and parmlib.xmi files, edit the contents of the files so that the values of parameters in the file match the settings of your target system installation.

The following z/OS libraries are used by the connector:

• Library = IDF.LINKLIB

  This library contains executable modules for the Provisioning (Pioneer) and Reconciliation (Voyager) Agents and various utility programs required for their operation.

• Library = IDF.PROCLIB

  This library contains STC procedures for Pioneer and Voyager. There are four members in this library:

  Pioneerx: Provisioning Agent

  Voyager: Reconciliation Agent

  Startup: Procedure to create Subpool 231 to capture events for Voyager

  Wrapup: Procedure to delete the Startup created subpool

• Library = IDF.PARMLIB

  This library contains the following members:

  PROG01: Dynamic APF authorization member for IDF.LINKLIB

  PROG76: Dynamic EXIT member for Activation of IRREVX01

  PROG77: Dynamic EXIT member for deactivation of IRREVX01

Configuring the Started Tasks

There are two different STCs (Started Task procedures) to set up and run the Reconciliation Agent and Provisioning Agent. There is a STC procedure member for each agent. RUNPIONX and RUNVOYAX are samples for you to set up the started tasks.

The parameters for RUNPIONX are:

• TCPN: The name of the TCP STC on z/OS

• IPAD: The value must always be 0.0.0.0.

• PORT: The incoming connection port for the Provisioning Agent must match the value given in the LDAP gateway properties file.

• DEBUG: The debug switch for showing diagnostic output

The parameters for RUNVOYAX are:

• TCPN: The name of the TCP STC on z/OS

• IPAD: The destination IP Address of the LDAP gateway

• PORT: The outgoing connection port for the Reconciliation Agent for the LDAP gateway

• DEBUG: The debug switch for showing diagnostic output

The source code for each program is as follows:

For RUNPIONX:

//PIONEER  EXEC PGM=PIONEERX,REGION=0M,TIME=1440, 
        //    PARM=('TCPN=TCPIP', 
        //          'IPAD=0.0.0.0', 
        //          'PORT=5799', 
        //          'DEBUG=Y', 
        //          'ESIZE=16', 
        //          'LPAR=ORACLE-T', 
        //          'JWAIT=10') 
        //STEPLIB  DD DISP=SHR,DSN=IDF.LINKLIB                    (1) 
        //* EPLIB  DD DISP=SHR,DSN=IDF.PROD.LINKLIB
        //         DD DISP=SHR,DSN=TCPIP.SEZATCP
        //* BATJINFO DD DISP=SHR,DSN=ADCDM.BATJCARD               (2)
        //* VSAMGETU DD DISP=SHR,DSN=ADCDM.SWUSERS                (3)
        //* VSAMGETO DD DISP=SHR,DSN=ADCDM.BATJCOUT               (4)
        //DEBUGOUT  DD SYSOUT=*                                   (5)
        //SYSPUNCH DD SYSOUT=(*,INTRDR) 
        //SYSPRINT DD SYSOUT=X 
        //SYSUDUMP DD SYSOUT=X
        //

An explanation of some of the lines in the preceding block:

• (1) In this example, Pioneer is using a STEPLIB.

• (2) , (3) , (4) these can be commented out. They are used only for ACF2 installations.

• (5) The new DEBUG out data definition statement.

For RUNVOYAX:

//VOYAGER JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//STEP1    EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,
//  PARM=('TCPN=TCPIP',
//    'IPAD=LDAP_GATEWAY_IP_ADDRESS',
//    'PORT=5190',
//    'DEBUG=Y',
//    'ESIZE=16',
//    'DELAY=00',
//    'STARTDELAY=10',
//    'PRTNCODE=SHUTRC')
//STEPLIB  DD  DSN=IDF.LINKLIB,DISP=SHR
//CACHESAV DD  DSN=ADCDM.CACHESAV,DISP=SHR
//DEBUGOUT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*

Integrating the Exits for the Reconciliation Agent with the Target System Exits

Note:

Before you perform this procedure, ensure that earlier versions of the reconciliation exits are not present.

Because two of the exit modules, ICHPWX01 and ICHRIX02, are in the z/OS Load Library that resides in the LPA, an IPL is required to complete the installation. The third exit, IRREVX01(LOGREVX01), resides in a z/OS Link List load library. This depends on whether the z/OS Load Library is added to the LinkList. To allow the LDAP Gateway to fully capture events, the Reconciliation Agent and its exits must be installed on each LPAR that shares the authentication repository.

To install the Reconciliation Agent exits:

Note:

In the console commands given in the following steps, XX is the PROG suffix for the member in SYS1.PARMLIB, which is one of the libraries that are used to start up the mainframe.

1. Install LOGEVX01, the Common Command exit, by using the Dynamic Exit Facility. The LOGRIX02, LOGOWX01 and LOGEVX01 are standard Assembler-language exits for manipulation or capture of IBM RACF data.

   See Also:

   IBM Security Server documentation for more information about the LOGRIX02, LOGOWX01, and LOGEVX01 exits

2. For testing, it is recommended that you set up one or more PROGxx members for dynamic activation of exits in SYS1.PARMLIB (or equivalent), to allow for easy removal of the exit, if required.

3. In SYS1.PARMLIB, create a member containing the following Dynamic Exit definitions:

   EXIT ADD EXITNAME(IRREVX01) MODULE(LOGEVX01)
   

4. From the distribution Load Library, copy LOGRIX02 as ICHRIX02 and LOGOWX01 as ICHPWX01 into a user LPA library defined in the sys1.parmlib – IEASYSxx member (LPALSTxx). A z/OS IPL is required to activate these exits.

5. IPL z/OS with the new LPA library contained within the LPALSTxx member of SYS1.PARMLIB.

   An entry similar to the following is logged when the target system finds and activates connector exits:

   0090  ICH508I ACTIVE RACF EXITS: ICHRIX02 ICHPWX01
   

6. Activate LOGEVX01 as an IRREVX01 exit point by running the console command SET PROG=XX. IRREVX01 is the only dynamically activated exit.

7. Use Startup or VOYINIT to build subpool 231. Verify that the job ends with the MVS condition code 0000.

Loading Exits

If the command exit IRREVX01 is contained in a Link List library and was activated through a z/OS SET command, then the LLA (Library Lookaside Area) must be refreshed, either using ISPF through SDSF or the z/OS master console:

/F LLA,REFRESH

Verifying Exit Installation

From the z/OS master console or ISPF - SDSF, enter the following command to verify that the load library where the product is installed is APF authorized:

/D PROG,APF

By default, if the installation load library is in the linklist, then it is APF authorized. You can determine whether or not the installation load library is in the linklist at IPL time by running the following command from the IPL library:

SYS1.PARMLIB, member = IEASYSxx

Here, xx is a user suffix for a z/OS startup member in SYS1.PARMIB.

Verifying That the Exits Are Loaded

The following are commands to verify that the exits are loaded and sample output for these commands:

0290  D PROG,LPA,MODNAME=ICHPWX01
0090  CSV550I 10.07.56 LPA DISPLAY 702
0090  FLAGS  MODULE    ENTRY PT  LOAD PT   LENGTH    DIAG
0090     P   ICHPWX01  83A56730  03A56730  00000228  11AF5B80
 
 
0290  D PROG,LPA,MODNAME=ICHRIX02
0090  CSV550I 10.08.54 LPA DISPLAY 704
0090  FLAGS  MODULE    ENTRY PT  LOAD PT   LENGTH    DIAG
0090     P   ICHRIX02  8318EAE0  0318EAE0  00000228  11AFD420
 
D PROG,EXIT,EXITNAME=IRREVX01
CSV461I 14.46.59 PROG,EXIT DISPLAY 414
EXIT             MODULE   STATE MODULE   STATE MODULE   STATE
IRREVX01         LOGEVX01   A

Uninstalling the Exits

If you want to uninstall the Reconciliation Agent exits, then use one of the following methods:

• For the command exit, IRREVX01, run the SET PROG=XX console command. In this command, replace XX with the PROG suffix for the exit (member) in SYS1.PARMLIB.

• For ICHPWX01 and ICHRIX02, delete modules from the LPA library where they are installed. Alternatively, you can create and use two LPA libraries, one each for production and for testing purposes. The correct IEASYSxx suffix can be pointed to the appropriate LPA library. After you delete the exits, a z/OS IPL is required.

• Run the following command:

  EXIT DELETE EXITNAME(IRREVX01) MODULE(LOGEVX01)
  

Creating an IBM RACF Account

The connector uses a target system account for reconciliation and provisioning operations performed on the target system. To create this target system account:

1. Create a RACF user account similar to the following:

   ADDUSER START2 DFLTGRP(xxxx) PASSWORD(yyyyyyyy)

   ALTUSER START2 SPECIAL OPERATIONS

2. Build the following RACF permissions:

   RDEFINE FACILITY IRR.RADMIN.* UACC(NONE)

   PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(START2) ACCESS(READ)

   PERMIT BPX.DAEMON CLASS(FACILITY) ID(START2) ACCESS(READ)

3. Refresh the RACLIST as follows:

   SETROPTS RACLIST(FACILITY) REFRESH

Starting Up and Shutting Down the Reconciliation Agent and Provisioning Agent

Note:

Both agents use the standard CICS Socket Interface EZASOKET. The errors returned from various calls are documented in z/OS V1R9.0 Communications Server IP CICS Sockets Guide.

To start up the Reconciliation Agent and Provisioning Agent:

1. z/OS IPLs.

2. RACF is started and the ICHPWX01 and ICHRIX02 exits are activated from the LPA.

3. JES2 is started.

4. TCP/IP and other communications-related STCs are started.

5. The VOYINIT or STARTUP procedure is executed to establish the subpool used to capture RACF events.

6. You verify that the LDAP Gateway properties have been changed to match Voyager and Pioneer properties.

7. To start Voyager, run the S VOYAGER command from the z/OS operator's console or SDSF in TSO.

8. To start Pioneer, run the S PIONEER command from the z/OS operator's console or SDSF in TSO.

To shut down the Reconciliation Agent and Provisioning Agent:

To shut down the Reconciliation Agent, run the F VOYAGER,SHUTDOWN command from the z/OS Operator's console or TSO/ISPF issue.

To shut down the Provisioning Agent, run the F PIONEER,SHUTDOWN command from the z/OS Operator's console or TSO/ISPF issue.