| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.3 Part Number B32378-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.3 Part Number B32378-01 |
|
|
View PDF |
The Provisioning and Reconciliation Agent Components of the IBM RACF Advanced Connector are installed on the mainframe. This chapter describes the installation and configuration of the Provisioning Agent and Reconciliation Agent in the following sections:
The following table identifies hardware, software, and authorization prerequisites for the installing Provisioning Agent and Reconciliation Agent.
The Provisioning Agent and the Reconciliation Agent are installed on the mainframe. Both require the installation of a started task. In addition, these agents function under a user account on the mainframe system. This user account must be created by the mainframe administrator during the deployment of the Provisioning Agent and the Reconciliation Agent.
Note:
Both the Provisioning Agent and Reconciliation Agent user accounts require placement 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.To deploy the IBM RACF Advanced Connector, ensure that the following requirements are met on the mainframe:
Each agent uses memory subpools to manage peak load conditions. These subpools require 1.5 to 2.0 MB of mainframe memory for operations. This is configured at the time of Provisioning Agent and Reconciliation Agent installation.
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 done by the mainframe administrator.
If MQ Series is used for the message transport layer, an MQ administrator will be needed to authorize the creation of MQ queues from an automated script that comes with the connector.
Oracle Identity Manager requires three queues: a send queue, a receive queue, and a communication queue for the Reconciliation Agent. The MQ administrator creates these queues and typically names them according to the naming conventions used in the system. These names are automatically inserted into the Provisioning Agent and Reconciliation Agent start up Job Control Language (JCL) program.
If TCP/IP is used in the message transport layer, an administrator must have authorization to create ports on the mainframe, as well as provide security authorizations.
The Reconciliation Agent operates using user exit technology, outside the mainframe operating system. This means it runs in a different LPAR from the operating system.
Typical mainframe shops install custom exits, for example to maintain a certain password format. Oracle Identity Manager exits are engineered to be the last exits called in sequence, allowing existing exits to function normally. After modifying exits within a logical partition (LPAR), an initial program load (IPL) of the LPAR may be required.
These are the initial steps for installing the components of the IBM RACF Advanced connector on z/OS.
Transmit or FTP JCL.XMIT and LINKLIB.XMIT to the z/OS server, each with the following specifications: RECFM=FB, LRECL=80, BLKSIZE=3120, and DSORG=PS.
Log in to the z/OS server's TSO environment.
Expand the CNTL data sets, issue the following command from the ISPF command line:
TSO RECEIVE INDA('IDF.CNTL.XMIT')
When prompted to specify restore parameters, enter:
DA('IDF.CNTL')
To expand the LINKLIB data set, enter the following command on the ISPF command line:
TSO RECEIVE INDA('IDF.LINKLIB.XMIT')
When prompted to enter restore parameters, enter:
DA('IDF.LINKLIB')
To complete the installation, follow the procedures in IDF.CNTL member #INSTVOY for the Reconciliation Agent components, and member #INSTPIO for the Provisioning Agent component.
Because the exits reside in LPARs, an IPL is required to complete the installation. To allow the LDAP Gateway to fully capture events, the Reconciliation Agent and its exits should be installed on each LPAR that shares the IBM RACF authentication repository.
To install the Reconciliation Agent exits:
Install LOGRIX02, LOGPWX01, and LOGEVX01, the Common Command exits, using the Dynamic Exit Facility.
For testing, it is recommended that you set up one or more PROGxx members in SYS1.PARMLIB (or equivalent), to allow for easy removal of the exit if desired.
The following commands comprise the PARMLIB list. These commands can also be added with operator console commands. The following sample command is used to append the Reconciliation Agent exits to the appropriate IBM RACF exits.
EXIT ADD EXITNAME(ICHRIX02) MODULE(LOGRIX02) EXIT ADD EXITNAME(ICHPWX01) MODULE(LOGPWX01) EXIT ADD EXITNAME(IRREVX01) MODULE(LOGEVX01)
Copy these three members to your system PARMLIB data set.
If you already have a PROGAD or PROGDL member, rename the LOG members to a PROGxx name that is not in use.
When ready, use the console command SET PROG=XX to activate LOGPWX01 as an ICHPWX01 exit point.
When Ready, use the console command SET PROG=XX to activate LOGRIX02 as an ICHRIX02 exit point.
When ready, use the console command SET PROG=XX to activate LOGEVX01 as an IRREVX01 exit point.
For permanent installation, do one of the following:
Add the EXIT ADD statement in PROGAD to your production PROGxx PARMLIB member.
Add a SET PROG=XX command to CONSOL00 or an automation script, so that it is issued during your IPL procedure.
Install ICHRIX02, the RACROUTE REQUEST=VERIFY(X) (RACINIT) post processing exit.
Note:
If you do not have an existingICHRIX02 exit, run the job in the samples library member RIX0A. This job uses SMP/E to linkedit LDXRIX02 into SYS1.LPALIB as exit ICHRIX02.To load the exits:
Command done from the Operator Log (ISPF menu option SDSF then option LOG)
/F LLA,REFRESH /T PROG=XX Where XX is the Parmlib list name created EX. PROG75 /T PROG=75
To look at the exits:
/D PROG,LPA,MODNAME=ICHPWX01 /D PROG,LPA,MODNAME=ICHRIX02 /D PROG,LPA,MODNAME=IRREVX01
Sample output of the display command:
15:47:38 D PROG,LPA,MODNAME=ICHPWX01 15:47:38 CSV550I 15.47.38 LPA DISPLAY 321 15:47:38 FLAGS MODULE ENTRY PT LOAD PT LENGTH DIAG 15:47:38 P ICHPWX01 85024C68 05024C68 00000398 0DA015F8 15:47:38 D PROG,LPA,MODNAME=ICHPWX01 15:47:38 CSV550I 15.47.38 LPA DISPLAY 321 15:47:38 FLAGS MODULE ENTRY PT LOAD PT LENGTH DIAG 15:47:38 P ICHPWX01 85024C68 05024C68 00000398 0DA015F8
If you need to uninstall the Reconciliation Agent exits, enter SET PROG=XY as a console command or enter the following commands.
EXIT DELETE EXITNAME(ICHRIX02) MODULE(LOGRIX02) EXIT DELETE EXITNAME(ICHPWX01) MODULE(LOGPWX01) EXIT DELETE EXITNAME(IRREVX01) MODULE(LOGEVX01)
This section describes the following Message Transport Layer configuration tasks for both TCP/IP and MQ Series:
This section describes configuring TCP/IP as the message transport layer for the IBM RACF Advanced connector on the z/OS system. The rules for using TCP/IP are beyond the scope of this document, but affect the startup and communication sequences. The goal is to establish a stateful connection, allowing the pooling of messages and significantly reducing the load on both the mainframe and the LDAP Gateway server.
Start up the Oracle Identity Manager LDAP Gateway. This must be previously configured to connect to the mainframe using a given IP address and port number.
Start the Provisioning Agent started task, which is also preset to establish the TCP/IP connection to the LDAP Gateway on a specified IP address and port number.
The same procedure applies to the Reconciliation Agent. Start the LDAP Gateway, and then initiate the Reconciliation Agent started task.
To use TCP/IP for the message transport layer, you will need the following IP addresses:
IP address to be used by z/OS
IP address for the router
IP addresses for domain name servers
For using TCP/IP as the message transport layer, you might need the help of a mainframe administrator to allow for the creation of ports on the mainframe, as well as providing security authorizations for the data structures.
To edit the Provisioning Agent and Reconciliation Agent JCL:
Insert an installation-approved job card.
Change the value for PARM =('TCPN=TCPIP' to the name of the running TCP/IP started task).
Change the IP address to the address of the LPAR (z/OS System that Provisioning Agent will be started from).
Change the port number to the port assigned in the LPAR (z/OS System that Provisioning Agent will be started from).
If your installation requires batch feeds then insert the proper VSAMGETU statement. The following code shows the batch loading of IBM RACF ACIDs:
//USR98S01 JOB (,xxxxxxxx,,'PROVISIONING AGENT UPLOAD PROCESS FOR ACIDS'),
// 'UPLOAD CATS TO XELLTE',
// REGION=2M,CLASS=6,MSGCLASS=Q,
// USER=XXXXXXXX,TIME=1440,
// NOTIFY=&SYSUID,TYPRUN=HOLD
//*
/*ROUTE PRINT CLE
//*
//PIONEERX EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=Host IP Address of the IBM RACF System',
// 'PORT=6500',
// 'DEBUG=Y')
//STEPLIB DD DISP=SHR,DSN=PPRD.IDF.LINKLIB
// DD DISP=SHR,DSN=SYS2.TCPACCES.V60.LINK
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSDBOUT DD SYSOUT=*
//SYSABOUT DD SYSOUT=*
//ABENDAID DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VSAMGETU DD DISP=SHR,DSN=LXT99S.FEEDFILE.SORTED
//*
For the Reconciliation Agent, the Job Control is the same with the exception of the execute card, which is shown here:
//VOYAGERX EXEC PGM=VOYAGERX,
// PARM=('TCPN=TCPIP',
// 'IPAD=Host IP Address of the IBM RACF System',
// 'PORT=5791',
// 'DEBUG=Y')
For both Reconciliation Agent and Provisioning Agent the following DEBUG parameter field equivalents can be used:
* VALID DEBUG PARMS ARE: N, Y, Z* N IS FOR NO DEBUGGING OUTPUT* Y IS FOR DEBUGGING OUTPUT* Z IS FOR DEBUGGING OUTPUT, BUT DO NOT WRITE TO MQ.
Note:
If you get the "data set in use" message when attempting to edit a member, use the F1 key to see the member in question that you are trying to edit. You will have to press the F1 key twice. The second time will actually give the name of the job using the file that you are trying to edit. You can then go to the z/OS console and remove it by using the p or c command.This section describes the installation of the Provisioning and Reconciliation Agents and configuring them to use IBM MQ Series.
Provisioning Agent uses the following members for MQ installation:
To install the Provisioning Agent:
Change "QMGR" in the QMGR PARM field to the name of your queue manager. Your Queue manager is the actual task name given to the MQ Queue manager in the system.
If required, enable the debug option by setting Debug=N (the default) to Y.
Caution:
This will generate a large amount of output. This should only be done for testing.Change Idf.Linklib to the name you have given the Oracle Identity Manager Authorized Load Module Library.
Edit member PIOCOPY and submit:
Insert your installation approved job card.
Change IDF.CNTL to the name you have given the Oracle Identity Manager Control Library. See Step 2: Installing the Connector Agents.
Change SYS1.PROCLIB to the name of the JES PROCLIB you would like to use.
Change the Reconciliation Agent-started task to initiate as a started task.
Submit PIOCOPY. Ensure that the member VOYAGER is present in your selected JES PROCLIB.
Change all occurrences of "QMGR" to the name of your queue manager. Your Queue manager is the actual task name given to the MQ Queue manager in the system.
Change all occurrences of "STGCLASS" to the name of the storage class for the two Provisioning Agent queues.
Note:
For performance reasons, your installation may want to define the two Provisioning Agent queues to different storage classes. If you are also using the Reconciliation Agent, you may want to use separate storage classes for the Reconciliation Agent queue.Edit member PIODEF and submit:
Insert your jobcard.
Change "QMGR" in the PARM to the name of your queue manager.
Change "MQMHLQ" to the high level qualifier of your MQ System datasets.
Change IDF.CNTL to the name you have given the Oracle Identity Manager control library.
Note:
Depending on your security environment, you may need to define Provisioning Agent as a started task and grant access to the dataset and MQ resources.The Provisioning Agent is ready to start.
Note:
The Provisioning Agent is dependent on MQ series, so you must ensure that the queue manager is active before starting the Provisioning Agent.If the Provisioning Agent is a started task, then start Provisioning Agent by issuing S PIONEER from the console. If Provisioning Agent is a batch task, then submit the PIONEER JCL.
The Reconciliation Agent installation members in the control library are:
To install the Reconciliation Agent:
Change "QMGR" in the QMGR PARM field to the name of your queue manager. Your queue manager is the actual task name given to the MQ Queue manager in the system.
If required, enable the debug option by changing Debug=N to Y.
Caution:
This will generate a large amount of output. This should only be performed for testing purposes.Change IDF.LINKLIB to the name you have given the Oracle Identity Manager Authorized Load Module Library.
Edit members VOYINIT, VOYKILL, and VOYSTOP:
Change IDF.LINKLIB to the name you have given the Oracle Identity Manager Authorized Load Module Library.
Edit member VOYCOPY and submit.
Insert your installation approved job card.
Change IDF.CNTL to the name you have given the Oracle Identity Manager control library.
Change SYS1PROCLIB to the name of the JESPROCLIB proclib you would like Voyager to be started from as a started task.
Ensure that members VOYAGER, VOYINIT, VOYKILL, and VOYSTOP are present in selected JES PROCLIB.
For installation with MQ Series: edit member VOYMQ.
Change all occurrences of "QMGR" to the name of your queue manager. Your queue manager is the actual task name given to the MQ Queue manager in the system.
Change all occurrences of +STGCLASS+ to the name of the storage class for the Reconciliation Agent queue.
Note:
You may want to assign the Reconciliation Agent to a different storage class than the one used by the Provisioning Agent queues.Edit member VOYDEF and submit.
Insert your job card.
Change "QMGR" in the parameter to the name of your queue manager. Your queue manager is the actual task name given to the MQ Queue manager in the system.
Change +MQMHLQ+ to the high level qualifier of your MQ system datasets.
Change IDF.CNTL to the name you have given the Oracle Identity Manager Control Library.
Ensure that the three objects are defined without errors.
Note:
Depending on your security environment, you may need to defineVOYAGER, VOYINIT, VOYKILL, and VOYSTOP as started tasks and grant access to the dataset and MQ resources.The Reconciliation Agent is ready to start.
Additional Notes
The Reconciliation Agent is dependent on MQ. Therefore, ensure that the queue manager is active before starting the Reconciliation Agent.
Start the VOYINIT task by issuing "S VOYINIT" from the console to create the subpool (this only needs to be done once, unless VOYKILL is run).
Once VOYINIT ends, then start Reconciliation Agent by issuing "S VOYAGER" from the console.
To quiesce VOYAGER while leaving the subpool intact, start VOYSTOP by issuing "S VOYSTOP" from the console. To quiesce Reconciliation Agent and destroy the subpool, start VOYKILL by issuing "S VOYKILL" from the console. Use of VOYKILL will cause any messages stored in the subpool to be lost.
Note:
Events detected by the Reconciliation Agent through exit technology are transformed into messages and passed to the LDAP Gateway.If MQ Series is used as the message transport layer, these messages are secured internally within the MQ system for delivery.
If the TCP/IP message transport layer is used, the messages are securely sent to the Gateway. If the Gateway is down, messages are held until the Gateway is returned to service, but also secured in an AES encrypted file on the mainframe. When the Gateway resumes, the messages are then sent.
If the subpool is stopped by an administrator, it shuts down the Provisioning Agent, destroying any messages not transmitted. However, the messages in the secured AES-encrypted file are not affected and can be recovered.
APF stands for the IBM Authorized Program Facility. Granting a program the APF Authorized status is similar to giving superuser status. This process will allow a program to run without allowing normal system administrators to query or interfere with its operation. Both the program that runs on the mainframe system and the user account it runs under must have APF authorization. For example, the Provisioning Agent user account must also have APF authorization.
Note:
APF authorization is usually done by a mainframe administrator. If you do not have the required authority to perform such tasks, you should arrange to enlist the assistance of someone who is qualified to perform these tasks.For APF authorization, you need to create the necessary definitions.
Logon to TSO by using a user account that has the requisite authority to execute IBM RACF commands and modify the IBM RACF database. For example, IBMUSER normally has such authority.
From a TSO command line (or Option 6 of ISPF), issue the following IBM RACF command:
RDEFINE FACILITY IRR.RADMIN.* UACC(NONE)
This command defines a IBM RACF resource named IRR.RADMIN.* in the FACILITY class.
From a TSO command line (or Option 6 of ISPF), issue the following IBM RACF command:
PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(STARTER) ACCESS(READ)
This command grants READ access to the resource IRR.RADMIN.* for user account STARTER (an example of the user account for the starter task). This allows the starter task to issue RACF commands.
From a TSO command line (or Option 6 of ISPF), issue the following IBM RACF command:
ALTUSER STARTER SPECIAL
This command grants the SPECIAL attribute to user account STARTER, which allows the started task to access and modify IBM RACF User Profiles.
Issue the following command from a TSO command line (or Option 6 of ISPF):
SETROPTS RACLIST(FACILITY) REFRESH
This command updates the in-storage tables of IBM RACF to immediately activate the definitions that you create.
Exit from ISPF.
There are two different JCLs to set up and run the Provisioning Agent and Reconciliation Agent. You can use these two JCL files for the basis of a starter task definition.
The parameters for RUNPIONX.txt are:
TCPN, the name of the TCP process
IPAD, the IP address of the system that the Provisioning Agent is running on
PORT, the incoming connection port for the Provisioning Agent
DEBUG, the debug switch for showing the extra output
The parameters for RUNVOYAX.txt are:
TCPN, the name of the TCP process
IPAD, the IP address of the system that the Reconciliation Agent is connected to
PORT, the outgoing connection port for the Reconciliation Agent
DEBUG, the debug switch for showing the extra output
Source code for each program is:
RUNPIONX:
//ADCDMPPT JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//PIONEERX EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=Host IP Address of the IBM RACF System',
// 'PORT=5790',
// 'DEBUG=Y')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//SYSPRINT DD SYSOUT=X
//SYSUDUMP DD SYSOUT=X
//
RUNVOYAx:
//ADCDMRVX JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//VOYAGERX EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=Host IP Address of the IBM RACF System',
// 'PORT=5190',
// 'DEBUG=Y')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//SYSPRINT DD SYSOUT=X
//SYSUDUMP DD SYSOUT=X
//
