IBM RACF Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

IBM Resource Access Control Facility (RACF) is an access control system for IBM mainframes running z/OS. The RACF connector lets you manage and synchronize accounts between RACF and IDM managed user objects. A RACF administrator account is required for this connector to work.

Before you start

Before you configure the connector, log in to your RACF administrator account and note the following:

Host name: The domain name or IP address of the host where RACF is running.
Port: The port RACF is configured to use.
User ID: The RACF administrator user ID.
Password: The password for the RACF administrator account.
Segments: A list of RACF user profile segments that are supported. Refer to ??? for a list of available segments.
Accept self-signed certificates: A boolean determining whether RACF is configured to allow self-signed certificates. This should usually be false in production environments, but may be true during development.
Client certificate alias: Alias name for the client certificate.
Client certificate password: Password for the client certificate.

Install the RACF connector

Download the connector .jar file from the ForgeRock BackStage download site.

If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:
```
mv ~/Downloads/racf-connector-1.5.20.12.jar /path/to/openidm/connectors/
```
If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the RACF connector

Create a connector configuration using the Admin UI:

Select Configure > Connectors and click New Connector.
Enter a Connector Name.
Select RACF Connector - 1.5.20.12 as the Connector Type.
Provide the Base Connector Details.
Click Save.

When your connector is configured correctly, the connector displays as Active in the Admin UI.

