IDM 7.2.2

IBM RACF connector

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 RACF segments and attributes 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.15.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:

  1. Select Configure > Connectors and click New Connector.

  2. Enter a Connector Name.

  3. Select RACF Connector - 1.5.20.15 as the Connector Type.

  4. Provide the Base Connector Details.

  5. Click Save.

After the connector is configured, it displays as Active in the admin UI.

You can test 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": "[1.5.0.0,1.6.0.0)",
    "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.

Account attributes

The following attributes are available to the __ACCOUNT__ resource object:

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:

Group attributes
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 "Content-Type: application/json" \
--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"
}

When you create a new user, you must specify at least __NAME__ and userId. Refer to the list of available attributes 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 a list of attributes, refer to RACF segments and attributes.

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 "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 "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 "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 "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"
}

While the __PASSWORD__ field is not returned as part of the response, the user object is updated.
Delete a RACF 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 "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. For additional details, see ICF 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 Encrypted(1) Required(2)

hostName

String

null

Yes

Host name or IP address of RACF

port

Integer

null

Yes

TCP/IP port number used to communicate with the RACF

userId

String

null

Yes

The user id used to login to RACF

password

GuardedString

null

Yes

Yes

The password used to login to RACF

segments

String

null

No

To retrieve data based on RACF segments

acceptSelfSignedCertificates

boolean

false

Yes

Accept or not self-signed certificates

clientCertAlias

String

null

No

Alias for the client certificate

clientCertPassword

GuardedString

null

Yes

No

Password for the client certificate

maximumConnections

Integer

10

No

Provide the maximum connections

connectionTimeout

Integer

300

No

Provide the maximum connection timeout in seconds

httpProxyHost

String

null

No

Provide the Proxy Host

httpProxyPort

Integer

null

No

Provide the Proxy Port

httpProxyUsername

String

null

No

Provide the Proxy Username

httpProxyPassword

GuardedString

null

Yes

No

Provide the Proxy Password

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.