Configuring Java applications to use the z/OS Identity Cache

The main application interface to the z/OS Identity Cache is the ICTX Java API described in more detail in ICTX Java API. Applications can use the API to access the Identity Cache on the local z/OS system or on a remote z/OS system.

To use the ICTX Java API to access a z/OS Identity Cache on either the local or a remote z/OS system, all applications must:
  • have access to the ICTX Java classes defined in the ictx.jar file, which is located in the /usr/lpp/eim/lib HFS directory. To get access to the ICTX Java classes, include the ictx.jar file in the CLASSPATH of the Java application.
  • have a RACF user ID on the z/OS system where the Identity Cache is located, and the permission necessary to access the Identity Cache. The ICTX Java API uses the R_cacheserv callable service to perform read and write operations to the Identity Cache. Use of the R_cacheserv callable service is authorized by the IRR.RCACHESERV.ICTX resource in the FACILITY class, so the RACF user ID associated with the request to access the Identity Cache must have the correct access permission to the IRR.RCACHESERV.ICTX resource in the FACILITY class.
    • If the application is a z/OS application accessing the Identity Cache on the local system, then the RACF user ID associated with the request is the one under which the application is running.
    • If the application is running on a z/OS or non-z/OS system and accessing the Identity Cache on a remote z/OS system, it will be accessing the remote system's Identity Cache through an IBM TDS server. In this case, the RACF user ID associated with the request is the RACF user ID used to authenticate with the remote z/OS system through an LDAP bind operation.
    The level of access permission required to access the IRR.RCACHESERV.ICTX resource in the FACILITY class depends on the specific type of operation the application needs to perform.
    • If the application is going to store user information in the Identity Cache, then the RACF user ID needs UPDATE access to the IRR.RCACHESERV.ICTX resource in the FACILITY class.
    • If the application is going to retrieve information from the Identity Cache (using either the ICTX Java API, the RACROUTE REQUEST=VERIFY macro, or the initACEE SAF callable service), then the RACF user ID needs READ access to the IRR.RCACHESERV.ICTX resource in the FACILITY class.
    The FACILITY class must be active and enabled for RACLIST processing. Access updates for a user will not take effect until the user logs on again.
In addition to the preceding configuration requirements common to all Java applications, additional configuration requirements vary depending on whether the application is accessing the Identity Cache on the local or on a remote z/OS system.
  • If the application will be accessing the Identity Cache on the local z/OS system, it must also have access to the EIM and ICTX API routines. To get access to these routines, include the HFS directory /usr/lpp/eim/lib in the LIBPATH of the z/OS Java application.
  • If the application will be accessing the Identity Cache on a remote z/OS system, it must also specify:
    • the host name and, optionally, the port number for the z/OS IBM TDS server that is providing the connection to the z/OS Identity Cache on the remote system. This host name may begin with ldap:// or ldaps://. If ldaps:// is used, then it is assumed the IBM TDS server as been set up for SSL or TLS communication.
      • If the application is running on a z/OS system, the host name for the z/OS IBM TDS server can be set as an in-storage Identity Cache default value (as described in Configuring Identity Cache connection defaults).
      • If the application is running on a non-z/OS system, the host name for the z/OS IBM TDS server could be obtained from a properties file specific to the application.
    • the bind credentials for connecting to the remote system. The bind credentials correspond to a RACF user ID and password on the remote system. If the application is running on a z/OS system, the bind credentials can be set as in-storage Identity Cache default values (as described in Configuring Identity Cache connection defaults).

    The z/OS IBM TDS server needs to have been configured with ICTX extended operations and started. To configure the z/OS IBM TDS server with ICTX extended operations, modify the ds.conf file with a section that defines the ICTX extended operations support. For more information, refer to Configuring the IBM Tivoli Directory Server for remote services support.