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.
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.
- Hypertext Transfer Protocol 1.1: http://www.w3.org/Protocols/
- Multipurpose Internet Mail Extensions (MIME) media types: http://www.iana.org/assignments/media-types/index.html
- Introducing JSON: http://www.json.org.
Using the Swagger interface
- 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
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
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)
Supply the appropriate value for host name and port.
Authenticating to z/OSMF
- 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.
Your client program authenticates to the z/OSMF REST services API with a valid z/OS user ID and password.
- 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
'Authorization':'Basic <encoding of userid:password>'
<encoding of userid:password>is a base 64 encoding of
- 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.
- 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:
followed by the token, for example:
'Cookie': 'LtpaToken2=IExabotu2sfNbJij6rajHJcFiDi 1H0hml3yKvylwfJ4q8goCFEYH41FQNlAgdMMVP6/nVbH/IKw 0l5b7ZqWuZ8ndOYcECAJg1ss2Vq4q21C1jLvVGTyNLk6rvbgs 7oQWM98bSuAN1Qtvlrx9uZ8EY4GqqscaErQO9vrAhwgkcedWB jn2lLNjl+G8olJA4uB+Cv5XamrUvziY2pcbCKjFjNt5EQ97Nf2 sBzvlanfrENhV9uOLRpw9DibrzKLh0R1fOrp5xySAe7Ery69 eynt4ItaVWCcpt+CYHFbpHpW/C7INWHeNcaNktr0DBmHh6EWl; '
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.
- Create the certificate. You can create the certificate in RACF or import it into RACF.
- Distribute the certificate to the appropriate workstations, for example, FTP it in binary.
- 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
- 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:
- GET, PUT, and DELETE requests can be "tunneled" through a POST method by using this custom HTTP header.
- 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.
- Review your applications and identify those applications that use the z/OSMF REST services.
- 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:
- This header can be set to any value or an empty string (""). It is required in both browser and non-browser applications.
- 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.
CSRF_SWITCH=ON|OFFto 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.
<SAF_PREFIX>is the SAF prefix for your z/OSMF configuration. By default, the prefix is
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.COMwould 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 (
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.
- 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,
JOBSto 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)
- 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)
- Refresh the ZMFAPLA class. In RACF, enter the SETROPTS command, as follows:
SETROPTS RACLIST(ZMFAPLA) REFRESH