Alternatively, test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/racf?_action=test"
{
  "name": "racf",
  "enabled": true,
  "config": "config/provisioner.openicf/racf",
  "connectorRef": {
    "bundleVersion": "${bundleVersion}",
    "bundleName": "org.forgerock.openicf.connectors.racf-connector",
    "connectorName": "org.forgerock.openicf.connectors.racf.RacfConnector"
  },
  "displayName": "RACF Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the RACF system.

RACF segments and attributes

The following tables list available attributes by segment. Attributes listed in the Base segment are available by default. To use any other attributes, include the segment name in the list of segments in the RACF connector configuration.

User accounts support create, update, query, and delete actions. Groups only support query actions.

Base segment

Attribute	Description
`userId`	The user's ID. Required.
`__NAME__`	The user's system name. Must match `userId`. Required.
`NAME`	The user's name.
`OWNER`	Owner of the user's profile.
`DFLTGRP`	Default group of the user.
`AUTHORITY`	User's authority in the default group.
`__PASSWORD__`	The user's password.
`PHRASE`	Optional password phrase.
`REVOKE`	Expiration date for the user's system access.
`RESUME`	Date a user's system access is restored.
`WHEN`	Days of the week and hours of the day the user has access to the system.
`CLAUTH`	Classes in which the user can define profiles.
`MODEL`	Name of the data model profile used when creating new data profiles (either generic or discrete).
`GROUP`	The group the user belongs to.
`SECLABEL`	The user's default security label.
`GRPACC`	Whether other group members have access to any other group set the user protects.
`RESTRICTED`	Indicates that when checking global access, the account will not be used to allow access to a resource.
`AUDITOR`	Gives the user the system-wide auditor attribute.
`OPERATIONS`	Gives the user the system-wide operations attribute.
`SPECIAL`	Gives the user the system-wide special attribute.
`ADSP`	Indicates all permanent data sets this user creates should be discrete profiles in RACF.

CICS segment

Attribute	Description
`CICS_OPCLASS`	The classes the user is assigned in CICS. Determines which basic mapping support (BMS) messages are routed to the user. Represented as a number ranging from `01` to `24`.
`CICS_OPIDENT`	A 1-3 character identification of the user for use by BMS.
`CICS_OPPRTY`	The number (`0` to `255`) that represents the priority of the user.
`CICS_RSLKEY`	The resource security level (RSL) keys assigned to the user.
`CICS_TIMEOUT`	The time in hours and minutes (either `HMM` or `HHMM` format) that the operator is allowed to be idle before being signed out.
`CICS_TSLKEY`	The transaction security level (TLS) keys assigned to the user.
`CICS_XRFSOFF`	Indicates whether the user should be signed out when an XRF takeover occurs.

DCE segment

Attribute	Description
`DCE_AUTOLOGIN`	Single Sign On (SSO) processing. Either `YES` or `NO`.
`DCE_DCENAME`	The user's DCE principal name.
`DCE_HOMECELL`	The user's DCE home cell.
`DCE_HOMEUUID`	The user's DCE UUID.
`DCE_UUID`	The user's principal DCE UUID.

DFP segment

Attribute	Description
`DFP_DATAAPPL`	The user's DFP data application identifier.
`DFP_DATACLAS`	The user's default data class for attributes used during allocation of any new data sets.
`DFP_MGMTCLAS`	The user's default management class for attributes used in managing a data set after it is allocated.
`DFP_STORCLAS`	The user's default storage class for logical storage attributes.

KERB segment

Attribute	Description
`KERB_ENCRYPT`	The user's encryption key types. Available values include: `DES`, `DES3`, `DESD`, `AES128`, and `AES256`.
`KERB_KERBNAME`	The user's local principal name. The value specified must be unique.
`KERB_MAXTKTLFE`	The maximum Kerberos ticket life specified in seconds. Note that `0` is not a valid value.

LANGUAGE segment

Attribute	Description
`LANGUAGE_PRIMARY`	The user's primary language.
`LANGUAGE_SECONDARY`	The user's secondary language.

LNOTES segment

Attribute	Description
`LNOTES_SNAME`	The user's short name for use with Lotus Notes in z/OS.

NDS segment

Attribute	Description
`NDS_UNAME`	The user's name for use with Novell Directory Services.

NETVIEW segment

Attribute	Description
`NETVIEW_CONSNAME`	Master Console Station (MCS) console identifier.
`NETVIEW_CTL`	Specifies whether a security check is performed for this user. Either `GLOBAL`, `GENERAL`, or `SPECIFIC`.
`NETVIEW_DOMAINS`	The domain identifier for any domains where the user can start a cross-domain session.
`NETVIEW_IC`	The initial command or list of commands to be executed by NetView when the user logs in.
`NETVIEW_MSGRECVR`	Indicates whether the user can receive unsolicited messages.
`NETVIEW_NGMFADMN`	Indicates whether the user can use the NetView graphic monitor facility.
`NETVIEW_OPCLASS`	NetView scope classes the user has authority with. The class value is a number from `1` to `2040`.

OMVS segment

Attribute	Description
`OMVS_ASSIZEMAX`	The user's z/OS maximum address space size.
`OMVS_CPUTIMEMAX`	The user's z/OS maximum CPU time allowed.
`OMVS_FILEPROCMAX`	The user's z/OS maximum number of files allowed per process.
`OMVS_HOME`	The user's z/OS home directory path.
`OMVS_MEMLIMIT`	The user's z/OS non-shared memory size limit.
`OMVS_MMAPAREAMAX`	The user's z/OS maximum memory map size.
`OMVS_PROCUSERMAX`	The user's maximum number of processes per UID in z/OS.
`OMVS_PROGRAM`	The user's z/OS path name, such as a default shell program.
`OMVS_SHMEMMAX`	The user's z/OS maximum shared memory size.
`OMVS_THREADSMAX`	The user's z/OS maximum number of threads per process.
`OMVS_UID`	The user's z/OS user ID.

OPERPARM segment

Attribute	Description
`OPERPARM_ALTGRP`	Alternative console group used for recovery.
`OPERPARM_AUTH`	The user's command authority.
`OPERPARM_CMDSYS`	Name of the system to which the user is connected for command processing.
`OPERPARM_DOM`	Indicates whether the console can receive delete operator message (DOM) requests.
`OPERPARM_HC`	Indicates whether this console should receive all messages that are directed to hardcopy.
`OPERPARM_INTIDS`	Indicates whether or not a console should receive messages directed to the internal console.
`OPERPARM_KEY`	Indicates a data retrieval key used to search for user consoles using the `DISPLAY CONSOLES` command.
`OPERPARM_LEVEL`	Message level the user should receive. Available values include `R`, `I`, `CE`, `E`, `IN`, `NB`, or `ALL`. If you specify `ALL`, you cannot specify `R`, `I`, `CE`, `E`, or `IN`.
`OPERPARM_LOGCMDRESP`	Indicates whether command responses received by the user are logged.
`OPERPARM_MFORM`	Specifies the format messages are displayed in. Available values include `J`, `M`, `S`, `T`, and `X`.
`OPERPARM_MIGID`	Indicates whether the user should receive a migration console ID.
`OPERPARM_MONITOR`	List of events the user can monitor.
`OPERPARM_MSCOPE`	List of the systems this console can receive unsolicited messages from.
`OPERPARM_ROUTCODE`	Routing codes for messages this console receives.
`OPERPARM_STORAGE`	The amount of virtual storage (in megabytes) the console is allowed for message queuing.
`OPERPARM_UD`	Specifies whether this console should receive undelivered messages.
`OPERPARM_UNKNIDS`	Indicates whether a console should receive messages directed to unknown console IDs.

OVM segment

Attribute	Description
`OVM_UID`	The user's OpenExtensions for z/VM user ID.
`OVM_FSROOT`	The user's OpenExtensions for z/VM file system root directory path.
`OVM_HOME`	The user's OpenExtensions for z/VM home directory path.
`OVM_PROGRAM`	The user's OpenExtensions for z/VM program path, such as a default shell program.

PROXY segment

Attribute	Description
`PROXY_LDAPHOST`	The URL of the LDAP server which the z/OS LDAP server contacts when acting as a proxy.
`PROXY_BINDDN`	The distinguished name (DN) which the z/OS LDAP server uses when acting as a proxy.

TSO segment

Attribute	Description
`TSO_ACCTNUM`	The user's default TSO account number.
`TSO_HOLDCLASS`	The user's default hold class.
`TSO_JOBCLASS`	The user's default job class.
`TSO_MAXSIZE`	The user's maximum region size.
`TSO_MSGCLASS`	The user's default message class.
`TSO_PROC`	The name of the user's default login procedure.
`TSO_SIZE`	The user's default region size.

WORKATTR segment

Attribute	Description
`WORKATTR_WANAME`	User name on `SYSOUT`.
`WORKATTR_WABLDG`	Building on `SYSOUT`.
`WORKATTR_WADEPT`	Department on `SYSOUT`.
`WORKATTR_WAROOM`	Room on `SYSOUT`.
`WORKATTR_WAADDR1`	`SYSOUT` address line 1.
`WORKATTR_WAADDR2`	`SYSOUT` address line 2.
`WORKATTR_WAADDR3`	`SYSOUT` address line 3.
`WORKATTR_WAADDR4`	`SYSOUT` address line 4.
`WORKATTR_WAACCNT`	Account number.
`WORKATTR_WAEMAIL`	User email address.

Group attributes

The following attributes are available to the __GROUP__ resource object:

Attribute	Description
`UID`	ID of the group.
`__NAME__`	Name of the group.
`OWNER`	Owner of the group.
`SUBGROUP`	List of subgroups part of this group.
`SUPGROUP`	List of groups this group is part of.
`USERS`	List of users part of this group.

Use the RACF connector

You can use the RACF connector to perform the following actions on a RACF account:

Create a RACF user

The following example creates a user with the minimum required attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "__NAME__": "BJENSEN",
  "userId": "BJENSEN"
}' \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__?_action=create"
{
  "_id": "BJENSEN",
  "NAME": "UNKNOWN",
  "LAST-ACCESS": "UNKNOWN",
  "DFLTGRP": "SYS1",
  "WHEN": {
    "DAYS": "ANYDAY",
    "TIME": "ANYTIME"
  },
  "PASS-INTERVAL": "N/A",
  "PHRASEDATE": "N/A",
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "SECLABEL": "NONE SPECIFIED",
  "userId": "BJENSEN",
  "ATTRIBUTES": [
    "PROTECTED"
  ],
  "PASSDATE": "N/A",
  "SECLEVEL": "NONE SPECIFIED",
  "__GROUP__": [
    {
      "GROUP": "SYS1",
      "OWNER": "IBMUSER",
      "AUTH": "USE",
      "UACC": "NONE"
    }
  ],
  "OWNER": "IBMUSER"
}

