| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.2 Part Number B32186-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.2 Part Number B32186-01 |
|
|
View PDF |
The Provisioning and Reconciliation Agent Components of the Oracle Identity Manager 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 ID on the mainframe system. This user ID must be created by the mainframe administrator during the deployment of the Provisioning Agent and the Reconcilliation Agent.
|
Note: Both the Provisioning Agent and Reconciliation Agent user IDs require placement into an administrative APF-authorized library. These user IDs must have at least the permissions of theSystemAdministrators group on the mainframe. These user IDs have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges. |
The IBM RACF Advanced connector has the following mainframe environment requirements:
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 ID 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, issue the following command from 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.
Follow the normal procedure for installing exits on your z/OS system. 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
To uninstall the Reconciliation Agent exit, 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:
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.
The first step is to start up the Oracle Identity Manager LDAP Gateway. This will have been previously configured to connect to using a given IP address and port number.
Once the LDAP Gateway is started, 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, an administrator will be needed to allow the creation of ports on the mainframe, as well as providing security authorizations for the data structures.
Edit the Provisioning Agent and Reconciliation Agent JCL and make the following changes:
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 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=148.141.7.113',
// '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 described below:
//VOYAGERX EXEC PGM=VOYAGERX,
// PARM=('TCPN=TCPIP',
// 'IPAD=192.168.1.231',
// '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 F1 to see who is using the member you are trying to edit. You will have to press F1 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, do the following:
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: Initial Connector Installation.
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. |
Provisioning Agent is ready to start.
|
Note: Provisioning Agent is dependent on MQ series, so ensure that the queue manager is active before starting Provisioning Agent.If Provisioning Agent is a started task, start Provisioning Agent by issuing "S PIONEER" from the console. If Provisioning Agent is a batch task, submit the Provisioning Agent JCL. |
The Reconciliation Agent installation members in the control library are:
Installation instructions:
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. |
Reconciliation Agent is ready to start.
Additional Notes
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 ID it runs under must have APF authorization. For example, the Provisioning Agent user ID 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 ID 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 ID STARTER (an example of the User ID 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 ID 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.
Once the required IBM RACF definitions are in place, exit to get out of 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 machine 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 machine 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=192.168.1.231',
// '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=192.168.1.183',
// '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
//
