| Oracle® Identity Manager Connector Guide for CA-ACF2 Advanced Release 9.0.3 Part Number B32349-01 |
|
|
View PDF |
| Oracle® Identity Manager Connector Guide for CA-ACF2 Advanced Release 9.0.3 Part Number B32349-01 |
|
|
View PDF |
The Provisioning and the Reconciliation Agent components of the CA-ACF2 Advanced connector are deployed on the mainframe.
This chapter describes the installation and configuration of the Provisioning Agent and the Reconciliation Agent in the following sections:
The following table includes hardware, software, and authorization prerequisites for installing both the Provisioning Agent and the 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 require 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 the 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 user accounts have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges.To deploy the CA-ACF2 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 the Provisioning Agent and the Reconciliation Agent installation.
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 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 the 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-ACF2 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 data set, 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 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 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 authentication repository.
To install the Reconciliation Agent exits:
Make sure the exit modules can be found via the system parmlib. For example, a typical system would have an entry in OIMACF2.PARMLIB(LPALSTCA). They can be in a separate LPA or listed alone by name.
Copy the exits into the appropriate LPAR for the system. In a typical installation, you copy the modules IDFACF2E, IDFACF2P, IDFACF2X into CAI.CAILPA. Also copy a utility module called IDFCACHE into CAI.CAILPA. The exit modules are in LINKLIB PDS and should be copied to the appropriate LPAR for the system.
Modify the control GSO record for system to add the exits. If the GSO record already exists, it will need to be changed, or else add a new record. Bear in mind that SYSTEMNAME is the name of the deployment system.
READY , ACF ? SET CONTROL(GSO) SYSID(SYSTEMNAME) ? INSERT SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXITS EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P) ACF0A026 RECORD ALREADY EXISTS, ? CHANGE SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P) SYSTEMNAME / EXITS LAST CHANGED BY MLIGHT ON 03/22/06-23:24, NEWPXIT(IDFACF2P) EXPPXIT(IDFACF2X) LIDPOST(IDFACF2E) ? QUIT
Refresh the GSO to add in the new values:
READY ACF ? F ACF2,REFRESH(EXITS) ACF79507 GSO PROCESSING COMPLETED WITHOUT ERROR ? QUIT READY
After a re-IPL of the system, the exits should be in place and operational.
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-ACF2 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 as 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 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 the Reconciliation Agent JCL:
Insert an installation-approved job card.
Change the value for PARM from 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 the Provisioning Agent will be started from.
Change the port number to the port assigned to the LPAR (z/OS System) that the 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-ACF2 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 of ACF2 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 of ACF2 system',
// 'PORT=5791',
// 'DEBUG=Y')
For both the Reconciliation and Provisioning Agents, the following DEBUG parameter field equivalents can be used:
N is for no debugging output.
Y is for debugging output.
Z is for debugging output, but the output is not written to MQ.
Note:
If you get the "data set 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 the Provisioning Agent and the Reconciliation Agent installation for MQ series.
The Provisioning Agent uses the following members for MQ installation:
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 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.For installations with MQ Series, 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 data sets.
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 the Provisioning Agent as a started task and grant access to the data set and MQ resources.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 the Provisioning Agent by issuing S PIONEER from the console. If the Provisioning Agent is a batch task, then submit the PIONEER JCL.
The Reconciliation Agent installation members in the control library are:
VOYINIT: The Reconciliation Agent initialization started task
VOYKILL: The Reconciliation Agent subpool removal started task
VOYCOPY: Copies the VOYAGER Reconciliation Agent started tasks to the procedure library
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 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 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.
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 data sets.
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 data set and MQ resources.The Reconciliation Agent is ready to start.
Additional Notes
The 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 the 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 the 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, the Provisioning Agent 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-ACF2 commands and modify the CA-ACF2 database. For example, IBMUSER normally has such authority.
From a TSO command line (or Option 6 of ISPF), issue the following CA-ACF2 command:
RDEFINE FACILITY IRR.RADMIN.* UACC(NONE)
This command defines a CA-ACF2 resource named IRR.RADMIN.* in the FACILITY class.
From a TSO command line (or Option 6 of ISPF), issue the following CA-ACF2 command:
PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(STARTER) ACCESS(READ)
This command grants READ access to the IRR.RADMIN.* resource for the User ID STARTER (an example of the user account of the starter task). This allows the starter task to issue CA-ACF2 commands.
From a TSO command line (or Option 6 of ISPF), issue the following CA-ACF2 command:
ALTUSER STARTER SPECIAL
This command grants the SPECIAL attribute to User ID STARTER, which allows the started task to access and modify CA-ACF2 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-ACF2 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 of ACF2 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 of ACF2 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
//
