| Oracle® Identity Manager Connector Guide for CA-Top Secret Advanced Release 9.0.3 Part Number B32350-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for CA-Top Secret Advanced Release 9.0.3 Part Number B32350-01 |
|
|
View PDF |
The Provisioning Agent and Reconciliation Agent components of the CA-Top Secret Advanced connector are deployed 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 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 privileges of the
SystemAdministrators group on the mainframe. These permissions are above those of the ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges.To deploy the CA-Top Secret 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 installation of the Provisioning and Reconciliation Agents.
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 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, 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, and member #INSTPIO for the Provisioning Agent.
Caution:
It is important to understand that there is only one exit within a CA Top Secret environment. Often a production deployment will have their own custom changes already written into the exit. The exit supplied with the advanced connector differs from the CA Top Secret supplied exit with the addition of three calls to external programs. The coding skill set and effort required to merge a typical custom production deployment with the supplied advanced connector exit is not trivial.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.
To install the Reconciliation Agent exits:
Make sure exit is turned off.
TSS MODIFY(EXIT(OFF))
Or from the operators console:
/F TSS,EXIT(OFF)
Make sure the exit can be found via the linklist path. For instance, the CA-Top Secret linklist is OIMTSS.PARMLIB(PROGCT). The definition for CAI.TSS80.CAILIB contains the TSSINSTX exit. A typical deployment will probably be different.
The exit TSSINSTX should be copied for our supplied LINKLIB PDS to a library which is in the linklist path.
Refresh the LLA.
/F LLA,REFRESH
Check the status of the exit (look for the exit in the output).
TSS MODIFY(STATUS)
Or from the operators console:
/F TSS,STATUS
Turn the exit on.
TSS MODIFY(EXIT(ON))
Or from the operators console:
/F TSS,EXIT(ON)
The exit is now operational.
Caution:
It is important to understand that there is only one exit within a CA-Top Secret environment. Typically, a production deployment will have its own custom changes already written into the exit. The exit supplied with the advanced connector differs from the CA-Top Secret supplied exit with the addition of three calls to external programs.The coding skill set and effort required to merge a typical custom production deployment with the supplied advanced connector exit is not trivial.
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 CA-Top Secret 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 will have been 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 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 CA-Top Secret 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=IP Address of Top Secret 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=IP Address of Top Secret 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 "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 the P 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:
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 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.
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 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.The 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 account it runs under must have APF authorization. For example, both the Provisioning Agent program 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.
Log on to TSO by using a user account 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 account STARTER (an example of the user account 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 account 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.
Exit from 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 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=IP Address of Top Secret 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=IP Address of Top Secret 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
//
