Using the z/OSMF REST services

z/OSMF supports the use of Representational State Transfer (REST) APIs, which are public APIs that your application can use to work with system resources and extract system data. As with implementations of REST services on other platforms, the z/OSMF APIs allow for easy-to-use services that are language- and platform-independent, stateless, scalable, and easily parsed.

Processing overview

The z/OSMF REST services can be invoked by any hypertext transfer protocol (HTTP) client application, running on the z/OS® local system or a remote system. The services support requests in either of the following protocols: HTTP/1.0 or HTTP/1.1.

Conceptually, your application (the client) issues requests to the target system (z/OS) in the form of request messages. The product name is z/OS. Each request message consists of a request line, optionally followed by request headers (HTTP headers), an empty line, and an optional message body. The request line includes the HTTP method, such as GET, a Universal Resource Locator (URL) and, where appropriate, parameters that further qualify the request. The URL is required and must be URI-encoded as specified in RFC 2396. For more information about RFC 2396, see the Uniform Resource Identifiers (URI): Generic Syntax web page.

If the API determines that the request is valid, it performs the requested service. After the API performs the service, it creates an HTTP response. If the request is successful, this response takes the form of an HTTP 200 (OK) response and, if applicable, an object that contains a result set. Depending on which service was requested, the result set might be returned in a format that requires parsing by your program, for example, a JavaScript Object Notation (JSON) object. In other cases, results might be returned in another format, such as plain text or binary data. If the request is not successful, the response consists of a non-OK HTTP response code with details of the error that is provided in the form of a JSON object.

It is assumed that users of these services are familiar with the JSON standard and coding practices. The following references provide more helpful information:

Using the Swagger interface

You can use the Swagger interface to display information about the following z/OSMF REST APIs:
To enable the use of Swagger at your installation, you must define the Swagger resources in your external security manager, and grant READ access to the appropriate users and groups. Ask your security administrator to do the following:
  • You and z/OSMF administrators require READ access to the IZUDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers resource in the EJBROLE class. The following example shows RACF commands that grant the access:
    
RDEFINE EJBROLE IZUDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers  UACC(NONE)

PERMIT IZUDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers CLASS(EJBROLE) 
ID(IZUUSER) ACCESS(READ)

PERMIT IZUDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers CLASS(EJBROLE) 
ID(IZUADMIN) ACCESS(READ)
  • z/OSMF administrators require READ access to the IZUDFLT.com.ibm.ws.management.security.resource.Administrator resource in the EJBROLE class. The following example shows RACF commands that grant the access:
    
RDEFINE EJBROLE IZUDFLT.com.ibm.ws.management.security.resource.Administrator UACC(NONE)

PERMIT IZUDFLT.com.ibm.ws.management.security.resource.Administrator CLASS(EJBROLE) 
ID(IZUADMIN) ACCESS(READ)
After the access is defined, use this address in a web browser to display information about the REST APIs:
https://<hostname>:<port>/ibm/api/explorer

Supply the appropriate value for host name and port.

Authenticating to z/OSMF

The z/OSMF REST services API is a secure interface that requires authentication. z/OSMF supports the following methods for passing user credentials to the API:
  • Basic authentication
  • Certificate authentication

Basic authentication means that the client program provides a z/OS user ID and password in the header of the initial request.

The following topics describe each method of authentication:

Basic authentication

Your client program authenticates to the z/OSMF REST services API with a valid z/OS user ID and password.

Typically, authentication is done through the HTTP header included in each client request. However, you might also consider using a single sign-on technique, such as the following:
  1. On the first request to the server, the client request includes a basic HTTP authentication header that contains a valid user ID and password. The header property value pair should look like this example: 
    'Authorization':'Basic <encoding of userid:password>'
    where <encoding of userid:password> is a base 64 encoding of <userid>:<password>.
  2. On successful log-in, your application receives the following values in the response header:
    • HTTP status code 200
    • Lightweight Third Party Access (LTPA) token, which contains the credentials for your program. For z/OSMF, the token is a LtpaToken2 value, which supports strong encryption.
  3. On subsequent requests, your program supplies the LTPA token for authentication with the z/OSMF REST services API, instead of the basic HTTP authorization header. You can provide the LTPA token through the Cookie header property, for example:
    You can provide the LTPA token through the Cookie header property, for example: 
    'Cookie':'<ltpaToken2=<tokenvalue>'
    followed by the token, for example: 
    'Cookie': 'LtpaToken2=IExabotu2sfNbJij6rajHJcFiDi
