1 About the Connector

Oracle Identity Manager automates access rights management, security, and provisioning of IT resources. Oracle Identity Manager connectors are used to integrate Oracle Identity Manager with external, identity-aware applications. This guide discusses the connector that enables you to use IBM RACF as a managed (target) resource for Oracle Identity Manager.

The advanced connector for IBM RACF provides a native interface between IBM RACF installed on an IBM z/OS mainframe and Oracle Identity Manager. The connector functions as a trusted virtual administrator on the target system, performing tasks related to creating and managing user profiles.

The connector allows information about users created or modified directly on the target system to be reconciled into Oracle Identity Manager. In addition, you can use Oracle Identity Manager to perform provisioning operations on the target system.

In the IBM RACF context, the term user profile is synonymous with user account. If IBM RACF is configured as a target resource, then user profiles on IBM RACF correspond to accounts or resources assigned to OIM Users.

This chapter is divided into the following sections:

• Section 1.1, "Certified Components"

• Section 1.2, "Certified Languages"

• Section 1.3, "Connector Architecture"

• Section 1.4, "Features of the Connector"

• Section 1.5, "Connector Objects Used During Reconciliation and Provisioning"

1.1 Certified Components

Table 1-1 lists the certified components.

Table 1-1 Certified Components

Item	Requirement
Oracle Identity Manager	You can use one of the following releases of Oracle Identity Manager: Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0) and any later BP in this release track Oracle Identity Manager 11g Release 2 PS3 (11.1.2.3.0) and any later BP in this release track Note: In this guide, Oracle Identity Manager release 11.1.2.x has been used to denote Oracle Identity Manager 11g release 2 (11.1.2.x) or future releases in the 11.1.2.x series that the connector supports.
JDK	JDK 1.6, update 31 or later.
Target system	IBM RACF on z/OS 1.13 to 2.2
Infrastructure Requirements: Message transport layer between the Oracle Identity Manager and the mainframe environment	The infrastructure requirements can be one of the following: TCP/IP with Advanced Encryption Standard (AES) encryption z/OS AES encryption
Target system user account for reconciliation and provisioning operations	IBM Authorized Program Facility (APF) authorized account with System Administrators privileges See Chapter 2, "Deploying the IDF Advanced Adapter for IBM RACF" for more information.
Product Libraries	The following are the product libraries: z/OS standard Load Libraries. These libraries must be APF authorized. IRREVX01 resides in the Product Library.
Pioneer and Voyager	Pioneer and Voyager are written in single thread LE Cobol. They were developed to run above the 16M line. Options that can adversely affect these STCs are LE run options: ALL31(OFF) instead of ON STACK(,,,BELOW,,) instead of STACK(,,,ANYWHERE,,)
LDAP Gateway operating system and JDK	The operating system for LDAP Gateway can be any one of the following: Microsoft Windows Server 2008 SP2 Microsoft Windows Server 2008 R2 SP1 (64-bit) Microsoft Windows Server 2012 (64-bit) Microsoft Windows Server 2012 R2 (64-bit) Oracle Linux 5.5+ Oracle Linux 6.x (32-bit), 6.x (64-bit) Oracle Linux 7.x (64-bit) (7u67 and above) Red Hat Enterprise Linux 5.5+, 6.x (32-bit), 6.x (64-bit) Red Hat Enterprise Linux 7.x (64-bit) (7u67 and above) Suse Linux Enterprise Server 10 SP2, 11.x Suse Linux Enterprise Server 12.x (7u75 and above) Ubuntu Linux 10.04 and above The following version of JDK is supported: JDK 1.7 or above

1.2 Certified Languages

The connector supports the following languages:

• Arabic

• Chinese (Simplified)

• Chinese (Traditional)

• Danish

• English

• French

• German

• Italian

• Japanese

• Korean

• Portuguese (Brazilian)

• Spanish

1.3 Connector Architecture

The connector architecture is described in the following sections:

• Section 1.3.1, "Connector Components"

• Section 1.3.2, "Connector Operations"

1.3.1 Connector Components

The connector contains the following components:

