| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.4 Part Number E10424-06 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for CA Top Secret Advanced Release 9.0.4 Part Number E10424-06 |
|
|
View PDF |
You must install the Reconciliation Agent and Provisioning Agent components of the CA Top Secret Advanced connector on the mainframe. The following sections describe the installation and configuration of these agents:
Both the Reconciliation Agent and Provisioning Agent need a started task and service account that has the privileges required to run CA Top Secret system commands on the mainframe system.
In addition, both the Reconciliation Agent and Provisioning Agent require a surrogate Top-Secret ACID. This ACID must have administrative privileges to issue creates, changes, lists, and replaces.
Note:
Both the Reconciliation Agent and Provisioning Agent require executable code (z/OS loadlibs) to be APF authorized. This can be achieved by a dynamic set command (T PROG=) or by placing the installation loadlib containing the executable code in the z/OS Linklist.Ensure that the following requirements are met on the mainframe:
The Provisioning Agent and Reconciliation agent use created z/OS subpool to manage peak load conditions. The subpool (231), which is allocated below the 16M line, requires 200 KB of memory for storage of Top-Secret events.
The Reconciliation Agent operates by using exit technology, within the z/OS operating system environment.
Command execution is captured by an exit, just before full completion of the native mainframe command. If the exit fails, then the command fails and returns an error message. Maintaining a specific password format is an example of the objective for which you use custom exits. Oracle Identity Manager exits are engineered to be the last exits called in sequence, which allows the existing exits to function normally. After modifying exits within an LPAR, an initial program load (IPL) of the LPAR may be required.
Note:
The systems programmer must perform an IPL after a system component is changed or modified.To deploy the Reconciliation Agent and Provisioning Agent:
Extract the contents of the following file from the installation media to a temporary directory on any computer:
etc/Provisioning and Reconciliation Connector/Mainframe_TS.zip
The following JES2 xmit files are included in the TSS-Adapter package:
Linklib.xmi: Executable library for all modules
parmlib.xmi: PROG member for dynamically authorizing IDF.LINKLIB
prclib.xmi: Contains all the STC (Started Task Procedures)
maclib.xmi: z/OS maclib containing TSSINSTX source code
Log in to the TSO environment of the mainframe.
Perform the following steps either from the TSO 'Ready' prompt or by using ISPF Option #6 using a TN3270 or TN3270E emulator (each file must be uploaded without any file conversion and in binary):
Note:
You can also use FTP to upload the files.Upload each file to z/OS.
Run the 'Receive inda(file-name-uploaded)' command for each file uploaded.
When prompted for dataset names, use the following information:
linklib.xmi: IDF.LINKLIB
parmlib.xmi: IDF.PARMLIB
prclib.xmi: IDF.PROCLIB
maclib.xmi: IDF.MACLIB
To complete the installation, add 'IDF.LINKLIB' to the Linklist member of SYS1.PARMLIB or the installation parmlib used for the z/OS IPL.
Pioneer and Voyager require a Top-Secret ACID for operation and a set of permissions. The following is an example of the steps to be performed:
Note:
In these sample steps,
xxxxxx is the ACID. This ID must be an administrator ID and with the permissions required to perform operations such as Create, Add, Addto, Replaces, and Changes. The following definitions are only an example in a test type environment.Create(xxxxxx) type(sca) name('pionvgr') password(nopw) facility(batch,stc)
Add(xxxxxx) uid(0) group(omvsgrp) dfltgrp(omvsgrp) home(/) omvspgm(/bin/sh)
Addto(stc) procname(pioneer) acid(xxxxxx)
Addto(stc) procname(voyager) acid(xxxxxx)
permit(xxxxxx) ibmfac(bpx.*) access(read)
permit(xxxxxx) ibmfac(irr.radmin.*) access(read)
add(xxxxxx) fac(all)
admin(xxxxxx) resource(all)
admin(xxxxxx) data(all)
admin(xxxxxx) acid(all)
admin(xxxxxx) facility(all)
admin(xxxxxx) misc1(all)
admin(xxxxxx) misc2(all)
admin(xxxxxx) misc3(all)
admin(xxxxxx) misc4(all)
admin(xxxxxx) misc8(all)
admin(xxxxxx) misc9(all)
Because the exit modules are in the z/OS Load Library, an IPL may or may not be required to complete the installation. This depends on whether the z/OS Load Library is added to the LinkList, which is a z/OS storage area defined when an IPL is performed. To allow the LDAP Gateway to fully capture events, the Reconciliation Agent and its exits must be installed on each LPAR that shares the authentication repository.
The following are guidelines regarding the Reconciliation Agent exit:
The Reconciliation Agent is installed in a z/OS Load Library for execution.
The exit (TSSINSTX) must be accessible by the operating system after the IPL is started.
It can be in the Linklist or steplib'ed to the STC (Reconciliation Agent).
The Reconciliation Agent exit must be active and the subpool that contains TSS events must be active. If the exit is not active or subpool not activated (by executing Startup), then Top Secret events are not captured and sent to the LDAP gateway.
In a single-LPAR environment, the Reconciliation Agent is required for real-time reconciliation event capture and the Provisioning Agent is required for provisioning.
In a multiple-LPAR environment where the Top Secret database is shared, a master LPAR runs the Reconciliation Agent and Provisioning Agent. In addition, TSSINSTX must be installed and the subpool must be active.
All Top Secret events from other LPARs are sent through the CPF to the master.
If the CPF is not installed, then events are not captured and the Reconciliation Agent and Provisioning Agent are required on each LPAR.
This section also discusses the following topics:
Note:
If there are no other exits installed on Top Secret, then perform the procedure described in this section.To install the Reconciliation Agent exit:
Copy the exit from IDF.LINKLIB to a user-defined CA loadlib, which is in the Linklist for the LPAR.
Add the user-defined CA Loadlib to the SYS1.PARMLIB member PROG=.
Perform an IPL on z/OS.
Run the following command from the z/OS operator's console to activate the exit code:
'F TSS,EXIT(ON')
Note:
There is only one exit within a CA Top Secret environment. Typically, a production deployment has its own custom changes already written into the exit. The exit supplied with the connector differs from the CA Top Secret supplied exit with the addition of three calls to external programs.To deactivate the exit, run the following command:
'F TSS,EXIT(OFF)'
Note:
If there are other exits installed on Top Secret, then perform the procedure described in this section.If one or more third-party modules have been installed with the Top Secret (TSSINSTX) exit, then integration is required. This integration may be accomplished through code modification of either the Reconciliation Agent exit or the third-party exit.
This section discusses the following topics:
The Reconciliation Agent exit can be modified in a number of different ways to integrate it with existing Top-Secret exits. To facilitate this alteration, the source for the exit is provided in the maclib.xmi file.
Note:
This procedure should be undertaken only by experienced mainframe programmers. The exit runs in z/OS supervisor mode, and appropriate precautions should be taken before modifying the exit.To work with the exit source:
Upload the maclib.xmi file in binary format to the mainframe using Option #6 on TSO.
After the upload is completed, run the following TSO command:
RECEIVE da('filename upload')
When prompted, specify the dataset name IDF.MACLIB.CNTL.
The maclib.xmi file contains TSSINSTX, which is the source and macros for the standard exit. These are used for assembly and linkedit of the installable binary. You must customize the TSSINSTX DD SYSLIB as follows:
// SYSLIB DD DISP=SHR,DSN=SYS1.MACLIB // DD DISP=SHR,DSN=SYS1.MODGEN // DD DISP=SHR,DSN=SYS1.AMODGEN // DD DISP=SHR,DSN=CAI.TSSOPMAT // DD DISP=SHR,DSN=IDF.MACLIB.CNTL
The SYS1 libraries are z/OS libraries and the CAI is the Top Secret Maclib containing the exit macros. The IDF.MACLIB.CNTL is created by the RECEIVE command and contains the copybooks required for assembly.
Change the following Assemble and Linkedit parameter:
//AL PROC LMOD='IDF.LINKLIB',
This parameter in the predefined z/OS procedure uses an LMOD parameter, which is the name of the Loadlib for the destination of the exit module. During installation, you assemble and linkedit to this library, and then (optionally) APF authorize the library. Typically, the library resides in the Linklist. If this is true for your operating environment, then APF authorization is not required.
Note:
Modifications similar to the ones performed on the Reconciliation Agent exit can be performed on the third-party exit. However, the exact procedure depends on the content of the third-party exit.Only one module is called as the Top Secret Exit (TSSINSTX). All other exits must either be integrated into a single unified TSSINSTX or renamed so that the modules do not conflict.
Integration of the Reconciliation Agent exit can be accomplished in one of the following ways:
Using the Reconciliation Agent Exit As First Executed with Another Exit
Using Reconciliation Agent Exit As Last Executed with Another Exit
Note:
It is recommended that the Reconciliation Agent exit be called last, or be the only exit. This is because other exits might modify data. If this occurs after the Reconciliation Agent exit has been called, then the Oracle Identity Manager data repository is not completely synchronized with the Top Secret repository.Using the Reconciliation Agent Exit as the One Executed Between Other Exits
Note:
Because the modification to the Reconciliation Agent exit code is in the exit section, the other exit code will be called after execution of the Reconciliation Agent exit code.To use the Reconciliation Agent exit as the first executed with another exit:
Deactivate the currently installed TSSINSTX by running the following command:
F TSS,EXIT(OFF)
Rename the installed TSSINSTX as TSSEXIT in the appropriate load library.
Modify the Reconciliation Agent exit as follows:
Insert the following instructions immediately after the exit label:
EXIT DS 0H LA R1,R9 Copy parmlist ptr to Reg1(R1) LR R11,R13 Save TSS's savearea PTR LA R13,WORKAREA L R15,=V(TSSEXIT) Load Reg15 with address of TSSEXIT BALR R14,R15 LTR R15,R15 LM R0,R14,0(R13) BR R14 End
Save the modified exit in the installation TSS Product library.
Customize and run the JCL provided in IDF.JCLLIB member ASMINSTX.
This will assemble and linkedit the customized TSSINSTX exit.
Verify that TSSINSTX is assembled with an MVS condition code of all 0000.
If the TSS product library is in the Linklist, refresh it by running the following command:
F LLA,REFRESH
After the refresh is completed, activate the new exit by running the following command:
F TSS,EXIT(ON)
Note:
Because the modification to the Reconciliation Agent exit code is performed in the PREINIT section, the other exit code will be called before execution of the Reconciliation Agent exit code.To use the Reconciliation Agent exit as the last executed with another exit:
Deactivate the currently installed TSSINSTX by running the following command:
F TSS,EXIT(OFF)
Rename the installed TSSINSTX as TSSEXIT in the appropriate load library.
Modify the Reconciliation Agent exit as follows:
Change the ##MATRIX byte for PREINIT to a value of #####YES.
Insert the following instructions immediately after the PREINIT label:
LA R1,R9 Copy parmlist ptr to Reg1(R1) LR R11,R13 Save TSS's savearea PTR LA R13,WORKAREA L R15,=V(TSSEXIT) Load Reg15 with address of TSSEXIT BALR R14,R15 B PASSPASS Branch to continue
Save the modified exit into the installation TSS Product library.
Customize and run the JCL provided in IDF.JCLLIB member ASMINSTX.
This will assemble and linkedit the customized TSSINSTX exit.
Verify TSSINSTX assembled with an MVS condition code of all 0000
If the TSS product library is in the Linklist, refresh it by running the following command:
F LLA,REFRESH
After the refresh is completed, activate the new exit by running the following command:
F TSS,EXIT(ON)
By combining the changes described for the first executed and last executed exits, you can configure the Reconciliation Agent exit to be called in the middle of the execution stack.
This section describes how to establish a TCP/IP connection with the LDAP Gateway and the building and operation of the starter tasks in the following topics:
Note:
Events detected by the Reconciliation Agent through exit technology are transformed into messages and encrypted using AES encryption before being passed to the LDAP Gateway.
If the LDAP Gateway is not running, then messages are held until the Gateway is returned to service and also secured in an AES-encrypted file on the mainframe. These messages are sent when the LDAP Gateway resumes running.
If the subpool is stopped by an administrator, then it shuts down the Provisioning Agent, thereby destroying any messages that are not transmitted. However, the messages in the AES-encrypted file are not affected and can be recovered.
This section describes how to configure TCP/IP as the message transport layer. Check with the systems programmer for detailed information about using TCP/IP. The objective 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.
To establish a TCP/IP connection with the LDAP Gateway:
Note:
For instructions to start and stop the LDAP Gateway, see "Installing and Configuring the LDAP Gateway".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 start 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 the mainframe
IP address for the router
IP addresses for domain name servers
Note:
To use TCP/IP as the message transport layer, you might need the help of the systems programmer to create ports on the mainframe and to provide security authorizations.The Provisioning Agent and Reconciliation Agent JCL procedure shipped with the connector must be edited to specify the user parameters that are different for each environment. To edit the Provisioning Agent and Reconciliation Agent JCL, you must edit the Voyager and Pioneer started tasks (STCs) procedures. To do so:
Change the value for PARM='TCPN=TCPIP' to the name of the running TCP/IP started task.
Change the IP address to the address (IPAD= parameter) of the LDAP Gateway (for Voyager only).
Change the port number (PORT= parameter) to the port assigned in the LPAR (z/OS system) from which the Provisioning Agent will be listening on for messages from the LDAP Gateway.
Change the port number (PORT = parameter) to the port that the LDAP gateway is listening on for messages from the Reconcilation Agent (Voyager).
For Voyager Reconciliation Agent, TSO edit the VOYAGERX procedure as shown:
//VOYAGERX EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=&SERVER', ------ This must match the IP address or the DNS
------ host name of the LDAP Gateway.
// 'PORT=&PORT', ----- Port must be 5190.
// 'DEBUG=N',
// 'ESIZE=16',
// 'DELAY=10',
// 'STARTDELAY=10',
// 'PRTNCODE=SHUTRC')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB ------This is not required for Linklist.
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//CACHESAV DD DSN=VOYAGER.CACHESAV,DISP=SHR
//DEBUGOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//
Where:
ESIZE=16 is used to denote AES encryption.
DELAY=01 to 99 in seconds. This is used for Top Secret cache. The value of DELAY is 10 on most z/OS systems running CA Top Secret.
STARTDELAY=10 is the recommended value (in seconds).
PRTNCODE=SHUTRC shows all MVS condition codes after the Reconciliation Agent shuts down.
PRTNCODE=SHUTRC shows all MVS condition codes after the Reconciliation Agent shuts down. Alternatively, PRTNCODE=TERMRC shows an MVS condition code of 0000 (signifying successful completion) after the Reconciliation Agent shuts down.
IPAD= is either the IP address or the DNS hostname of the LDAP Gateway.
DEBUG=Y routes debugging statements to the DEBUGOUT data definition statement (DD).
Caution:
This setting generates a large amount of output. It is recommended that you consult support personnel before you use apply this setting.Note:
To shut down the Reconciliation Agent, run the following command from the z/OS operator's console:'F VOYAGER,SHUTDOWN'
To shut down the Provisioning Agent, run the following command from the z/OS operator's console:
'F PIONEER,SHUTDOWN'
TCPN=TCPIP is the name of TCPIP STC name.
DEBUG can be one of the following for both the Reconciliation Agent and Provisioning Agent:
N is for no debugging output.
Y is for debugging output.
Z is for detailed debugging.
Note:
If the "data set in use" message is displayed when you attempt to edit a member, then press the F1 key twice to see details of the member that you are trying to edit. The name of the job that is causing the exception is displayed. On the z/OS console, you can remove the job by using thep or the c command.Apply the following guidelines while working with the Reconciliation Agent:
The subpool (RUNSTART.JCL) must be started before starting the Reconciliation Agent. The subpool is used as an in-memory storage for message creation.
Because you are using TCP/IP, the LDAP Gateway must be started first. If the Reconciliation Agent is started first, then an error is generated with RETCODE=-01 and ERRORNO=61 because the LDAP Gateway is not available.
Voyager Cachesav dataset:
Pre-allocate the Cachesav dataset of the Voyager Reconciliation Agent with the following dataset attributes:
DSORG=PS, LRECL=32, RECFM=FB, BLKSIZE=27968, CYLS = 5
For Pioneer Provisioning Agent:
//PIONEER EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=0.0.0.0',
// 'PORT=5790',
// 'DEBUG=N',
// 'ESIZE=16',
// 'LPAR=XXXXXXXX')
//STEPLIB DD DSN=IDF.LINKLIB ,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD SYSOUT=(*,INTRDR)
//DEBUGOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Where:
TCPN=TCPIP is the name of TCPIP STC name.
IPAD must always be zeros.
PORT=5790 must match the provisioning port of the LDAP Gateway.
ESIZE=16 must be left as is.
LPAR= 'XXXXXXXX' . This is a 8 character unique identifier for the system partition on which the Provisioning Agent is running.
There are two different JCLs to set up and run the Provisioning Agent and Reconciliation Agent. There is a JCL member for each agent. RUNPIONX and RUNVOYAX are samples to set up the started tasks.
The parameters for RUNPIONX are:
TCPN: Name of the TCP process
IPAD: IP address of the computer on which the Provisioning Agent is running
PORT: Incoming connection port for the Provisioning Agent
DEBUG: Debug switch for showing the extra output
ESIZE: AES encryption used
The parameters for RUNVOYAX are:
TCPN: Name of the TCP process
IPAD: IP address of the computer on which the Reconciliation Agent is connected
PORT: Outgoing connection port for the Reconciliation Agent
DEBUG: Debug switch for generating large amount of output into the z/OS JES2 queue that facilitates troubleshooting
ESIZE: AES encryption used
The source code for each program is as follows:
For RUNPIONX:
Note:
The BATJINFO, VSAMGETO, and VSAMGETU data definition (DD) statements are not required on Top Secret installations and can be commented out as shown in this block of code.//PIONEERX EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=&SERVER',
// 'PORT=&PORT'
// 'DEBUG=Y',
// 'ESIZE=16',
// 'LPAR=TOPSECRET-SYS')
// 'LPAR= name ')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//* BATJINFO DD DISP=SHR,DSN=hlq.BATJCARD
//* VSAMGETU DD DISP=SHR ,DSN=hlq.SWUSERS
//* VSAMGETO DD DISP=SHR,DSN=hlq.TOPSCOUT
//SYSPRINT DD SYSOUT=X
//DEBUGOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=X
//
Note:
In the code, hlq stands for installation high-level qualifier. The IPAD= parameter above must always be0.0.0.0.For RUNVOYAX:
//VOYAGERX EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=&SERVER', ß--- must match LDAPS IP address
// 'PORT=&PORT', ß--- must be Port 5190
// 'DEBUG=Y',
// 'ESIZE=16',
// 'DELAY=00',
// 'STARTDELAY=10',
// 'PRTNCODE=SHUTRC')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB ß- not required for Linklist
// DD DISP=SHR,DSN=TCPIP.SEZATCP
//CACHESAV DD DSN=VOYAGER.CACHESAV,DISP=SHR
//DEBUGOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=X
//SYSUDUMP DD SYSOUT=X
//
For the Reconciliation Agent:
The dataset attributes for Cachesav is:
Cachesav - DSORG(PS),LRECL=(32),RECFM=(FB),BLKSIZE=(27968)
|
 Copyright © 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|