Note

When you create a new user, you must specify at least __NAME__, userId. Refer to the list of available attributes above for more information.

Update a RACF user

You can modify an existing user with a PUT request, including all attributes of the account in the request.

For example, to add a work email and update the name of the user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{
  "__NAME__": "BJENSEN",
  "userId": "BJENSEN",
  "WORKATTR_WAEMAIL": "bjensen@example.com",
  "NAME": "Barbara Jensen"
}' \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__/BJENSEN"
{
  "_id": "BJENSEN",
  "NAME": "BARBARA JENSEN",
  "LAST-ACCESS": "UNKNOWN",
  "DFLTGRP": "SYS1",
  "WORKATTR_WAEMAIL": "bjensen@example.com",
  "WHEN": {
    "DAYS": "ANYDAY",
    "TIME": "ANYTIME"
  },
  "PASS-INTERVAL": "N/A",
  "PHRASEDATE": "N/A",
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "SECLABEL": "NONE SPECIFIED",
  "userId": "BJENSEN",
  "ATTRIBUTES": [
    "PROTECTED"
  ],
  "PASSDATE": "N/A",
  "SECLEVEL": "NONE SPECIFIED",
  "__GROUP__": [
    {
      "GROUP": "SYS1",
      "OWNER": "IBMUSER",
      "AUTH": "USE",
      "UACC": "NONE"
    }
  ],
  "OWNER": "IBMUSER"
}