• LDAP Gateway: The LDAP Gateway receives instructions from Oracle Identity Manager in the same way as any LDAP version 3 identity store. These LDAP commands are then converted into native commands for IBM RACF and sent to the Provisioning Agent. The response, which is also native to IBM RACF, is parsed into an LDAP-format response and returned to Oracle Identity Manager.

  During reconciliation, the LDAP Gateway receives event notification, converts the events to LDAP format, and then forwards them to Oracle Identity Manager, or events can be stored in the LDAP Gateway internal store and pulled into Oracle Identity Manager by a scheduled task.

• Provisioning Agent (Pioneer): The Provisioning Agent is a mainframe component. It receives native mainframe IBM RACF provisioning commands from the LDAP Gateway. These requests are processed against the IBM RACF authentication repository, in which all provisioning updates from the LDAP Gateway are stored. The response is parsed and returned to the LDAP Gateway.

  Note:

  At some places in this guide, the Provisioning Agent is referred to as Pioneer.

• Reconciliation Agent (Voyager): The Reconciliation Agent captures mainframe events by using exits, which are programs run after events in IBM RACF are processed. These events include the ones generated at TSO logins, the command prompt, batch jobs, and other native events. These events are stored in a subpool cache area that is established by a supplied, standard z/OS procedure (STARTUP). The Reconciliation Agent captures these events, transforms them into LDAPv3 protocol notification messages, and then sends them to Oracle Identity Manager through the LDAP Gateway.

  Note:

  At some places in this guide, the Reconciliation Agent is referred to as Voyager.

• Message Transport Layer: The message transport layer enables the exchange of messages between the LDAP Gateway and the Reconciliation Agent and Provisioning Agent. TCP/IP protocol is used for the transport of messages.

  TCP/IP with Advanced Encryption Standard (AES) encryption using 128-bit cryptographic key. The connector supports a message transport layer by using the TCP/IP protocol, which is functionally similar to proprietary message transport layer protocols.

1.3.2 Connector Operations

This section provides an overview of the following processes:

• Section 1.3.2.1, "Full Reconciliation Process"

• Section 1.3.2.2, "Initial LDAP Population and Reconciliation Process"

• Section 1.3.2.3, "Provisioning Process"

1.3.2.1 Full Reconciliation Process

Full reconciliation involves fetching existing user profile data from the mainframe to Oracle Identity Manager. If you configure the target system as a target resource, then this user profile data is converted into accounts or resources for OIM Users.

The following is a summary of the full reconciliation process:

Note:

For detailed instructions, see Chapter 2, "Deploying the IDF Advanced Adapter for IBM RACF" of this guide.

1. You set values for the attributes of the RACF Reconcile All Users scheduled task.

2. You run the scheduled task. The task sends a search request to the LDAP Gateway.

3. The LDAP Gateway encrypts the search request and then sends it to the Provisioning Agent on the mainframe.

4. The Provisioning Agent encrypts user profile data received from RACF and then passes this data to the LDAP Gateway.

5. The LDAP Gateway decrypts the user profile data. If the user profile data does not include any changes when compared to the OIM user's existing resource data, then the event is ignored and reconciliation continues with the next user on the target system. If the user profile data includes a change, then the LDAP Gateway passes the data on to Oracle Identity Manager.

6. The user profile data is converted into accounts or resources for OIM Users.

1.3.2.2 Initial LDAP Population and Reconciliation Process

This reconciliation process allows for a faster reconciliation based on an Extracted File configured on the Mainframe that will be used to populate the internal LDAP store, which OIM can then use a normal scheduled task to reconcile all the data to Oracle Identity Manager.

The following is a summary of the full reconciliation process:

Note:

For detailed instructions, see Section 5.7, "Initial LDAP Gateway Population and Full Reconciliation" of this guide.

1. Use IBM utility to EXTRACT user data to a file.

2. Configure Pioneer to use this file when needed.

   Once this file has been created and used by OIM it will become stale and must be deleted. The file can be generated again if needed for re-populating or updating the Internal LDAP for Oracle Identity Manager to reconcile the latest data.

3. Once the above file is generated, run the RACF Reconcile Users To Internal LDAP scheduled task to populate the LDAP Gateway internal store.

