Single-Sign-On to z/OS REST APIs with Zowe
{Core} Once you have multiple different API services on z/OS or you use multi-factor authentication, you would like to log in only once per your authenticated session and then access your APIs within the authenticated session without the need to provide different second factors to each request.
Zowe™ is an open-source project created to host technologies that benefit the IBM Z platform for all members of the Z community, including Independent Software Vendors (ISVs), System Integrators, and z/OS consumers. Zowe, like Mac or Windows, comes with a set of APIs and OS capabilities that applications build on and also includes some applications out of the box. Zowe offers modern interfaces to interact with z/OS and allows you to work with z/OS in a way that is similar to what you experience on cloud platforms today. You can use these interfaces as delivered or through plug-ins and extensions that are created by clients or third-party vendors.
Zowe provides authentication capabilities that make it possible to authentication only once per session and then do multiple REST API requests.
API security is the building block of the Zowe pathway to the better CLI security and authentication experience that has been described by Dan Kelosky.
Zowe API Gateway allows you to obtain Zowe JWT token and use it in API services.
Zowe-conformant API services accept the same Zowe JWT token that can be passed in the Authorization: Bearer header of HTTP request on in secure HTTP-only cookie with the name apimlAuthenticationToken.
We will see the process in more detail.
Note: We will use the HTTPie command-line HTTP client that allows us to issue REST API requests easily. The output starts with the full request including the JSON body and the output contains all response cookies and formatted JSON response if present. You can use any HTTP client on command-line, programming language, or application like Postman.
Obtaining JWT Token
The Zowe API Mediation Layer provides support for token-based authentication. You can use the/api/v1/gateway/auth/login endpoint to obtain a time-limited JWT token.
In the following example, we will use Zowe installation on a system with the hostname sys1.acme.net and Zowe API Gateway on port 40004.
Example of obtaining JWT token:
$ http -v --session=zowe POST https://sys1.acme.net:40004/api/v1/gateway/auth/login username=user01 password=YOUR@PWD Content-Type: application/json
Host: sys1.acme.net:40004
{
"username": "user01",
"password": "YOUR@PWD"
}HTTP/1.1 204
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
Pragma: no-cache
Set-Cookie: apimlAuthenticationToken=eyJhbGciOiJSU...nPCxrFl-aegbQ; Path=/; Secure; HttpOnly
The HTTPie has two special parameters:
-vcauses that the request header and body are printed before the response. You can see that the body was:
Content-Type: application/json
Host: sys1.acme.net:40004
{
"username": "user01",
"password": "YOUR@PWD"
}--session=zowestores the response cookies to a named session so we will be able to use in following requests
The response has been 204 which means success as every 2xx response.
Validating JWT Token
The next request validates the current JWT token. The HTTPie uses the token stored in the zowe session. This is not required. It can be useful if you have an older token and you want to be sure that is not expired.
$ http -v --session=zowe GET https://sys1.acme.net:40004/api/v1/gateway/auth/query GET /api/v1/gateway/auth/query HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Cookie: apimlAuthenticationToken=eyJhbGciOiJSU...nPCxrFl-aegbQ
Host: sys1.acme.net:40004HTTP/1.1 200
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 126
Content-Type: application/json;charset=UTF-8
Expires: 0
Pragma: no-cache{
"creation": "2020-01-13T14:31:19.000+0000",
"domain": "SAFRealm",
"expiration": "2020-01-14T14:31:19.000+0000",
"userId": "user01"
}
The response is 200 so the token is valid. You can that it will be valid for one full day in the expiration field. The expiration time is configurable by Zowe API Mediation Layer properties.
Note: You can also use Authorization header in the request instead of the cookie:
Authorization: Bearer eyJhbGciOiJSU...nPCxrFl-aegbQThe cookies are better suited for web browsers and the Authorization header is easier to use in programmatic API clients. You can find more details about cookies and authorization header in the following talk:
Accessing z/OSMF with Zowe JWT Token
Zowe API Gateway allows you to access many APIs with a valid Zowe JWT token. You do not need to know what is the authentication scheme of the downstream API service, API gateway will do it transparently. Of course, the Zowe JWT token needs to be valid.
We will access a z/OSMF REST API endpoint via the API Gateway. The z/OSMF is available via the zosmf service ID.
http -v --session=zowe GET https://sys1.acme.net:40004/api/v1/zosmf/info "X-CSRF-ZOSMF-HEADER;"GET /api/v1/zosmf/info HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Cookie: apimlAuthenticationToken=eyJhbGciOiJSU...nPCxrFl-aegbQ
Host: sys1.acme.net:40004
X-CSRF-ZOSMF-HEADER:HTTP/1.1 200
Cache-Control: no-store
Content-Language: en-US
Content-Type: application/json
Pragma: no-cache
Transfer-Encoding: chunked{
"api_version": "1",
"plugins": [
...
],
"zos_version": "04.27.00",
"zosmf_full_version": "27.0",
"zosmf_hostname": "sys2.acme.net",
"zosmf_port": "443",
"zosmf_saf_realm": "SAFRealm",
"zosmf_version": "27"
}
You can access any z/OSMF REST API endpoint with the same JWT token.
Accessing Services that Support PassTickets with Zowe JWT Token
The Zowe API Gateway supports z/OSMF, services that support Zowe JWT token, and any service that accepts PassTickets in the standard HTTP Basic authorization header.
A lot of z/OS API services support PassTickets. In this example, we will use the CA Endevor SCM REST API.
For each service that supports PassTickets, you need to do a setup in the security product on z/OS. This is documented in the documentation for your particular API service. For example, this is for CA Endevor SCM: https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/devops/ca-endevor-software-change-manager/18-0/securing/multi-factor-authentication-mfa.html
The last step is to allow the Zowe server user ID to generate PassTickets for the ENDEVOR APPLID. The following example is for CA Top Secret as the security product:
TSS PERMIT(<zowesrv>) PTKTDATA(IRRPTAUTH.ENDEVOR.) ACCESS(READ,UPDATE)
TSS REFRESHYou can limit it to certain users by specifying IRRPTAUTH.ENDEVOR.USERID .
You need to tell Zowe API Gateway that Endevor accepts PassTickets by providing additional metadata for any file in the Zowe api-defs directory on z/OS:
additionalServiceMetadata:
- serviceId: endevor
mode: UPDATE
authentication:
scheme: httpBasicPassTicket
applid: ENDEVORFor more details about the configuration of PassTicket and commands for other security products, see Zowe Docs.
Now we can access the Endevor REST API via the API Gateway:
http --session=zowe GET https://sys1.acme.net:40004/api/v1/endevor/ENV/HTTP/1.1 200
API-Version: 1.1
Cache-Control: private
Content-Encoding: gzip
Content-Length: 330
Content-Type: application/json
{
"agedTimeout": 0,
"characterSet": "ISO8859-1",
"codepage": "cp1047",
"comments": "Welcome to ENDEVOR ACME Environment",
"contentType": "Text",
"description": "Endevor Web Services",
"hostName": "A01SENF",
"jobName": "TSO1MFNE",
"lang": "EN",
"message": "ENDEVOR Web Service for ACME",
"name": "ENV",
"password": null,
"poolIncrSize": 1,
"poolInitSize": 2,
"poolMaxSize": 5,
"poolReapTime": 0,
"programName": "BC1PAPI0",
"status": "Available",
"timeZone": "GMT-6.0",
"traced": "ALL",
"unusedTimeout": 0,
"userId": "ENDEVOR"
}
Summary
We have obtained one JWT token from the Zowe API Gateway and used that token to access both z/OSMF and CA Endevor. This allows you to develop and use other API services or automation scripts that work with multiple APIs that require the authentication to be done only once.
You can learn more about Zowe here.
See more blogs at medium.com/zowe.
Download at https://www.zowe.org/.