1H0hml3yKvylwfJ4q8goCFEYH41FQNlAgdMMVP6/nVbH/IKw
0l5b7ZqWuZ8ndOYcECAJg1ss2Vq4q21C1jLvVGTyNLk6rvbgs
7oQWM98bSuAN1Qtvlrx9uZ8EY4GqqscaErQO9vrAhwgkcedWB
jn2lLNjl+G8olJA4uB+Cv5XamrUvziY2pcbCKjFjNt5EQ97Nf2
sBzvlanfrENhV9uOLRpw9DibrzKLh0R1fOrp5xySAe7Ery69
eynt4ItaVWCcpt+CYHFbpHpW/C7INWHeNcaNktr0DBmHh6EWl; '

Certificate authentication

Your client program authenticates to the z/OSMF REST services API with a certificate.

With a client certificate, your program can access z/OSMF without having to supply a user ID and password. If your client is browser-based, the certificate is stored in the browser itself. When you log in to z/OSMF, the server requests the certificate from your browser. If your browser stores more than one certificate, you might be prompted to select the correct one to use with z/OSMF. Otherwise, your browser sends the certificate to z/OSMF. After z/OSMF identifies you as the owner of the key that is associated with the certificate, a secure connection is established.

To use client certificate authentication for the z/OS jobs REST interface services, you:
  1. Create the certificate. You can create the certificate in RACF or import it into RACF.
  2. Distribute the certificate to the appropriate workstations, for example, FTP it in binary.
  3. Import the certificate into the browser, by using the procedure that is appropriate for that browser.

For more information about creating and managing digital certificates, see RACF and digital certificates. For an example, see Creating client browser certificates with a locally signed certificate .

Supported HTTP versions

The z/OSMF REST interface services support requests in either of the following protocols: HTTP/1.0 or HTTP/1.1

Usage considerations for the z/OSMF REST services

Observe the following considerations when you use the z/OSMF REST interfaces:
  • As with any z/OSMF task or function, the REST services compete for z/OSMF resources with users of the z/OSMF web browser interface. Thus, concurrent high usage of the REST services can affect response time for users of the z/OSMF web browser interface.
  • During periods of concurrent high usage of the REST services, an application can experience connection failures, such as connection refused, connection timed out, or connection reset. In these cases, the application should try the request again. The number of retry attempts needed depends on how much work is being requested of the server. It might be necessary for your installation to modify the workload and reduce the arrival rate of requests.
  • Some browsing environments do not support all of the HTTP methods, such as HTML 4 or XHTML 1, or might block applications from accessing response content that has a non-successful HTTP response status code (4nn and 5nn). As a workaround, your application can use the following custom HTTP request headers:
    X-IBM-Requested-Method:
    GET, PUT, and DELETE requests can be "tunneled" through a POST method by using this custom HTTP header.
    X-IBM-Bypass-Status:
    If set to true, all response status codes are set to 200, and the custom HTTP response header X-IBM-Actual-Status is included in the returned data. To determine the original status code, your application must check the X-IBM-Actual-Status header.

Timestamp data type

The timestamp data type is used in the definition of some data models and notification message formats in the z/OSMF REST services APIs. Where it appears in this document, the timestamp data type is used to mean a non-negative Long integer quantity where the value represents a date and time that is expressed as the number of milliseconds since midnight on January 1, 1970 UTC.

Enabling browser log in through a client certificate

It is possible to run the z/OS jobs REST interface services directly from a web browser. Here, you must first authenticate to z/OSMF through your browser. In z/OSMF, authentication is typically done by entering your user ID and password at the Welcome page. However, it is also possible to log in with a client certificate, if your installation favors this approach. With a client certificate, you can access z/OSMF through your browser without having to supply a user ID and password.

When a client certificate is created, it requires security associations. For example, on a system with RACF installed, your client certificate can be associated with a RACF user ID. After the user ID is associated with the client certificate, the certificate can be exported. You must get the client certificate from the server side by using the FTP command and typing in the host name or IP address of the server. When prompted, enter your user ID and password, and use the bin command to transfer the file in binary format. Then, import the client certificate into the client's browser.

In client certificate authentication, the certificate is stored in the browser itself. When you log in to z/OSMF, the server requests the certificate from your browser. If your browser stores more than one certificate, you might be prompted to select the correct one to use with z/OSMF. Otherwise, your browser sends the certificate to z/OSMF. After z/OSMF identifies you as the owner of the key that is associated with the certificate, a secure connection is established.

If z/OSMF does not accept your client certificate, z/OSMF displays the Welcome page for you to enter your user ID and password.

If your installation plans to enable client certificate login for the z/OS jobs REST interface services, understand that it is your responsibility to create the certificate and manage its distribution to users. It is recommended that you ensure that users have browsers that support importing a certificate.

For more information about creating digital certificates, see z/OS Security Server RACF Security Administrator's Guide.

Allowing cross-site access to REST services

The z/OSMF REST services can be accessed by an HTTP client application, or by a web application that is running on the same host system. By default, z/OSMF blocks access attempts from web applications on other host systems. In such cases, the request is failed with error message IZUG846W, which indicates that a cross-site request forgery (CSRF) was attempted. In security terminology, a CSRF is a type of malicious attack on a website in which the attacker sends unauthorized commands to a web server or web application from a user that the server or application trusts.