4. After the LDAP Gateway internal store is populated, run the RACF Reconcile All LDAP Users scheduled task with one of the following settings:

   1. To reconcile all users, set the value of the Last Modified Timestamp attribute to 0.

   2. To reconcile all users that have changed since that date, set the value of the Last Modified Timestamp attribute to a date range.

   Note:

   If the _internalEnt_ property, located in the LDAP_INSTALL_DIR/conf/racf.properties file, is set to true, then the LDAP internal store will also be populated on an ongoing basis by the "real-time" event capture using Voyager and the EXIT(s). So after initial population and reconciliation the process will still continue to use the RACF Reconcile All Ldap Users Task scheduled job using a Date range to reconcile these "real-time" event changes from data captured in the LDAP internal store.

1.3.2.3 Provisioning Process

Figure 1-1 shows the flow of data during provisioning.

Figure 1-1 Provisioning Process

Description of ''Figure 1-1 Provisioning Process''

The following is a summary of the provisioning process:

1. Provisioning data submitted from Oracle Identity Self Service is sent to the LDAP Gateway.

2. The LDAP Gateway converts the provisioning data into mainframe commands, encrypts the commands, and then sends them to the mainframe computer over TCP/IP.

3. The Provisioning Agent installed on the mainframe computer decrypts and converts the LDAP message from ASCII to EBCDIC.

4. The Provisioning agent executes the commands, runs them on the mainframe and within the Pioneer STC (Started Task) using the RACF API (IRRSEQ00).

5. The Provisioning Agent converts the RACF API output to ASCII and encrypts the message prior to sending back to the LDAP Gateway.

6. The outcome of the operation on the mainframe is displayed in Identity Self Service. A more detailed message is recorded in the connector log file.

1.4 Features of the Connector

The following are features of the connector:

• Section 1.4.1, "Full and Incremental Reconciliation"

• Section 1.4.2, "Encrypted Communication Between the Target System and Oracle Identity Manager"

• Section 1.4.3, "High Availability Feature of the Connector"

1.4.1 Full and Incremental Reconciliation

After you deploy the connector, you perform full reconciliation to bring all existing user profile data from the target system to Oracle Identity Manager. After the first full reconciliation run, the scheduled task works in incremental mode by leveraging the value present in the Last Modified Time Stamp parameter of the IT resource.

You can perform a full reconciliation run at any time. See Section 4.4.1, "Configuring Incremental Reconciliation" and Section 4.4.2, "Performing Full Reconciliation" for more information.

1.4.2 Encrypted Communication Between the Target System and Oracle Identity Manager

AES-128 encryption is used to encrypt data that is exchanged between the LDAP Gateway and the Reconciliation Agent and Provisioning Agent on the mainframe.

1.4.3 High Availability Feature of the Connector

The following are component-failure scenarios and the response of the connector to each scenario:

• Scenario 1: The Reconciliation Agent is running and the LDAP Gateway stops responding

  1. The Reconciliation Agent stops sending messages (event data) to the LDAP Gateway.

  2. Messages that are not sent are stored in the subpool cache.

  3. When the LDAP Gateway is brought back online, the Reconciliation Agent reads data from the subpool cache and then sends messages to the LDAP Gateway.

• Scenario 2: The LDAP Gateway is running and the Reconciliation Agent stops responding

  1. Event data is sent to the subpool cache.

  2. When the Reconciliation Agent is brought back online, it reads data from the subpool cache and then sends messages to the LDAP Gateway.

     Note:

     During SHUTDOWN, there is a possibility that events that had been sent to the LDAP might be saved and re-sent again once the agent is brought back online. This is to ensure that no data lose and this process will re-list the event data to provide the most current view.

• Scenario 3: The LDAP Gateway is running and the mainframe stops responding

  1. Messages that are in the subpool cache are written to disk.

  2. When the mainframe is brought back online, event data written to disk is again stored in the subpool cache.

  3. The Reconciliation Agent reads data from the subpool cache and then sends messages to the LDAP Gateway.

     Note:

     During SHUTDOWN, there is a possibility that events that had been sent to the LDAP might be saved and re-sent again once the Agent is brought back online. This is to ensure no data lose and this process will re-list the event data to provide the most current view.

