| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.2 Part Number B32152-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.2 Part Number B32152-01 |
|
|
View PDF |
The Provisioning Agent and Reconciliation Agent components of the Oracle Identity Manager CA Top Secret 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 installing the 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 permissions are above those of the ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges. |
The CA Top Secret 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 installation of the Provisioning and Reconciliation Agents.
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 is typically configured 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 CA Top Secret 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 TSO environment.
Expand the CNTL dataset, issue the following command from the ISPF command line:
SO RECEIVE INDA('IDF.CNTL.XMIT')
To expand the LINKLIB dataset, 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, and member #INSTPIO for the Provisioning Agent.
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 authentication repository.
Follow the normal procedure for installing exits on the 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 CA Top Secret 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, use the following command 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 view 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 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:
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 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 making 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.
//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 "dataset in use" message when attempting to edit a member, use the F1 key to see who is using the member 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 theP or C command. |
This section describes Provisioning and Reconciliation Agent installation for MQ series.
Provisioning Agent uses the following members for MQ installation:
PIOCOPY: Copies the Provisioning Agent-started task to your installation procedure library.
PIODEF: Defines the Provisioning Agent MQ definitions
PIOMQ: Provisioning Agent MQ definition input
PIONEER: Provisioning Agent start task job control
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 installation.
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 job card.
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.
Provisioning Agent is ready to start.
|
Note: Provisioning Agent is dependent on MQ series, so ensure that the queue manager is active before starting the Provisioning Agent.If the Provisioning Agent is a started task, start Provisioning Agent by issuing " |
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 installation.
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 SYS1.PROCLIB to the name of the JES PROCLIB you would like the Reconciliation Agent to be started from as a started task.
Ensure that members VOYAGER, VOYINIT, VOYKILL, and VOYSTOP are present in selected JES PROCLIB.
For installations 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 installation.
Change all occurrences of +STGCLASS+ to the name of the storage classfor 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 installation.
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, both the Provisioning Agent program 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.
Log on to TSO by using a user ID that has the requisite authority to execute CA Top Secret commands and modify the CA Top Secret database. For example, IBMUSER normally has such authority.
From a TSO command line (or Option 6 of ISPF), issue the following command:
RDEFINE FACILITY IRR.RADMIN.* UACC(NONE)
This command defines a resource named IRR.RADMIN.* in the FACILITY class.
From a TSO command line (or Option 6 of ISPF), issue the following command:
PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(STARTER) ACCESS(READ)
This command grants READ access to resource IRR.RADMIN.* for User ID STARTER (an example of the User ID of the starter task). This allows the starter task to issue commands.
From a TSO command line (or Option 6 of ISPF), issue the following command:
ALTUSER STARTER SPECIAL
This command grants the SPECIAL attribute to User ID STARTER, which allows the started task to access and modify 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 to immediately activate the definitions that you create.
Once the required definitions are in place, exit to get out of ISPF.
There are two different JCLs to set up and run the Provisioning Agent and the 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
//