Query RACF users

The following example queries all RACF users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "ADCDY"
    },
    {
      "_id": "ADCDZ"
    },
    {
      "_id": "BJENSEN"
    },
    {
      "_id": "BPXOINIT"
    },
    {
      "_id": "CEA"
    },
    {
      "_id": "CFZSRV"
    },
    {
      "_id": "CICSUSER"
    },
    {
      "_id": "DANY101"
    },
    {
      "_id": "DANY102"
    },
    [ ... ]
    {
      "_id": "ZOSCAGL"
    },
    {
      "_id": "ZOSCSRV"
    },
    {
      "_id": "ZOSMFAD"
    },
    {
      "_id": "ZOSUGST"
    },
    {
      "_id": "ZWESIUSR"
    },
    {
      "_id": "ZWESVUSR"
    }
  ],
  "resultCount": 162,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The following command queries a specific user by their ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__/BJENSEN"
{
  "_id": "BJENSEN",
  "NAME": "BARBARA JENSEN",
  "LAST-ACCESS": "UNKNOWN",
  "DFLTGRP": "SYS1",
  "WORKATTR_WAEMAIL": "bjensen@example.com",
  "WHEN": {
    "DAYS": "ANYDAY",
    "TIME": "ANYTIME"
  },
  "PASS-INTERVAL": "N/A",
  "PHRASEDATE": "N/A",
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "SECLABEL": "NONE SPECIFIED",
  "userId": "BJENSEN",
  "ATTRIBUTES": [
    "PROTECTED"
  ],
  "PASSDATE": "N/A",
  "SECLEVEL": "NONE SPECIFIED",
  "__GROUP__": [
    {
      "GROUP": "SYS1",
      "OWNER": "IBMUSER",
      "AUTH": "USE",
      "UACC": "NONE"
    }
  ],
  "OWNER": "IBMUSER"
}