• Scenario 4: The LDAP Gateway is running and the Provisioning Agent or mainframe stops responding

  The process task that sends provisioning data to the LDAP Gateway retries the task.

• Scenario 5: The subpool is stopped by an administrator

  If the subpool is stopped by an administrator, then it shuts down the Reconciliation Agent, thereby destroying any messages that are not transmitted. However, the messages in the AES-encrypted file are not affected and can be recovered.

1.5 Connector Objects Used During Reconciliation and Provisioning

The following sections provide information about connector objects used during reconciliation and provisioning:

• Section 1.5.1, "Supported Functions for Target Resource Reconciliation"

• Section 1.5.2, "Supported Functions for Provisioning"

• Section 1.5.3, "User Attributes for Target Resource Reconciliation and Provisioning"

• Section 1.5.4, "Group Attributes for Target Resource Reconciliation and Provisioning"

• Section 1.5.5, "Security Attributes for Provisioning"

• Section 1.5.6, "Dataset Profile Attributes for Provisioning"

• Section 1.5.7, "Resource Profile Attributes for Provisioning"

• Section 1.5.8, "Reconciliation Rule"

• Section 1.5.9, "Reconciliation Action Rules"

1.5.1 Supported Functions for Target Resource Reconciliation

The connector supports reconciliation of user data from the following events:

• Create user

• Modify user

• Revoke user

• Resume user

• Delete user

• Add user to group

• Delete user from group

1.5.2 Supported Functions for Provisioning

Table 1-2 lists the provisioning functions supported by the connector.

Table 1-2 Supported Provisioning Functions

Function	Description	Mainframe Command
Create users	Adds new user on IBM RACF	ADDUSER
Create groups	Adds new group on IBM RACF	ADDGRP
Modify users	Modifies user information on IBM RACF	ALTUSER
Change passwords	Changes user password on IBM RACF in response to password changes made on Oracle Identity Manager through user self-service	ALTUSER
Reset passwords	Resets user password on IBM RACF The passwords are reset by the administrator.	ALTUSER
Revoking user accounts	Sets IBM RACF user to a REVOKED state	ALTUSER
Resuming user accounts	Sets IBM RACF user to an ENABLED state	ALTUSER
Add user to group	Connects user with an IBM RACF group	CONNECT
Remove user from group	Disconnects user from an IBM RACF group	REMOVE
Permit user to dataset	Permits user to be part of the data set ACL and gives them access rights to the data set	PERMIT
Remove user from dataset	Removes user from the data set ACL	PERMIT
Permit user to access general resource	Permits user to be part of the resource ACL and gives them access rights to the resource	PERMIT
Remove user from general resource	Removes user from the resource ACL	PERMIT
Grant security attribute to user	Provides non-value security attribute privileges to user	ALTUSER
Grant user to TSO segment	Provides TSO access and information to user	ALTUSER
Grant user to OMVS segment	Provides OMVS information to users	ALTUSER
Delete User	Deletes user from IBM RACF	DELUSER

1.5.3 User Attributes for Target Resource Reconciliation and Provisioning

Table 1-3 lists attribute mappings between IBM RACF and Oracle Identity Manager for target resource reconciliation and provisioning. The OnBoardRacfUser and ModifyUser adapters are used for the Create User and Modify User provisioning operations, respectively.

Table 1-3 User Attributes for Target Resource Reconciliation and Provisioning