You can enable your applications to make cross-site z/OSMF REST requests. To do so, you must perform the following steps:
  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 (""). It is required in both browser and non-browser applications.
  3. Because most modern web browsers block cross-site access due to same origin restrictions, an extra step is required for browser applications — you must define the origin site of the web application to your installation security "white list." Instructions for doing so are provided in Enabling cross-origin resource sharing (CORS) for REST services.

    Non-browser applications, such as Java applications, require only the custom header. They do not require a "white list" definition.

Note: z/OSMF includes the parmlib member IZUPRMxx, which your installation can use to override the z/OSMF default settings. IZUPRMxx includes the setting CSRF_SWITCH=ON|OFF to allow for disabling CSRF checking for all requests to the z/OSMF server. By default, CSRF_SWITCH is set to ON to ensure that your installation is protected against CSRF attacks. However, in some limited cases, such as for testing, you might choose to temporarily disable CSRF checking by setting CSRF_SWITCH=OFF. It is recommended, however, that you leave this setting enabled to prevent CSRF attacks.

Enabling cross-origin resource sharing (CORS) for REST services

Your installation can allow browser applications from certain, trusted sites to access z/OSMF REST services on the host system. If so, you must enable cross-origin resource sharing (CORS) on the host system. This work involves creating a "white list" of exceptions (the trusted sites), and enabling those exceptions in your external security manager.

Identify which sites are to be allowed, and which REST interfaces are to be made available for cross-site access. Then, work with your security administrator to create the appropriate authorizations in your external security manager. In a RACF installation, for example, define generic or discrete profiles for the remote sites in the ZMFAPLA class, and permit 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. Table 1 shows the identifiers for each of the z/OSMF interfaces. To indicate all REST interfaces, specify an asterisk (*) as the identifier.
    Table 1. SAF identifiers for the z/OSMF REST interfaces
    REST interface Identifier
    Application Linking Manager interface services APPLINK
    Application server routing services GATEWAY
    Cloud provisioning services PROVISIONING
    Data persistence services PERSIST
    Multisystem routing services GATEWAY
    MVS subsystem services FILES
    Software management services SWMGMT
    Topology services SYSTEM
    TSO/E address space services TSO
    z/OS console REST interface services CONSOLE
    z/OS data set and file REST interface services FILES
    z/OS jobs REST interface services JOBS
    z/OSMF workflow services WORKFLOW
  • <reversed-hostname> is the site’s fully qualified domain name in reverse, for example, the domain WWW.IBM.COM would be specified as COM.IBM.WWW. Use uppercase letters for any alphabetic characters in the profile. Specify a domain name only; not the full URL. Omit the protocol (HTTP:// or HTTPS://).

    If the site is known by an IP address, specify the IP address in reverse. For any IP addresses that you define, it is recommended that you create a discrete profile (without wildcards) for each address. Use a valid "dotted decimal" Internet Protocol version 4 (IPv4) address. IPv6 addresses and internationalized domain name (IDN) addresses are not supported.

    Though not recommended, you can use generic profiles with wildcard characters to allow access from multiple domains or subdomains. You might do so temporarily to allow for internal testing of the REST interfaces across multiple sandbox systems.

For example, assume that your installation wants to allow a web browser application on the site “lab2.ibm.com” to send requests for z/OS jobs REST interface services on the site “lab1.ibm.com.” To allow a web browser application to issue cross-site requests from the "lab2" site, your RACF security administrator would create the authorization on the "lab1.ibm.com site," as follows:
  1. Create a profile for the "lab2.ibm.com" site in the ZMFAPLA class. In the profile, include the identifier to represent the resource (the REST interface), for example, JOBS to indicate the z/OS jobs REST interface. In RACF, enter the RDEFINE command, as follows:
    RDEFINE ZMFAPLA IZUDFLT.REST.JOBS.COM.IBM.LAB2 UACC(NONE)
    To allow this cross-site access for all of the REST interfaces, specify a wildcard (*) in place of a specific resource identifier. For example: 
    RDEFINE ZMFAPLA IZUDFLT.REST.*.COM.IBM.LAB2 UACC(NONE)
  2. Ensure that the z/OSMF server user ID (by default, IZUSVR) has READ access to the profile. In RACF, enter the PERMIT command, as follows: 
    PERMIT IZUDFLT.REST.JOBS.COM.IBM.LAB2 CLASS(ZMFAPLA) ID(IZUSVR) ACCESS(READ)
  3. Refresh the ZMFAPLA class. In RACF, enter the SETROPTS command, as follows: 
    SETROPTS RACLIST(ZMFAPLA) REFRESH
Note: These settings do not override the security settings in your browser. For more information about cross-origin resource sharing (CORS), see the documentation for the web browser.