| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.1 Part Number B31113-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.1 Part Number B31113-01 |
|
|
View PDF |
The Provisioning and Reconciliation Connector Components of the Oracle Identity Manager CA Top Secret connector are installed on the mainframe.
This chapter describes the installation and configuration of the Oracle Identity Manager Provisioning Connector and Reconciliation Connector in the following sections:
The following table identifies hardware, software, and authorization prerequisites for the installing Provisioning Connector and Reconciliation Connector.
| Item | Requirement |
|---|---|
| Operating System | z/OS, any version |
| Message Transport Layer | TCP/IP Network MQ Series v.5 or later |
| z/OS Patch Level | Verify that all current patches are in place. |
| Top Secret Identity Repository | CA-Top Secret MVS Release 5.0, genlevel 9702 or later
Current patch level for z/OS |
There are two primary systems that are installed on the mainframe, the Provisioning Connector and the Reconciliation Connector. Both connectors require the installation of a started task and both require placement into an administrative APF authorized library.
Installation of the environment is from load libraries. However, if any environmental issues are encountered, assistance may be needed to quickly diagnose the problem. The following are the toolsets available in a typical mainframe shop to handle these issues:
Cobol Compiler. The current version was compiled using IBM Enterprise COBOL for z/OS and OS/390 3.1.1
Assembler. Oracle Identity Manager currently uses HLASM R4.0.
The CA Top Secret Advanced connector has the following environment requirements:
Each Connector uses memory subpools to manage peak load conditions. These subpools require 1.5 to 2.0 MB of mainframe memory for operations.
The Provisioning Connector program user ID should be given authorization to access subpools on the host platform.
If MQ Series is used in your environment and you plan for Oracle Identity Manager to use MQ series as a message transport layer, then a sample program that is an MQ-enabled program should be available. An MQ administrator will be needed to authorize the creation of MQ queues from our automated script. Oracle Identity Manager requires three queues: a send queue, a receive queue, and a voyager communication queue. The names of these queues will be inserted into the Provisioning Connector and Reconciliation Connector start up JCL.
Using TCP/IP, an administrator will be needed to allow creation of ports on the mainframe, as well as provide security authorizations for the data structures.
The Reconciliation Connector operates at the Exit level, just outside the mainframe operating system. Typical mainframe shops install custom exits, for example to maintain a certain password format.
If there are custom exits already installed, an engineering effort will be needed to allow Reconciliation Connector exits to coexist with existing exits already deployed. The Oracle Identity Manager exits are engineered to be the last exits called in sequence, allowing existing exits to function normally. Installation of new exits within an LPAR may require an IPL of the LPAR.
These are the initial procedures for installing the components of the 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 CNTLdataset dataset, issue the following command from the ISPF command line:
SO RECEIVE INDA('IDF.CNTL.XMIT')
To expand the LINKLIBdataset,, 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 Connector components, and member #INSTPIO for the Provisioning Connector component.
Because the exits reside in LPA, an IPL is required to complete the installation. To events Reconciliation Connector and its exits should be installed on each LPAR that shares the CA Top Secret authentication repository.
Note:
The following instructions assume you will install both Provisioning Connector and Reconciliation Connector Connectors.Follow the normal procedure for applying such changes to your z/OS system. It is recommended that you:
Install and test the exits on a test system or partition first.
Make a copy of your system volumes before applying any changes.
Consider packaging the exits as SMP/E user mods.
Assemble the exits into an authorized load library.
To install the Reconciliation Connector 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.
Below are three commands that will compromise the PARMLIB list you create. The three commands can also be added via operator console commands. The following sample command appends the Reconciliation Connector 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 uninstall the LDX 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)
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 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
This section describes the following Message Transport Layer configuration tasks for both TCP/IP and MQ Series:
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
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 Connector and Reconciliation Connector 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 Connector will be started from).
Change the port number to the port assigned in the LPAR (z/OS System that Provisioning Connector will be started from).
If your installation requires batch feeds then insert the proper VSAMGETU statement. See Batch Loading of Top SecretACIDS below.
//USR98S01 JOB (,xxxxxxxx,,'PIONEER 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
//*
If Provisioning Connector is a started task, start Provisioning Connector by issuing "S Pioneer" from the console. If Provisioning Connector is a batch task, submit the Pioneer JCL.For Reconciliation Connector the Job Control is the same with the exception of the execute card, which is described below:
//RECONCILIATION CONNECTORX EXEC PGM=RECONCILIATION CONNECTORX,
// PARM=('TCPN=TCPIP',
// 'IPAD=192.168.1.231',
// 'PORT=5791',
// 'DEBUG=Y')
For both Reconciliation Connector and Provisioning Connector 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 connector installation for MQ series.
Provisioning Connector uses the following for MQ installation:
PIOCOPY: Copies the Provisioning Connector-started task to your installation procedure library.
PIODEF: Defines the Provisioning Connector MQ definitions
PIOMQ: Provisioning Connector MQ definition input
PIONEER: Provisioning Connector start task job control
Installation instructions:
Edit Member PIONEER.
If using the MQ series protocol:
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 installing system.
If desired, enable the debug option by changing 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 (The library downloaded in the previous install steps).
Change SYS1.PROCLIB to the name of the JES PROCLIB you would like to use.
Change the Reconciliation Connector-started task to initiate as a started task.
Submit PIOCOPY. Ensure that the member VOYAGER is present in your selected JES PROCLIB.
For MQ series installations: Edit Member PIOMQ.
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 installing system.
Change all occurrences of "STGCLASS" to the name of the storage class you have chosen for the two Provisioning Connector queues.
Note:
For performance reasons, your installation may want to define the two Provisioning Connector queues to different storage classes. If you are using Reconciliation Connector (in addition to Reconciliation Connector ), you may want to use separate storage classes for the Reconciliation Connector 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.
Submit PIODEF. Ensure that the three objects are defined without errors.
Note:
Depending on your security environment, you may need to define Provisioning Connector as a started task and grant access to the dataset and MQ resources.Provisioning Connector Is Ready To Start.
Note:
Provisioning Connector is dependent on MQ series, so ensure that the queue manager is active before starting pioneer.If Provisioning Connector is a started task, start Provisioning Connector by issuing "S PIONEER" from the console. If Provisioning Connector is a batch task, submit the Provisioning Connector JCL.
The Provisioning Connector installation members distributed in the control library are:
VOYAGER: Reconciliation Connector-started task job control
VOYCOPY: Copies the Reconciliation Connector started tasks to the procedure library
VOYDEF: Defines the Reconciliation Connector MQ definitions
VOYINIT: Reconciliation Connector initialization-started task
VOYKILL: Reconciliation Connector subpool removal-started task
VOYMQ: Reconciliation Connector MQ definition input
VOYSTOP: Reconciliation Connector stop-started task
Installation instructions:
Edit Member VOYAGER.
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 installing 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 SYS1.PROCLIB to the name of the JES PROCLIB proclib you would like Voyager to be started from as a started task.
Submit VOYCOPY.
Ensure that members VOYAGER, VOYINIT, VOYKILL, and VOYSTOP are present in selected JES PROCLIB.
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 installing system.
Change all occurrences of +STGCLASS+ to the name of the storage class you would like the queue for Reconciliation Connector defined.
Note:
You may want to assign the Reconciliation Connector to a different storage class than the one used by the Provisioning Connector 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 installing 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.
Submit VOYDEF. 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 Connector Is Ready To Start.
Reconciliation Connector is dependent on MQ. Therefore, ensure that the queue manager is active before starting Voyager.
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 Connector by issuing "S VOYAGER" from the console.
Note:
To quiesceVOYAGER while leaving the subpool intact, start VOYSTOP by issuing "S VOYSTOP" from the console. To quiesce Reconciliation Connector and destroy the subpool, start VOYKILL by issuing "S VOYKILL" from the console.Caution:
Use of VOYKILL will cause any CA Top Secret messages stored in the subpool to be lost.For APF authorization, you need to create the necessary definitions
Note:
This step requires that you be appropriately authorized to issue CA Top Secret commands and to make alterations to the CA Top Secret database. 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.Logon to TSO by using a user ID that has the requisite authority to execute CA Top Secretcommands and modify the CA Top Secretdatabase. For example, IBMUSER normally has such authority.
From a TSO command line (or Option 6 of ISPF), issue the following CA Top Secret command:
RDEFINE FACILITY IRR.RADMIN.* UACC(NONE)
This command defines a CA Top Secret resource named IRR.RADMIN.* in the FACILITY class.
Note:
This resource may already be defined to your installation.From a TSO command line (or Option 6 of ISPF), issue the following CA Top Secret command:
PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(STARTER) ACCESS(READ)
This command grants READ access to resource IRR.RADMIN.* for User ID STARTER (this is User ID which the starter task runs under). This allows the starter task to issue CA Top Secret commands.
From a TSO command line (or Option 6 of ISPF), issue the following CA Top Secret command:
ALTUSER STARTER SPECIAL
This command grants the SPECIAL attribute to User ID STARTER, which allows the started task to access and modify CA Top Secret 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 CA Top Secret to immediately activate the definitions that you create.
Once the required CA Top Secret definitions are in place, exit to get out of ISPF.
There are two different JCLs to setup and run Provisioning Connector and Reconciliation Connector. You can use these two JCL files for the basis of a starter task definition.
Note:
The JCLs have a time set of 1440 on the jobs.The parameters for RUNPIONX.txt are:
TCPN, the name of the TCP process
IPAD, the IP address of machine that Provisioning Connector is running on
PORT, the port that we are listening on
DEBUG, the debug switch for showing the extra output
The parameters for RUNVOYAX.txt
TCPN, the name of the TCP process
IPAD, the IP address of machine that Reconciliation Connector is connection to
PORT, the port that we are talking to
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
//RECONCILIATION CONNECTORX EXEC PGM=RECONCILIATION CONNECTORX,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
//
Pioneer and the LDAP console have the ability to load ACIDs from a file into the conversion process and provision IM product data base records in a set of automated tasks. This facility is useful in loading the new IM system from the existing legacy CA Top Secret security database.
This requires the JCL added to the start up task Job Control for Provisioning Connector.
//VSAMGETU DD DISP=SHR,DSN=USR99S.FEEDFILE.SORTED
The LDAP console will then provide a list of ACIDS for which automated information can be obtained and the new database loaded.
In the IDF.CNTL library, you will find a task called UPLOAD. The current task is a three-step process. The first step utilizes a Top Secret utility to create sequential records from the Top Secret security database. These records do not contain passwords so as to protect the confidential nature of the information.
The second step utilizes an IBM utility to extract only the ACID from each record.
The third step sorts the ACIDS. This sort is done so that as the ACIDs are fed in and propagated across systems, they are processed sequentially and in proper order to aid the performance of the load process.