Process Form Field	IBM RACF Attribute	Description
cn	NAME	Full name You can specify the format in which Full Name values are stored on the target system. Step 2 of Section 3.5, "Installing and Configuring the LDAP Gateway" describes the procedure.
cicsOpclass	CICS_OPCLASS	Operator class
cicsOpident	CICS_OPIDENT	Operator ID
cicsOpprty	CICS_OPPRTY	Operator priority
cicsRslkey	CICS_RSLKEY	Resource key 0–99
cicsTimeout	CICS_TIMEOUT	Timeout value
cicsTslkey	CICS_TSLKEY	Type key 1–99
cicsXrfsoff	CICS_XRFSOFF	Transaction off (Force|NoForce)
dfltGrp	DEFAULT-GROUP	Default group for the user
instdata	DATA	Installation-defined data for the user
netviewConsname	NETVIEW_CONSNAME	Console name
netviewCtl	NETVIEW_CTL	Control
netviewDomains	NETVIEW_DOMAINS	Domain name
netviewIc	NETVIEW_IC	Command|Command List
netviewMsgrecvr	NETVIEW_MSGRECVR	Message receiver
netviewNgmfadmn	NETVIEW_NGMFADMN	Administration (Y|N)
netviewNgmfvspn	NETVIEW_NGMFVSPN	View span
netviewOpclass	NETVIEW_OPCLASS	Operator class
omvsAssizemax	OMVS_ASSIZEMAX	Address space size
omvsAutouid	OMVS_AUTOUID	Generate auto user identifier
omvsCputimemax	OMVS_CPUTIMEMAX	CPU time
omvsFileprocmax	OMVS_FILEPROCMAX	Files per process
omvsHome	HOME	Homelocation
omvsMemlimit	OMVS_MEMLIMIT	Non-shared memory size
omvsMmapareamax	OMVS_MMAPAREAMAX	Memory map size
omvsProcusermax	OMVS_PROCUSERMAX	Processes per UID
omvsProgram	PROGRAM	Program
omvsShared	OMVS_SHARED	Shared user identifier
omvsShmemmax	OMVS_SHMEMMAX	Shared memory size
omvsThreadsmax	OMVS_THREADSMAX	Threads per process
omvsUid	UID	UID
owner	OWNER	Owner of the user profile
resumeDate	RESUME DATE	Future date from which the user will be allowed access to the system
revokeDate	REVOKE DATE	Future date from which the user's access to the system will be revoked
revoke	REVOKE|RESUME	Status of the user
tsoAcctNum	ACCTNUM	Default TSO account number on the TSO/E logon panel
tsoCommand	COMMAND	Command to be run during TSO/E logon
tsoDest	DEST	Default SYSOUT destination
tsoHoldclass	HOLDCLASS	Default hold class
tsoJobclass	JOBCLASS	Default job class
tsoMaxSize	MAXSIZE	Maximum region size the user can request at logon
tsoMsgclass	MSGCLASS	Default message class
tsoProc	PROC	Default logon procedure on the TSO/E logon panel
tsoSize	SIZE	Minimum region size if not requested at logon
tsoSysoutclass	SYSOUTCLASS	Default SYSOUT class
tsoUnit	UNIT	Default UNIT name for allocations
tsoUserdata	USERDATA	TSO-defined data for the user
uid	USER	Login ID
userPassword	PASSWORD	Password used to log in
waaccnt	WAACCNT	Account number for APPC or IBM z/OS processing
waaddr1	WAADDR1	Address line 1 for SYSOUT delivery
waaddr2	WAADDR2	Address line 2 for SYSOUT delivery
waaddr3	WAADDR3	Address line 3 for SYSOUT delivery
waaddr4	WAADDR4	Address line 4 for SYSOUT delivery
wabldg	WABLDG	Building for SYSOUT delivery
wadept	WADEPT	Department for SYSOUT delivery
waname	WANAME	User name for SYSOUT delivery
waroom	WAROOM	Room for SYSOUT delivery

1.5.4 Group Attributes for Target Resource Reconciliation and Provisioning

The connector supports reconciliation and provisioning of the GROUP multivalued attribute. For any particular user, a child form is used to hold values of the GROUP attributes listed in the table. The AddUserToGroupR2 and RemoveUserFromGroupR2 adapters in Oracle Identity Manager are used for group provisioning operations.

Table 1-4 lists group attribute mappings between IBM RACF and Oracle Identity Manager.

Table 1-4 Group Attributes for Target Resource Reconciliation and Provisioning

Child Form Field	IBM RACF Attribute	Description
MEMBER_OF	GROUP	UID Of the group being assigned to User

1.5.5 Security Attributes for Provisioning

