| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.4 Part Number E10451-14 |
|
|
PDF · Mobi · ePub |
| Oracle® Identity Manager Connector Guide for IBM RACF Advanced Release 9.0.4 Part Number E10451-14 |
|
|
PDF · Mobi · ePub |
You deploy the Reconciliation Agent and Provisioning Agent on the mainframe. These agents communicate with the LDAP Gateway during connector operations.
Note:
If you are deploying the agents on a mainframe cluster, then perform the procedures described in this chapter on each LPAR of the cluster.The following section summarizes the procedure to deploy the Reconciliation Agent and Provisioning Agent:
The following sections describe each deployment step in detail:
Section 3.3, "Deploying the Reconciliation Agent and Provisioning Agent"
Section 3.5, "Installing or Integrating the Reconciliation Agent Exits"
Section 3.6, "Creating an IBM RACF Account for Connector Operations"
Section 3.7, "Starting Up and Shutting Down the Reconciliation Agent and Provisioning Agent"
See the following sections if you want to remove the Reconciliation Agent exits:
The following steps summarize the procedure to deploy the connector components on the target system:
Review and address the deployment requirements.
Deploy the Reconciliation Agent and Provisioning Agent.
Configure the started tasks.
Install or integrate the Reconciliation Agent exits.
Create an IBM RACF account for reconciliation and provisioning operations.
Test the setup by starting up and shutting down the Reconciliation Agent and Provisioning Agent.
The following is a summary of the deployment requirements:
The Reconciliation Agent and Provisioning Agent require a RACF user ID on z/OS. This RACF user ID for Pioneer must have the privileges (shown later in this chapter) execute RACF commands on the mainframe. This is the equivalent of giving the agents and the RACF user ID a full RACF administrator authority.
The procedure is described in Section 3.6, "Creating an IBM RACF Account for Connector Operations."
The Reconciliation Agent uses z/OS system subpool for storage of Reconciliation events generated by the three exits. If the exits (ICHPWX01,ICHRIX02 and IRREVX01) are not active then the subpool storage is not necessary and does not have to be allocated via the STARTUP program. The subpool is configurable in size from 200K to 1001K. The procedure is described in Section 3.3, "Deploying the Reconciliation Agent and Provisioning Agent."
The Reconciliation Agent operates by using exit technology, within the IBM 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. If the subpool is not allocated and the exits are active, warning messages are issued , indicating the events will be lost. If the subpool fills up, which would indicate that Voyager is not connected to the LDAP, the incoming events will be lost only and system integrity will not be lost. Maintaining a specific password format is an example of the objective for which you use custom exits, such as the ones used by the Reconciliation Agent. These exits can be set up as the last exits called in sequence. This allows existing exits to function normally.
Note:
The systems programmer must perform an IPL after a system component is changed or modified. In particular, the two LPA loaded exits, ICHPWX01 and ICHRIX02.To deploy the Reconciliation Agent and Provisioning Agent:
Extract the contents of the following file from the installation media to a temporary directory:
etc/Provisioning and Reconciliation Connector/Mainframe_RACF.zip
Transmit the following files to the IBM z/OS computer:
clist.xmi
jcllib.xmi
linklib.xmi
parmlib.xmi
proclib.xmi
You can transmit the files either through FTP or IND$FILE on a TN3270 emulator. The files must be transmitted in binary format.
The output files are in JES2 XMIT format. The output file names can be, for example:
IDF.CLIST.XMIT
IDF.JCLLIB.XMIT
IDF.LINKLIB.XMIT
IDF.PARMLIB.XMIT
IDF.PROCLIB.XMIT
The file attributes are as follows:
RECFM=FB
LRECL=80
BLKSIZE=3120
DSORG=PS
Log in to the TSO environment of the mainframe.
Expand each of the uploaded XMIT files by running TSO Option #6 and then running the RECEIVE INDA('XMIT_FILE_NAME') command. The output is the following files:
IDF.CLISTLIB
IDF.JCLLIB
IDF.LINKLIB
IDF.PARMLIB
IDF.PROCLIB
In TSO, edit all members of IDF.JCLLIB and modify the MVS job card to match DataCenter job card standards. Modify VOL=SER=?????? so that the value is the VOL=SER disk volume in which the datasets are to be placed.
TSO submit the CREATDSN member to IBM z/OS. Verify that the return code (RC) for completion is 0000.
Ensure that the //SYSPROC statement of REXXCL points to IDF.CLISTLIB, which is the library that contains the CLISTs required by the LDAP Gateway for running batched reconciliation.
Verify that the job card is correct for the installation.
TSO submit the LOADDSN member to IBM z/OS. This member loads the required datasets with the IDCAMSC and REXXCL members. Verify that the return code (RC) is 0000 (that is, no errors are encountered).
If the ICHPWX01 and ICHRIX02 exits do not exist, then run IEBCOPYL. This copies the LOGPWX01 and LOGRIX02 exits to a new or existing library that is defined in the LPA in IEASYSxx.
If the ICHPWX01, ICHRIX02, or IRREVX01 exit exists, then the LOGPWX01, LOGRIX02, and LOGEVX01 exits must be called as described in Section 3.5, "Installing or Integrating the Reconciliation Agent Exits."
Copy the started tasks and procedures to a new procedure library or an existing library. To do so, review and if required modify the IEBCPYPR member so that it conforms to installation standards. Then, TSO submit the member and verify that the return code for completion is 0000.
Review IEBCOPYP and determine whether the product LINKLIB (IDF.LINKLIB) is APF-authorized at IPL. If it is not APF authorized, then run the IEBCOPYP member.
Similarly, review IDF.PARMLIB member = PROG75. This is the dynamic member for IRREVX01, and it is required for real-time reconciliation. If it is not APF authorized, then run this member.
In the installation running IEASYSxx, verify that the IEFSSNxx member pointed to by the IEASYSxx parameter SSN= has the following defined:
The SUBSYS SUBNAME(RACF)
INITRTN(IRRSSI00)
(or)
SUBSYS SUBNAME(RACF)
INITRTN(IRRSSI00)
INITPARM('#')
Both of these examples will work.
This is required because the Provisioning Agent uses the R_Admin RACF service call through the IRRSEQ00 module. Without it, the Provisioning Agent fails.
TCPIP ports can also be reserved. A good example is in TCP.PROFILE using the PORT statement.
If the port to be reserved is 2000 and the Pioneer STC (Started Task) name is Pioneer, then the PORT statement should be:
PORT 2000 TCP PIONEER
There are two different started tasks (STCs) to set up and run the Reconciliation Agent and Provisioning Agent. The STC procedure member for each agent, Pioneer and Voyager, is in IDF.PROCLIB. The following sections provide information about configuring these STCs:
The following are parameters of Pioneer:
Note:
Ensure that the parameters are in the order shown in the PARM statement of the STC procedure and in the Provisioning Agent control file, which is mentioned later in this section. If the parameters are not in the specified order, then the Provisioning Agent will fail.TCPN: Enter the name of the TCP STC on the mainframe.
IPAD: Ensure that the value is always 0.0.0.0.
PORT: Ensure that the incoming connection port for the Provisioning Agent matches the value of the _port_ property in the racf.properties file and the port property in the beans.xml file. Both files are components of the LDAP Gateway. The gateway uses this port to connect to the mainframe and send provisioning data to the Provisioning Agent. See Section 2.9, "Installing and Configuring the LDAP Gateway" for information about these files. The default port is 5790.
DEBUG: Enter Y as the value if you want diagnostic information to be displayed when Pioneer is run. Otherwise, enter N.
Caution:
TheDEBUG=Y setting generates a large amount of output. It is recommended that you consult support personnel before you apply this setting.The following lines are from the source code for Pioneer:
//PIONEER EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
// PARM=('TCPN=TCPIP',
// 'IPAD=0.0.0.0',
// 'PORT=5797',
// 'DEBUG=Y')
//JCLOUTP DD SYSOUT=*
//PARMFLE DD DISP=SHR,DSN=PIONEER.ORACLE.CTLFLE (OR) //PARMFLE DD DISP=SHR,DSN=PIONEER.CONTROL.FILE(XXXXXXX)
//SYSTSPRT DD DISP=SHR, DSN=PIONEER.REXXOUT.FILE
//GRPS DD DUMMY
//SYSEXEC DD DISP=SHR, DSN=ORACLE.CLIST.LIBRARY
//RECONJCL DD DISP=SHR, DSN=PIONEER.ORACLE.RECON.LIBRARY
//FULLIMPU DD DISP=SHR, DSN=PIONEER.IMPORTU.FILE
//FULLIMPG DD DISP=SHR, DSN=PIONEER.IMPORTG.FILE
//RECONOUT DD DISP=SHR, DSN=PIONEER.ORACLE.RECON.FILE
//INJCLR DD DISP=SHR, DSN=PIONEER.ORACLE.JCLLIB
//INJCLR1 DD DISP=SHR, DSN=PIONEER.INJCL2.LIBRARY
//INJCLR2 DD DISP=SHR, DSN=PIONEER.INJCL3.LIBRARY
//LISTINR DD DISP=SHR, DSN=PIONEER.ORACLE.LSTOUT
// DCB=(RECFM=VB,LRECL=137)
//SYSPUNCH DD SYSOUT=(*,INTRDR)
//SYSPRINT DD SYSOUT=*
//
The following is an explanation of some of the lines in the preceding source code:
(1) //JCLOUTP - DD required for displays/prints of submitted z/OS job streams.
(2) //SYSTSPRT - DD required for output of all internally called Rexx clists.
(3) //GRPS - DD required and should not be removed.
(4) //SYSEXEC - DD required for all internally called Rexx clists, this is the actual clist library.
(5) //RECONJCL - Skeleton JCL for all batch reconciliation executions, Pioneer "reads" this file only.
(6) //RECONOUT - Batch reconciliation execution output file. Used as input for Pioneer/LDAP.
(7) //INJCLR - Skeleton JCL for all Batch Alias executions. Pioneer "reads" this file only.
(8) //LISTINR -Output file of Batch Alias executions and used as input for Pioneer/LDAP.
(9) //SYSPUNCH - Must always point to INTRDR, all recon batch jobs are read from PDS library members and punched to the Intrdr.
(10) //SYSPRINT - Standard Sysprint.
(11) //PARMFLE - This is the PARMFLE data definition statement. The PARMFLE can be defined as a PDS and the parameter file can be a member. The PARMFLE is the Provisioning Agent control file. This file contains some of the Pioneer parameters. You can also use this file to add post-processing commands. Section 5.4, "Using the Provisioning Agent to Run IBM z/OS Batch Jobs" provides more information about this feature.
(12)//INJCLR1 - Skeleton JCL for full reconciliations for user IDs
(13)//INJCLR2 - Skeleton JCL for full reconciliations for groups
(14)//FULLIMPU - Output file of the full reconciliation for user IDs execution
(15)//FULLIMPG - Output file of the full reconciliation for groups execution
In the control file, each parameter is on a single line. There are no commas, other delimiting characters, or comments on the line. The following are the default entries in this file:
ESIZE=16
This option controls encryption during provisioning operations. Do not change the value of this parameter.
LPAR=
Enter the name of the LPAR that you have defined for the Provisioning Agent. The name can be up to 20 characters long.
JWAIT=999
This is the value in seconds from 001 to 999 that Pioneer will wait for ALIAS batch job completion. This parameter holds the timeout interval (in seconds) for each batch. You can enter a value from 001 to 999.
DEBUGOUT=
Enter either DEBUGOUT=FILE (or) DEBUGOUT=SYSOUT,CL(X).
If FILE is specified as the value, then the dataset name is PIONEER.DEBUG.FILE. This value cannot be changed for the current release. The IBM z/OS DCB attributes for this FILE are as follows:
DSORG=PS,RECFM=FA,LRECL=134,BLKSIZE=134,CYL=10,UNIT=SYSDA
If DEBUGOUT,SYSOUT,CL() is specified the only valid SYSOUT JES2 classes are A-Z and 0-9. Example is DEBUGOUT,SYSOUT,CL(X)
If Y is specified as the value of DEBUG and FILE is specified as the value of DEBUGOUT, then the file cannot be reviewed. This is because the file is allocated to the Provisioning Agent and is open.
SPIN_CLASS=Y
This parameter is used in conjunction with DEBUGOUT. When the MVS console operator or system's program issues a "F PIONEER,DEBUG-=N" and debugging is activate, the debugging will stop and then the output will spool up in the SPIN_CLASS specified. The valid classes are A-Z and 0-9.
This is the JES2 class the DEBUG output will be placed in, once a operator command of 'F PIONEER,DEBUG=N' us issued. See the 'Operator Commands' later in this section.
IDLEMSG=Y or N
If the value is Y, then idle messages are displayed for every hour of inactivity of the Provisioning Agent. If the value is N, then no messages are displayed.
POST_PROC_ALIAS=
This is either T (true) or F (false), indicates whether Pioneer will process post ALIAS requests from the LDAP.
QUEUE_DSN = Name of the dataset used for queuing/locking for external reconciliations.
| Parameter | Description |
|---|---|
|
ESIZE=16 |
16 is the only valid parameter, which you must not change. This is the encryption type parameter. |
|
LPAR=xx |
UPTO 20 bytes of unique name. |
|
RWAIT=999 |
Values of 001-999 are valid, time used for Pioneer to wait until Batch recon finishes. The only Recon jobs are Search dataset and Search facility. |
|
JWAIT=999 |
Values of 001-999 are valid, time used for Alias Batch completion. |
|
POST_PROC_ALIAS= |
T = True, F = False, True is processing aliases and False if not. |
|
IDLEMSG= |
Y = Pioneer IDLE message ever hour, N = no idle message. |
|
DEBUGOUT= |
SYSOUT,CLASS(Y), for debugging, this will output the debug output when DEBUG=Y to the JES2 spool. FILE, outputs debugging to a fixed record file LRECL=121. |
|
SPIN_CLASS= |
K, this is the CLASS used when the DEBUGGING is stopped. |
|
QUEUE_DSN= |
Queuing dataset used by pioneer for external reconciliations. Passed in Rexx clists for batch executions. Can be up to 44 characters. |
Parameters must be in the order shown in the above table.
Note:
If no C=ADDUSER,ALTUSER,DELUSER,CONNECT or REMOVE are found in the Control file, then no Post-Processing will take place.The following are parameters of contained within the Voyager control file or control file member, the DD (data Definition) statement for Voyager is //PARMFLE, this is a new option in 9.0.4.16:
TCPN: Enter the name of the TCP STC on IBM z/OS.
IPAD: Enter the IP address or host name of the LDAP Gateway host computer. This is the computer on which Oracle Identity Manager is installed.
PORT: Enter the number of the outgoing connection port for the Reconciliation Agent to connect to the LDAP Gateway. In other words, this is the port defined on the LDAP Gateway host computer to which the Reconciliation Agent connects when it detects an event. The default port is 5190.
DEBUG: Enter Y as the value if you want diagnostic information to be displayed when Voyager is run. Otherwise, enter N.
DELAY=00
Do not change this value.
ESIZE=16
Do not change this value, the only value for encryption.
STARTDELAY=99
Seconds to delay Voyager to open its TCP/IP port.
PRTNCODE=SHUTRC
Do not change this value.
VOYAGER_ID=??????????
Voyager ID passed to the LDAP Gateway
CACHE_DELAY=???
Delay for environments running Oracle Identity Manager backends.
| Parameter | Description |
|---|---|
|
TCPN= |
Name of the TCPIP STC in the LPAR where Voyager is executing. |
|
IPAD= |
Ip address as 192.168.1.109 for example or hostname as myhost.com |
|
PORT= |
99999, the port the LPAD is listening on. |
|
DEBUG= |
N = no debugging and Y = yes debugging. |
|
ESIZE= |
16 is the only valid parameter for encryption/decryption. |
|
DELAY=00 |
Delay for CA Top-Secret environments only. |
|
STARTDELAY= |
01 - 99 Amount of time in seconds to delay opening the Voyager connection. |
|
PRTNCODE= |
SHUTRC = show no MVS condition codes only 0000 on shutdown. |
|
CSDATA= |
Y , when Voyager gets a subpool entry it will perform a listuser with csdata as one of the segment names. N= voyager will not use CSDATA as a segment name on a listuser. |
|
VOYAGER_ID= |
8 character unique name that will be passed with each Voyager message to the LDAP gateway. If for example 8 Lpars all running Voyager, each Voyager control file must have the same VOYAGER_ID= coded. |
|
Cache_Delay= |
999 = value in seconds from 001-999 seconds for environments only running Oracle Identity Manager backends. Do not code long delays else the Subpool will backup. Use 030 seconds as a starting value for Oracle Identity Manager backend environments. Non Oracle Identity Manager should code 005 seconds. |
Caution:
TheDEBUG=Y setting generates a large amount of output. It is recommended that you consult support personnel before you apply this setting.The following lines are from the source code for Voyager STC procedure:
//VOYAGER PROC //STEP1 EXEC PGM=VOYAGERX,REGION=0M,TIME=1440, //DEBUGOUT DD SYSOUT=* //PARMOUT DD SYSOUT=* //PARMFLE DD DISP=SHR,DSN=VOYAGER.CONTROL.FILE(XXXXXX) //CACHESAV DD DISP=SHR.DSN=VOYAGER.CACHESAV //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSMDUMP DD SYSOUT=*
The //CACHESAV DD dataset has the following IBM z/OS DCB attributes (new Lrecl and Blksize in 9.0.4.16):
DSORG(PS),RECFM(FB),LRECL(112),BLKSIZE(27888),
Typically, about 10 cylinders should be allocated on a 3390-3. This file is only used if there is a situation that requires Voyager to be shutdown while there are entries in the Subpool. The subpool size in 9.0.4.16 has been increased from 20 bytes to 100 bytes.
This is to add auditing data to the Recon event.
The Reconciliation Agent CACHESAV also requires an IBM RACF definition, similar to the following:
ALTDSD 'IDF.VOYAGER.CACHESAV' UACC(READ) GENERIC
PERMIT 'IDF.VOYAGER.CACHESAV' ID(USERID_FOR_RECONCILIATION_AGENT) ACCESS(UPDATE) GENERIC
The connector uses three standard IBM RACF exits to capture IBM RACF events in real time: ICHPWX01, ICHRIX02, and IRREVX01. Together, these exits capture IBM RACF events resulting from operations such as ADDUSER, ALTUSER, DELUSER, CONNECT, password resets, and password changes that occur from TSO/SDSF or in batch. Data about these events is stored in a MVS subpool 231, CSA/ECSA area of storage on the IBM z/OS computer. This subpool is created by the job/STC supplied in the distribution library called STARTUP. It must be executed before Voyager is started. If the exits are enabled (loaded) and STARTUP has not executed any real-time Reconciliation events are lost. Some customers elect to run only the command capture exit, IRREVX01 and not ICHPWX01 and ICHRIX02. This can be done successfully, but real-times passwords will not be captured for OIM capture and storage. To run only with the IRREVX01 command exit, do not copy the LOGPWX01 or LOGRIX02 from the distribution library to a LPA library. So when RACF starts, it will not find the exits and not start any capture.
See Also:
The "Summary of installation-exit callers" section in z/OS V1R9.0 Security Server RACF System Programmer's Guide for information about the IBM RACF functions captured by each exit.During installation, you rename the standard exits to LOGPWX01, LOGRIX02 and LOGEVX01. This helps avoid naming conflicts if the standard exits are already installed and in use on IBM RACF.
The procedure that you must perform depends on whether or not other versions of these exits have already been installed:
Caution:
Both ICHRIX02 and ICHPWX01 use MODESET macros in assembler to place themselves in supervisor mode. A test LPA and test IEASYSXX must be developed for testing the new exits. Otherwise, if a coding error occurs, you might not be able to IPL the z/OS system.If the standard exits have not been previously installed on IBM RACF, then perform the following steps:
Note:
Perform the procedure described in this section only if there are no other exits installed on the mainframe. See Section 3.5.2, "Integrating the Reconciliation Agent Exits" if there are other exits installed on the mainframe.
SYS1.PARMLIB is one of the libraries that are used to start up the mainframe. In the console commands given in the following steps, xx is the PROG suffix for the member in SYS1.PARMLIB.
Add the LPA library to the LPALSTxx member of IEASYSxx for the startup (IPL) of z/OS.
Dynamically activate LOGEVX01 by using a PROG=xx member of an existing LOADLIB. This is the same library that contains the Reconciliation Agent and Provisioning Agent. Also review where LOGEVX01 is stored, that is, loadlib and verify LOGCACHE is also there. LOGCACHE is the caching routine required by LOGEVX01.
IPL z/OS using CLPA. Use the IEASYSxx mentioned in Step 2.
During the IPL, the ICH508I message should state that the ICHPWX01 and ICHRIX02 exits were found. At this stage, IBM RACF loads pointers (addresses) to the exits for usage.
The following lines are from the IBM RACF loads pointers to the exits of usage:
0290 $ JES2,PARM='COLD,NOREQ'
0290 $ VLF,SUB=MSTR
0290 $ VTAM
0290 $ VTAMAPPL
0290 $ DLF,SUB=MSTR
0290 DD ADD,VOL=JASYS1
0290 DD NAME=SYS1.&NAME..DMP&SEQ
0290 IEE2521 MEMBER SMFPRMOO FOUND IN ADCD.Z11OS.PARMLIB
0290 DD ALLOC=ACTIVE
0090 IEE3511 SMF SYS1.MAN RECORDING NOT BEING USED
0090 ICH5081I ACTIVE RACF EXITS: ICHRIX02 ICHPWX01
0281 IEF196I IEF237I OA82 ALLOCATED TO SYS00001
0281 IEF196I IEF237I OA80 ALLOCATED TO SYS00002
0090 IRR803I VLF IS NOT ACTIVE. POSSIBLE RACF PERFORMANCE IMPACT
0090 ICH581I DYNAMIC CLASS DESCRIPTOR TABLE PROCESSED
0290 IEE252I MEMBER IEFSSN01 FOUND IN ADCD. Z11OS.PARMLIB
0090 IGD031I SMS PARAMETERS 166
0090 ACDS =SYS1.ACDS
After TCP/IP starts running, execute the S STARTUP command to create the subpool. This maybe done via a scheduler or one of the installation processes. The important thing to remember is it must be executed prior to Voyager, otherwise Voyager will fail (abend).
After the subpool is created, the exits start storing data about IBM RACF events in the subpool. Prior to Startup executing, RACF events are not saved.
To start the Reconciliation Agent, run the S VOYAGER command.
After the Reconciliation Agent starts and establishes a connection with the LDAP Gateway, it reads the contents of the subpool, and sends reconciliation data to the LDAP Gateway. If the LDAP gateway is not up, Voyager will wait until the LDAP is up, recovery messages will be issued by Voyager to the z/OS operator's console.
Note:
A good recovery approach is to automate the messages when there is a Voyager failure and decide on what action is required based on installation policy.If there is an existing version of ICHPWX01, ICHRIX02, or IRREVX01 on the IBM RACF installation, then you must integrate the Reconciliation Agent exits with the existing versions. For example, suppose there are existing versions of ICHPWX01 and IRREVX01 on the target system. In this scenario, you must enlist the assistance of a systems programmer to copy ICHRIX02 into a user LPA Library and modify the existing ICHPWX01 and IRREVX01 to call LOGPWX01 and LOGEVX01.
There are several approaches to integrating the Reconciliation Agent exits with an existing exit. Example 3-1 shows one approach toward integrating LOGRIX02 with an existing exit. This example shows the prolog and epilog of the caller exit.
Example 3-1 Sample Integration of LOGRIX02 with an Existing Exit
Caller EXIT - EXIT001
EXIT001 CSECT
USING EXIT001,15
USING SAVEAREA,13
STM 14,12,SAVE14
LR 12,15
USING EXIT001,12
DROP 15
LR 6,1
GETMAIN
ST 1,SAVENEW-SAVEAREA(,13)
ST 13,SAVEOLD-SAVEAREA(,1)
** Existing exit code here **
EXIT DS 0H
L R1,SAVEOLD
L R1,24(R13)
CALL LOGRIX02
LR 1,13
L R13,SAVEOLD
FREEMAIN …………..
XC SAVENEW,SAVENEW
LM 14,12,SAVE14
BR R14
SAVEAREA DSECT
DS F
SAVEOLD DS F
SAVENEW DS F
SAVE14 DS F
SAVE15 DS F
DS 13F
SAVESIZE EQU *-SAVEAREA
After changing the calling exit, assemble and link-edit it. The MVS JCL or procedure you use to link-edit must include the following lines:
// ORACLIB DD DSN=ORACLE.DIST.LINKLIB,DISP=SHR
INCLUDE ORACLIB(LOGRIX02)
NAME EXIT001(R)
/*
Ensure that the output module resides with ICHPWX01 in the same user LPA load library.
The connector uses an IBM RACF user ID for reconciliation and provisioning operations performed on the target system. The following procedure shows the minimum permissions that must be assigned to this user ID:
Note:
Permissions assigned to the user ID must be similar to the permissions granted to the SystemAdministrators group on the mainframe. Users belonging to this group have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges.Create an IBM RACF user ID similar to the following for Pioneer:
ADDUSER START2 DFLTGRP(xxxx) PASSWORD(yyyyyyyy)
ALTUSER START2 SPECIAL
RDEFINE FACILITY IRR.RADMIN.* UACC(NONE) (The installation may not support a Rdefine facility as shown because of their security concerns/restrictions, another approach is to replace the "*" with each command that Pioneer can process, that is, ADDUSER,ALTUSER, DELUSER,LISTUSER,CONNECT and so on). Pioneer is a Centralized host based RACF administrator very much like a person.
PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(START2) ACCESS(READ)
PERMIT BPX.DAEMON CLASS(FACILITY) ID(START2) ACCESS(READ)
Refresh the RACLIST as follows:
SETROPTS RACLIST(FACILITY) REFRESH
The START2 ID in this case is used to start both Voyager and Pioneer. There could also be separate RACF IDs for this purpose. The Voyager RACF ID must have a permit as shown to IRR.RADMIN.LISTUSER now. Voyager after reading the subpool will perform a LISTUSER for the entry in the subpool and build a message(s) and send them back to the LDAP.
For example:
For Voyager:
ADDUSER STARTVOY DFLTGRP(XXX) PASSWORD(xxxxxxx) ADDSD -- whoever owns this CACHESAV DATASET ALTDSD 'IDF.VOYAGER.CACHESAV' UACC(READ) GENERIC PERMIT 'IDF.VOYAGER.CACHESAV' ID(USERID_FOR_RECONCILIATION_AGENT) ACCESS(UPDATE) GENERIC PE IRR.RADMIN.LISTUSER CLASS(FACILITY) ID(STARTVOY) ACCESS(READ) PERMIT BPX.DAEMON CLASS(FACILITY) ID(STARTVOY) ACCESS(READ)
For Pioneer:
ADDUSER(STRTPION) DFLTGRP(OMVS) PASSWORD(xxxxxxxxx) ALTUSER STRTPION SPECIAL RDEFINE FACILITY IRR.RADMIN.* UACC(NONE) <or> RDEFINE FACILITY IRR.RADMIN.xxxxxxx UACC(NONE) (Where the xxxxxxx is the RACF command, please see IBM's Security Server Manual for these commands and permissions ) PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(STRTPION) ACCESS(READ) <or> PE IRR.RADMIN.xxxxxx CLASS(FACILITY) ID(STRTPION) ACCESS(READ) (where xxxxxx is the RACF command from the above rdefine command) PERMIT BPX.DAEMON CLASS(FACILITY) ID(STRTPION) ACCESS(READ)
See Section 3.4.1, "Configuring Pioneer" for further file information.
Both agents use the standard CICS Socket Interface EZASOKET. Error messages that the agents can return are documented in Appendix A and Appendix B. In addition, see OS V1R11.0 Communications Server IP CICS Sockets Guide for more information.
Note:
The subpool and the LDAP Gateway must be started before starting the Reconciliation Agent. If the LDAP Gateway is not available when the Reconciliation Agent is started, then an error is generated withRETCODE=-01 and ERRORNO=61.To start up the Reconciliation Agent and Provisioning Agent:
When IBM z/OS IPLs, IBM RACF is started and the ICHPWX01 and ICHRIX02 exits are activated from the LPA.
JES2 is started.
TCP/IP and other communications-related STCs are started.
The STARTUP procedure is run to create the subpool that is used to capture IBM RACF events. See Appendix A, "Reconciliation Agent (Voyager) Messages" for all messages.
The valid parameters for STARTUP are SUBPOOL=9999K, the 9999 must be a value between 0200K and 1001K.
To start the Reconciliation Agent, run the S VOYAGER command from the IBM z/OS operator's console or SDSF in TSO.
To start the Provisioning Agent, run the S PIONEER command from the IBM z/OS operator's console or SDSF in TSO.
To shut down the Reconciliation Agent and Provisioning Agent:
To shut down the Reconciliation Agent, run the F VOYAGER,SHUTDOWN command from the z/OS Operator console or TSO/ISPF/SDSF/IOF issue.
To shut down the Provisioning Agent, run the F PIONEER,SHUTDOWN command from the z/OS Operator console or TSO/ISPF/SDSF/IOF issue.
If you want to remove the Reconciliation Agent exits, then perform the following steps:
To remove the IRREVX01 exit, run the SET PROG=XX console command. In this command, replace XX with the PROG suffix for the exit (member) in SYS1.PARMLIB. The PROG member of SYS1.PARMLIB would contain the below command:
EXIT DELETE EXITNAME(IRREVX01) MODULE(LOGEVX01)
To remove the ICHPWX01 and ICHRIX02 exits, delete the modules from the LPA library in which they are installed, either by using a batch program (IEBCOPY) or by using TSO option 3.4 . After you delete the exits, a z/OS IPL is may or may not be required depending on the version of z/OS the installation is running. Many of the new releases can dynamically change/update the LPA.
All Operator commands for Pioneer and Voyager are issued through the z/OS modify command interface. Voyager and Pioneer are both single thread STC procedures. The command format is F-stcid command and the stcid is the STC ID or NAME assigned to it by E-Installation.
This section is divided into following topics:
Shutdown - Shutdown Pioneer, closes open ports.
Status - Pioneer reports OK and is alive.
Debug=N - Turns on Debugging, output will be to control file parameter DEBUGOUT=.
Debug=N - Turns off Debugging, if DEBUGOUT=SYSOUT,CL(X), output Queues to JES2 class X.
JWAIT=999 - Modify the JWAIT control file parameter value.
RWAIT=999 - Modify the RWAIT control file parameter value.
The following are the Voyager operator commands:
Shutdown - Shutdown Voyager, closes open ports.
Status - Voyager reports OK and is alive.
IPAD=xxxx.xxxx.xxxx.xxxx, PORT=99999 Switch to a new LDAP at IPAD= IP Address, PORT= port Address.
All Operator command output for Pioneer and Voyager are displayed upon the z/OS master console. The following example displays the STATUS command from Pioneer:
0090 IDMP015I - PIONEER DETECTS JOB WAIT TIME OF 010 SECS 0090 IDMP015I - PIONEER DETECTS RECON WAIT TIME OF 010 SECS 0090 IDMP009I - PIONEER DETECTS ENCRYPTION ENABLED 0090 IDMP030I - PIONEER INITAPI WAS SUCCESSFUL 0090 IDMP031I - PIONEER GETCLIENTID WAS SUCCESSFUL 0090 IDMP032I - CLIENT NAME IS PIONEERN 0090 IDMP033I - CLIENT TASK IS PIONEERX 0090 IDMP035I - PIONEER BIND SOCKET WAS SUCCESSFUL 0090 IDMP036I - PIONEER LISTENING PORT IS 5797 0090 IDMP037I - PIONEER LISTENING ADDRESS IS 0.0.0.0 0090 IDMP038I - PIONEER LISTEN SOCKET CALL WAS SUCCESSFUL 0090 IDMV021I - VOYAGER INITIALIZATION OF PTON WAS SUCCESSFUL 0090 IDMV201I - VOYAGER CONNECTION TO GATEWAY FAILED 0290 F PIONEERN, STATUS 0090 IDFV10A (POLLOPER): HERT=Y (HEARTBEAT)COMMAND SENT TO: PIONEERN 0090 IDMP306I - PIONEER RECEIVED STATUS QUERY AN IS ALIVE
In this example, the Pioneer STC is called 'PIONEERN' and command was 'STATUS'. The entire command whether issued via the z/OS console, TSO, or another running system, is the Operator Interface for Pioneer known as POLLOPER that issues the command to Pioneer or Voyager. The message is IDFV101A. The response back from Pioneer is IDMP306I.
The following is an example of issuing a "F PIONEERN,DEBUG=N" that turns off DEBUGGING:
0090 IDMP056I - PIONEER RECON PROCESSING ENDED 0090 IDMP057I - PIONEER RECON PROCESSING WAS SUCCESSFUL 0090 IDMV021I - VOYAGER INITIALIZATION OF PTON WAS SUCCESSFUL 0090 IDMV201I - VOYAGER CONNECTION TO GATEWAY FAILED 0290 IEA6301 OPERATOR SFORD NOW ACTIVE, SYSTEM=ADCD, LU=RACTP28 0290 F PIONEERN,DEBUG=N 0090 IDFV101A (POLLOPER): DEBUG=N COMMAND SENT TO:PIONEERN 0090 IDMP305I - PIONEER DEBUGGING WAS TURNED: OFF 0090 IDMV021I - VOYAGER INITIALIZATION OF PTON WAS SUCCESSFUL 0090 IDMV201I - VOYAGER CONNECTION TO GATEWAY FAILED 0090 IDMP054I - PIONEER RECEIVED RACF RECON REQUEST FROM LDAP 0090 IDMP055I - PIONEER RECON PROCESSING STARTED 0090 IDMV021I - VOYAGER INITIALIZATION OF PTON WAS SUCCESSFUL 0090 IDMV201I - VOYAGER CONNECTION TO GATEWAY FAILED
In this example, the Pioneer STC is called "PIONEERN" and command was "DEBUG=N". The entire command whether issued via the z/OS console, TSO, or another running system is the Operator Interface for Pioneer known as 'POLLOPER' that issues the command to Pioneer or Voyager. The message is IDFV101A. The response back from Pioneer is IDMP305I.
The following is an example of issuing a "F PIONEERN,DEBUG=N" that turns off DEBUGGING:
0290 F PIONEERN DEBUG=Y 0090 IDFV101A (POLLOPER): DEBUG=Y COMMAND SENT TO: PIONEERN 0090 IDMP305I - PIONEER DEBUGGING WAS TURNED: ON
In this example, the Pioneer STC is called "PIONEERN" and the command was "DEBUG=Y". The entire command whether issued via the z/OS console, TSO, or another running system, the Operator Interface for Pioneer known as "POLLOPER" issues the command to Pioneer or Voyager. The message is IDFV101A. The response back from Pioneer is IDMP305I.
The alias process is an interface into the Standard z/OS Batch environment. The alias process works as follows:
Identity Management software initiates a DEFINE alias request for a RACF user ID.
The request is sent to the LDAP.
LDAP forwards the request to Pioneer.
Pioneer Decrypts the message, converts the message from ASCII to EBCDIC.
Pioneer determines if the message is an ALIAS request, if it is correct, then Pioneer opens the skeleton QSAM file referenced by "DD" INJCLR as shown in the following example:
//IDCALIAS JOB SYSTEMS, MSGLEVEL=(1,1), MSGCLASS)=X, CLASS=A, PARTY=8, // NOTIFY=&SYSUID, REGION=OK //STEPO EXEC PGM=IDCAMS //SYSPRINT DD DSN=PIONEER.ORACLE.LSTOUT,DISP=SHR //SYSIN DD * &CONTROL /*
The SYSPRINT points to a QSAM file that is created by the initial installation of the product. This file is referenced by Pioneer's "DD" LISTINR. The enqueue and dequeue is control and handled by Pioneer. The "&CONTROL" control record is replaced by the DEFINE ALIAS or DELETE ALIAS command. The JCL stream with the replaced control record is then submitted to the INTRDR via SYSPUNCH.
Once the above shown batch JCL executes the output writes to SYSPRINT and Pioneer will read the results and build messages, convert them to ASCII, and encrypt them and send them back to the LDAP and then to the Identity Management software.
The Post-Processing that Pioneer can perform consists of two parts. The first part is contained in various XML control files of the LDAP. The second part is contained in a control file, PARMFLE is the Data Definition (DD) statement of the Pioneer STC (started task). Pioneer will use several other z/OS operating system functions to perform the post-processing requested. The first being one of the Dynamic Allocation programs (BPXWDYN) and the second, the z/OS Intrdr. Both BPXWDYN and the Intrdr should be accessible via Pioneer's RACF user ID. If either one of these components are not accessible and are in a "locked down" state in RACF, Pioneer's post-processing process will fail.
The actual flow of the Post-Process is summarized as follows:
LDAP initiates a ADDUSER, ALTUSER, DELUSER,CONNECT or REMOVE request and this message request is encrypted and send to Pioneer on it's PORT = port.
Pioneer is listening for incoming requests on PORT = port and when a incoming message arrives, Pioneer reads the message, decrypts it, and converts it to EBCDIC.
Once converted to EBCDIC, Pioneer examines the message request and if it is either a ADDUSER,ALTUSER,DELUSER,CONNECT or REMOVE and a control file parameter as follows exist, Pioneer will perform post-processing for every RACF coded in the control file. The following are some examples to illustrate how this process works:
Control-File(1): C=ALTUSER,M=TESTA,L=USER.TEST.JCLLIB
Library USER.TEST.JCLLIB(TESTA) Contents:
//IDCAMSD JOB ,SYSTEMS,CLASS=A,MSGCLASS=X,
// MSGLEVEL=(1,1),REGION=4096K,NOTIFY=&SYSUID
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE ALIAS(NAME(CSX002) RELATE(USERCAT1)) -
CATALOG(CATALOG.Z110S.MASTER)
- Pioneer after receiving the request, dynamically allocates the Library in the L= Portion of the above control record, and the member of the PDS library M= Only PDS libraries are supported as of this release (9.0.4.15).
- After allocation of the PDS and the member, Pioneer reads the PDS's member and punches it to the Intrdr for execution. If this control record has no P= as the next record, no parameters are passed and the implied type is a JCL execution.
- The JCL will execute and at this point Pioneer will not return output or status of the execution, only that the JOB was submitted to z/OS for execution.
- Upon completion of the punching to the Intrdr, Pioneer closes the PDS and member and de-allocates the PDS and the member.
Control-File(2) C=ALTUSER,M=TESTA,L=USER.TEST.JCLLIB P=USERID(Y),DATA(N),N1,N2,N3,N4.N5.N6
Library USER.TEST.JCLLIB(TESTA) Contents After Substitution:
//REXXBTH JOB ,SYSTEMS,CLASS=A,MSGCLASS=X, // MSGLEVEL=(1,1),REGION=4096K,NOTIFY=&SYSUID //STEP1 EXEC PGM=IKJEFT01,DYNAMNBR=20 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSPROC DD DSN=SFORD.CLIST.LIBRARY,DISP=SHR //SYSTSIN DD *
- Pioneer after receiving the request, dynamically allocates the Library in the L= portion of the above control record, and the member of the PDS library M=. Only PDS libraries are supported as of this release (9.0.4.15).
- After allocation of the PDS and the member, Pioneer reads the PDS's member and punches it to the Intrdr for execution. Pioneer will also after seeing the P=USERID(Y) will pass the RACF USERID. The DATA(N) must be coded and is a placeholder, which is required. The parameters passed to a Rexx clist can be RACF user ID and up to six RACF CSDATA FIELDS that had been previously defined using a RACF RDEFINE command. The LDAP will send the ALTUSER with the RACF user ID and upto six CSDATA fields.
- Pioneer will insert after the: "//SYSTSIN DD *" and a %clistname Userid N1 N2 N3 N4 N5 N6
For example:
ALTUSER testa CSDATA(T1(ABCD) T2(DEF) T3 (QWE) would be passed to above example, Clist = TESTA would be passed to the Rexx JCL As 'TESTA testa ABCD DEF QWE' TESTA Rexx clist would be coded similar to the below example: /* rexx */ Arg u1 p1 p2 p3 Say 'Userid ' u1 Say 'Parm1'p1 Say 'Parm2'p2
- The JCL will execute, at this point Pioneer will not return output or status of the execution, only that the JOB was submitted to z/OS for execution.
- Upon completion of the punching to the Intrdr, Pioneer closes the PDS and member and de-allocates the PDS and member.
All output of either the JCL submitted for execution or Rexx clist are the responsibility of the customer. The z/OS JCL examples and Rexx examples are only presented here as examples to illustrate how Post-Processing works inside/outside Pioneer.
Pioneer via LDAP initiation can do the following:
Receive LDAP initiated RACF commands.
Receive MVS Alias requests, defines and deletes.
Perform Post-Processing with various RACF commands from the LDAP.
Receive LDAP initiated SEARCH requests (many of these are executed internal to Pioneer using Rexx - IRXJCL , outputting to SYSTSPRT and then read and sent back to the LDAP - OIM).
For full reconciliations for user IDs and groups the flow is:
a.) LDAP initiates GENUFILE for user IDs and a GENGFILE for groups IDs.
b.) Pioneer receives the request, decrypts, converts to EBCDIC and verifies the
request is valid.
c.) Pioneer for GENUFILE, reads INJCLS , in turn this JCL skeleton executes the
GENUFILE Rexx clist which extracts all user IDs from the RACF database placing them in the //FULLIMPU 'DD' of Pioneer. Full reconcliliations are usually performed infrequently. If the request is for the group, then a GENGFILE is submitted and output is placed in //FULLIMPG.
d.) LDAP then submits a SRCHLU or SRCHLG command to retrieve the data
placed either in //FULLIMPG or //FULLIMPU.
e. ) The //FULLIMPG or //FULLIMGU are cleared or emptied by the use of a command entered on the LDAP.
1. Internal
Pioneer can internally call Rexx clists, one that is used is IDFRACFC user xxxx or IDFRACFC group xxxx. This is a single user ID or group extract from the RACF database. The output of this clist is the //SYSTSPRT 'DD' in Pioneer.
2. External
Pioneer uses 4 Rexx clists for reconcilation work. These clists are:
i. GENUFILE: Generates RACF database extract containing user IDs
ii. GENGFILE: Generates RACF database extract containing groups
iii. SERCHDAT: Generates RACF dataset list of all Datasets
iv. SERCHFAC: Generates RACF facility list
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|