Reset a RACF account password

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PATCH \
--data '[{
  "operation": "add",
  "field": "__PASSWORD__",
  "value": "Passw0rd@123!"
}]' \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__/BJENSEN"
{
  "_id": "BJENSEN",
  "NAME": "BARBARA JENSEN",
  "LAST-ACCESS": "22.304/12:17:39",
  "DFLTGRP": "SYS1",
  "WORKATTR_WAEMAIL": "bjensen@example.com",
  "WHEN": {
    "DAYS": "ANYDAY",
    "TIME": "ANYTIME"
  },
  "PASS-INTERVAL": "180",
  "PHRASEDATE": "00.000",
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "SECLABEL": "NONE SPECIFIED",
  "userId": "BJENSEN",
  "ATTRIBUTES": [
    "NOPASSWORD",
    "PASSPHRASE"
  ],
  "PASSDATE": "N/A",
  "SECLEVEL": "NONE SPECIFIED",
  "__GROUP__": [
    {
      "GROUP": "SYS1",
      "OWNER": "IBMUSER",
      "AUTH": "USE",
      "UACC": "NONE"
    }
  ],
  "OWNER": "IBMUSER"
}

Note

While the __PASSWORD__ field is not returned as part of the response, the user object is updated.

Delete a RACF user account

You can use the RACF connector to delete an account from the RACF service.

The following example deletes a RACF account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/racf/__ACCOUNT__/BJENSEN"
{
  "_id": "BJENSEN",
  "NAME": "BARBARA JENSEN",
  "LAST-ACCESS": "22.304/12:17:39",
  "DFLTGRP": "SYS1",
  "WORKATTR_WAEMAIL": "bjensen@example.com",
  "WHEN": {
    "DAYS": "ANYDAY",
    "TIME": "ANYTIME"
  },
  "PASS-INTERVAL": "180",
  "PHRASEDATE": "00.000",
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "SECLABEL": "NONE SPECIFIED",
  "userId": "BJENSEN",
  "ATTRIBUTES": [
    "NOPASSWORD",
    "PASSPHRASE"
  ],
  "PASSDATE": "N/A",
  "SECLEVEL": "NONE SPECIFIED",
  "__GROUP__": [
    {
      "GROUP": "SYS1",
      "OWNER": "IBMUSER",
      "AUTH": "USE",
      "UACC": "NONE"
    }
  ],
  "OWNER": "IBMUSER"
}

OpenICF Interfaces Implemented by the RACF Connector

The RACF Connector implements the following OpenICF interfaces.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:

The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
The script has access to any script-arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

RACF Connector Configuration

The RACF Connector has the following configurable properties.

Configuration properties

Property	Type	Default
`hostName`	`String`	`null`
Host name or IP address of RACF

`port`	`Integer`	`null`
TCP/IP port number used to communicate with the RACF

`userId`	`String`	`null`
The user id used to login to RACF

`password`	`GuardedString`	`null`
The password used to login to RACF

`segments`	`String`	`null`
To retrieve data based on RACF segments

`acceptSelfSignedCertificates`	`boolean`	`false`
Accept or not self-signed certificates

`clientCertAlias`	`String`	`null`
Alias for the client certificate

`clientCertPassword`	`GuardedString`	`null`
Password for the client certificate

`maximumConnections`	`Integer`	`10`
Provide the maximum connections

`connectionTimeout`	`Integer`	`300`
Provide the maximum connection timeout in seconds

`httpProxyHost`	`String`	`null`
Provide the Proxy Host

`httpProxyPort`	`Integer`	`null`
Provide the Proxy Port

`httpProxyUsername`	`String`	`null`
Provide the Proxy Username

`httpProxyPassword`	`GuardedString`	`null`
Provide the Proxy Password

^[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. ^[b] A list of operations in this column indicates that the property is required for those operations.