Establish security for cross-site z/OSMF REST requests

Description

z/OSMF includes a number of Representational State Transfer (REST) services, which are public APIs that an application can use to work with z/OS system resources and extract system data. The z/OSMF REST services are described in IBM z/OS Management Facility Programming Guide.

As of z/OS V2R3:
  • New HTTP custom header "X-CSRF-ZOSMF-HEADER" is required for all applications that issue cross-site requests to z/OSMF REST interfaces (both browser and non-browser applications). Further, for browser applications, the approved origin sites must be defined to your installation security "white list," as in previous releases.
  • z/OSMF server supports cross-origin resource sharing (CORS) in your enterprise. With this support, a web browser can issue REST requests to the z/OSMF server on your system without being automatically blocked as a potential cross-site request forgery (CSRF) attempt. To permit valid browser requests to the z/OSMF server, your installation must define the approved web browser origin sites to your installation security white list though your security manager, such as RACF.

Table 1 provides more details about this migration action. Use this information to plan your changes to the system.

Table 1. Information about this migration action
Element or feature: z/OSMF.
When change was introduced: z/OS V2R3.
Applies to migration from: z/OS V2R2 and z/OS V2R1.
Timing: Before installing z/OS V2R3.
Is the migration action required? Yes.
Target system hardware requirements: None.
Target system software requirements: None.
Other system (coexistence or fallback) requirements: None.
Restrictions: None.
System impacts: If this migration action is not followed, valid browser requests to the z/OSMF server can be blocked as a potential cross-site request forgery (CSRF) attempts.
Related IBM® Health Checker for z/OS® check: None.

Steps to take

z/OS V2R3 requires that you take the following actions to establish security for cross-site z/OSMF REST requests:
  1. Review your applications and identify those applications that use the z/OSMF REST services.
  2. For any applications that make cross-site requests to z/OSMF REST services, update the application by adding the following HTTP custom header to every cross-site request:
    X-CSRF-ZOSMF-HEADER
    This header can be set to any value or an empty string (""). This action is required for both browser and non-browser applications that issue cross-site REST requests to the z/OSMF server on your system.
  3. To enable REST calls from web browsers, create an exception by adding the browser origin sites to your installation's white list. An exception is required for every approved web browser application that is not running in the same host system and port as the target z/OSMF system. Non-browser applications, such as Java applications, require only the custom header (they do not require a "white list" definition).

    To create white list exceptions, work with your security administrator to create the appropriate authorizations in your z/OS security product. On a RACF system, for example, this work involves defining generic or discrete profiles for the remote sites in the ZMFAPLA class, and permitting the profiles to the z/OSMF REST interfaces.

    To define a profile for a remote site, use the following format:
    <SAF_PREFIX>.REST.<identifier>.<reversed-hostname>
    Where:
    • <SAF_PREFIX> is the SAF prefix for your z/OSMF configuration. By default, the prefix is IZUDFLT.
    • REST.<identifier> identifies the REST interface that is to be allowed for use by the remote site.

For the identifiers for each of the z/OSMF interfaces, see IBM z/OS Management Facility Programming Guide. To indicate all REST interfaces, specify an asterisk as the identifier.

Reference information

For more information, see IBM z/OS Management Facility Programming Guide.