The connector supports provisioning of the SECURITY ATTRIBUTE multivalued attribute. For any particular user, a child form is used to hold values of the SECURITY ATTRIBUTE attributes listed in the table.

The following list shows the bit flag security attributes that are supported for provisioning operations between Oracle Identity Manager and IBM RACF:

• ADSP

• AUDITOR

• CICS

• DCE

• DFP

• EXPIRED

• GRPACC

• NETVIEW

• OIDCARD

• OMVS

• OPERATIONS

• OPERPARM

• OVM

• PROTECTED

• PROXY

• RESTRICTED

• SPECIAL

• TSO

• UAUDIT

Table 1-5 Security Attribute for Target Resource Reconciliation and Provisioning

Child Form Field	IBM RACF Attribute	Description
ATTRIBUTE	Security Attribute	Attribute access authority for user

1.5.6 Dataset Profile Attributes for Provisioning

The connector supports provisioning of the DATASET multivalued attribute. For any particular user, a child form is used to hold values of the DATASET attributes listed in the table.

Table 1-6 lists DATASET attribute mappings between IBM RACF and Oracle Identity Manager.

Table 1-6 DATASET Attribute Mappings

Child Form Field	IBM RACF Attribute	Description
Dataset Name	PROFILE NAME	Profile ID
Dataset Access	ACCESS	User's access level to the dataset
Dataset Generic	GENERIC	Treat the dataset as a generic name

1.5.7 Resource Profile Attributes for Provisioning

The connector supports reconciliation and provisioning of the RESOURCE PROFILE multivalued attribute. For any particular user, a child form is used to hold values of the RESOURCE PROFILE attributes listed in the table.

Table 1-7 Resource Profile Attributes for Target Resource Provisioning

Child Form Field	IBM RACF Attribute	Description
RESOURCE PROFILE ID	RESOURCE PROFILE NAME& CLASS NAME	Profile ID and class name combinations
RESOURCE ACCESS	RESOURCE ACCESS	User's access level to resource profile

1.5.8 Reconciliation Rule

See Also:

Defining Reconciliation Rules in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for generic information about reconciliation matching and action rules

During target resource reconciliation, Oracle Identity Manager tries to match each user profile fetched from IBM RACF with existing IBM RACF resources provisioned to OIM Users. This is known as process matching. A reconciliation rule is applied for process matching. If a process match is found, then changes made to the user profile on the target system are copied to the resource on Oracle Identity Manager. If no match is found, then Oracle Identity Manager tries to match the user profile against existing OIM Users. This is known as entity matching. The reconciliation rule is applied during this process. If an entity match is found, then an IBM RACF resource is provisioned to the OIM User. Data for the newly provisioned resource is copied from the user profile.

The following is the reconciliation rule for target resource reconciliation:

Rule name: IdfReconUserRule

Rule element: User Login Equals uid

In this rule element:

• User Login is the User ID field on the process form and the OIM User form.

• uid is the USER attribute on IBM RACF.

After you deploy the connector, you can view this reconciliation rule by performing the following steps:

1. On the Design Console, expand Development Tools and then double-click Reconciliation Rules.

2. Search for and open the IdfReconUserRule rule.

1.5.9 Reconciliation Action Rules

Reconciliation action rules specify actions that must be taken depending on whether or not matching IBM RACF resources or OIM Users are found when the reconciliation rule is applied. Table 1-8 lists the reconciliation action rules for this connector.

Table 1-8 Reconciliation Action Rules

Rule Condition	Action
No Matches Found	None
One Entity Match Found	Establish Link
One Process Match Found	Establish Link

Note:

No action is performed for rule conditions that are not predefined for this connector. You can define your own action rule for such rule conditions. For information about modifying or creating reconciliation action rules see Setting a Reconciliation Action Rule in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

After you deploy the connector, you can view the reconciliation action rules for target resource reconciliation by performing the following steps:

1. On the Design Console, expand Resource Management and double-click Resource Objects.

2. Search for and open the OIMRacfResourceObject resource object.

3. Click the Object Reconciliation tab, and then click the Reconciliation Action Rules tab. The Reconciliation Action Rules tab displays the action rules defined for this connector.