Zowe CLI: Token Based Authentication with API mediation layer and baseProfiles

{Core} I received a request from a happy user of the The Open Mainframe Project’s Zowe CLI who wrote to me recently.

‘Hi Joe,
This is great that I can connect my laptop to z/OSMF and list files, submit jobs, and drive the mainframe from my PC. I’ve heard that the Zowe API Mediation Layer component can help me, but I’m not sure how. I will have to ask my sysprogs to install it onto the LPAR, so what is the use case my team will benefit from before I create the ticket ?
Cheers, and thanks to the Zowe team for being so amazing.
(p.s. I’m having a tough day at work, do you know any good jokes to cheer me up ?)`

This is the first in a series of blogs that will answer the question. I am a hands-on kind of blogger so rather than me showing static diagrams I’m going to build up a picture that introduces a new topic in each blogpost.

• Configuring z/OSMF behind an API Gateway for use by the CLI with base profiles, showcasing token based authentication (that is this blog’s focus)
• Single sign-on across multiple CLI services using the API Gateway as a proxy for Multi Factor Authentication, showing the benefit of Zowe APIML and Zowe conformance and the growing vendor community of plugins.
• Providing High Availability of z/OS services by having the CLI connect to multiple services through a single gateway

Apologies if this blog is too verbose and too full of screen shots, but I wanted to capture every step in the hope that if you are trying this at home (make sure you ask your parent or guardian’s permission and check with the bill payer first and don’t phone if you are watching on catchup TV), then you can get to the end without creating a big mess all over your kitchen floor.

Sitting comfortably ? Now we’ll show how to use Zowe CLI connecting directly to z/OSMF, and also how to put the Zowe API Mediation Layer in the middle and the benefit this brings. We’ll talk about things like baseProfiles, apimlAuthenticationTokens, single-sign-on (SSO), multi-factor-authentication (MFA), probably some more three letter acronyms (TLAs), and if you read all the way to end there is a joke that you might find funny.

Direct connection to z/OSMF.

In this scenario we’ll make a connection from the Zowe CLI and Zowe Explorer directly to z/OSMF so that it can issue REST API calls.

You’ll need to know the port that z/OSMF is running on. It’s likely to be 443 but a good way to check is to open your favourite unix terminal on USS and do a netstat command looking for the port that IZUSVR1 is listening on. This could be ishell or omvs but if you’re wanting to get down with the kids (DWTK) then I recommend using ssh .

(For the purpose of this blog I wanted to show everything with a real system and real screen shots and gif snippets, however I don’t want to show you the actual TCP/IP network address of the system I’m using so I created an entry in Mac’s /etc/hosts file called zowehost that maps to the real IP address).

Do we trust z/OSMF ?

A good check to ping z/OSMF from your laptop is to use a browser and hit the URL <zowehost>:<port>/zosmf/info . This will let you know whether your laptop trusts the z/OSMF TLS certificate. In the screen shot of the Chrome browser below is shows NotSecure|https:// with a red triangle. Knowing the cert is not trusted is good to remember as this controls the value of the rejectUnauthorized: parameter we’ll set in the profile that will be false . If instead of the scary red in the browser (that has been preceded by a “Do you want to continue ?”) question, you have a trusted cert then the value should be true

Next create a connection that defines the z/OSMF endpoint. If this is your first time creating a CLI profiles (which define how your PC reaches the z/OS services you want to talk to (host, port, credentials, cetificate trust, …) then checkout some of the great other medium.com/zowe blogs such as Team Configuration: The new sheriff in town from Richell Anne Craw, and also Gene Johnson’s awesome piece Enterprise rollout of Zowe CLI.

Assuming you’re using Team Configuration files (which are the preferred way to store CLI profiles) you’ll have a directory in your PC’s home directory called /.zowe and inside that a file called zowe.config.json . That file contains all your CLI profiles, and into that we’ll be creating a "type": "zosmf" YAML segment. I use VS Code so the screen shots in this blog are from VS Code where I make edits to the file’s contents.

For the zOSMF connection I’ve called this direct. Because we know the cert isn’t trusted by our PC rejectUnauthorized (our browser indicated this when we made the connection above) we set this to be false .

Run a simple CLI command

To test this connection a good Hello World request to run is to look at the z/OSMF jobs (which we know will be running so the result is consistent). We already know that these jobs have IZU in their name (because we did the netstat earlier). The zowe list jobs command has paramaters of --prefix that will be set to IZU* and because it’s not owned by the TSO user for my CLI profile userID WINCHJ we’ll to set --owner to be * . The full command becomes zowe jobs list jobs --prefix “IZU*” — owner ”*". Because this is the first time we’ve used our profile the user and password are unknown so we will be asked to enter them with the helpful message pair Enter the user name for your service (will be hidden): where we can type our TSO user ID, followed by Enter the password for your service (will be hidden): where we enter our TSO password. Because our zowe.config.json profile specified that these properties were to be stored securely they won’t appear in plain text like the other profile property values and instead are safely squirelled away in our laptop’s credential store. On later CLI commands they’re retrieved and you won’t need to enter them again.

**Nerdy Note Number One** — The reason the messages Enter the password for your service (will be hidden) is phrased as such, is to let you know that when you type your password the characters aren’t echoed to the terminal for prying eyes to see and steal under your nose).

**Nerdy Note Number Two** If you get a message prompt like “Electron Helper (Plugin) wants to use confidential information stored as ‘Zowe’ in your keychain” this is because you have the Zowe Explorer extension open on the zowe.config.json file and VS Code has detected that the file has been updated with new information it needs to retrieve, and to this you need to give Electron (the UI framework VS Code is built on top of) permission to get at the data. This is a great example of how your credentials are protected and if any app on your desktop, foe or friend (in the case of Zowe Explorer) tries to access the operating system asks for your permission.

Back to the main plot. Having got the credentials stored to allow the CLI command to execute, under the covers the Zowe CLI has constructed a REST API request to call the z/OSMF REST Jobs API https://zowehost:443/zosmf/restjobs/jobs?prefix-IZU*&owner=* . The credentials are flowed on the REST API message header as part of the basic Authentication header. You can learn more about API authorization headers by using an API tool such as Postman to send the request yourself and see the results as shown below.

Conclusion to Act 1.

In its most simple form having a profile with properties of user and password these are used by the CLI to construct REST API requests flowing the credential pair using the Basic Authentication REST Authorization Type. All good and well, but what if we want our password to be a one time use auth and burn, perhaps alongside an out of band multi factor authentication protocol.

This is where Act 2 begins and we bring the Zowe API Mediation Layer into our play.

Connection to z/OSMF via APIML

We’re going to build on this scenario of the CLI connecting to z/OSMF, by conceptually putting the Zowe API Mediation Layer (APIML) in-between our CLI client on our PC and the z/OSMF server running on z/OS.

We’ll do this so that the CLI doesn’t need to flow a user ID and password on every API request, and instead use APIML to exchange this for a temporary token that we can use on API calls instead. The advantage of this is that the password can be one time use only and also that the password doesn’t need to be stored and recalled on every API request. Even though Zowe keeps user credentials in the PC’s keystore many companies have rules that just forbid passwords being stored anywhere on PCs or client desktop machines to stop phishing, snarfing, and other evil things occurring that might compromise security.

The APIML being in between the Zowe CLI and z/OSMF is often known as a Reverse Proxy pattern.

The Zowe APIML by default runs on port 7554 . For this blogpost I have my gateway running on on port 27554 on the same LPAR.

For Zowe’s APIML I’ve used a different certificate to the one z/OSMF used for its TLS. Where the z/OSMF one was self signed and not trusted by my PC, the Zowe one is trusted (as shown by the lack of scary red Untrusted warnings). This is one of the advantages of having the APIML front z/OS services, all host endpoints can be funnelled through a common network address with a single certificate, a single port, and a single management and access point.

Base Profile

To create a the connection to z/OSMF via the API Gateway we need to create two connections.

- A base profile that describes where the API Mediation Layer’s gateway endpoint is
- a zosmf profile that points to the base profile and adds any specific connection details needed to talk to z/OSMF.

The base profile describes where the API Mediation Layer is. The screen shot below shows one that I’ve called zoweapimland specified the host , the port , the rejectUnathorized (which is for the Zowe APIML certificate that my PC trusts), and I’ve also specified a tokenType of apimlAuthenticationToken (instead of the user and password used in the direct port 443connection)

To get an SSO token generated we need to log into the APIML and exchange our user ID and password for a tokenValue . This is done with the command zowe auth login apiml . We’ll be prompted for our user ID and password, the CLI will call the API Gateway server on 27554 , get a token back and put it in into our PC’s secure credential store.

The tokenValue retrieved from APIML is stored securely by the Zowe CLI so you can’t see it by default, although if you look into the zowe.config.json file the base profile will have been updated to reflect this.

The password challenge received in the screen shot above is because to store the token in my PC’s keychain needs a quick double check as it’s a privileged data store. This is a good thing, as it also means that it’s tucked away nice and safe so that other software can’t grab it, copy it to another laptop, and try and pretend to be you (or in this case me).

If you go and have a look back in zowe.config.json you’ll see that the profile has been updated to show that the tokenValue is held securely.

Having defined the base profile that points to APIML, we now need to define the one that says “I want to reach the z/OSMF server that is behind the API Gateway”. This profile is still type zosmf , but instead of specifying the endpoint port: 443 and other URL details of z/OSMF itself, just needs to point to the baseProfile that we defined earlier (that we called zoweapiml ) and an extra important piece of basePath . For z/OMF this will be /ibmzosmf/api/v1 . This is like a telephone dialing code, we just need to add it to the requests that we’ll send to the API Gateway that we want it direct to z/OSMF.

Now when we run zowe CLI commands against this profile it will act and behave as though it is a full z/OSMF endoint, but traffic will go via the APIML. To be sure that the CLI is going through our zosmf_via_apiml connection we’ll use the --zosmf-p argument to point to the profile. We’ll also use for good measure go and do a --zosmf-p direct as well afterwards to show that the results are unchanged.

I can tell you’re not impressed. That’s good ! What has happened is that the zosmf_via_apiml connection has got the list of jobs as before, however instead of sending a userID and password down the wire it’s sent the token from the API Gateway.

How is the token stored ?

When the CLI profile zosmf-via-apiml is used because the profile defined that its tokenValue is stored using a code module that the Zowe docs refer to as the Secure Credentials Store . This is visually shown to you by the tokenValue not being in clear text in the zowe.config.json but in the secure block of YAML

Behind the covers you can look into how your PC has stored the value. For my Mac it’s I can open the keychainAccess app that will show all of the logins with a Zowe one. Select that which shows the Attributes for secure_config_properties to reveal the value.

Another way to show the value of the token is to add --show-inputs-only . What this does is show all of the data that the CLI has sent in its request, which will reveal to us that it hit port 27554 (the API Gateway) and also the token value in all of its gorpy hex.

Let’s do another test of this and go back to Postman (or whatever your favourite REST API tool is). Copy the gorpy hex token into your clipboard, select BearerToken for the authentication type, paste the token value. Change the URL to point at the APIML, add the segment /ibmzosmf/api/v1 into the path and you’ll see that everything works ! The gateway has picked up the API request, taken the basePath value and realized it needs to re-direct to the z/OSMF service, and flowed the API call there.

Let’s wrap it up

What have we done ?

We created a CLI profile that connects directly to the z/OSMF service on port 443 that used the basicAuthentication REST API method to authenticate with a userID and password. This worked great, except that the password was flowed on each request. The CLI stored it in the PC’s secure credentials store to stop it being snarfed but it still had to be a long lived password so it won’t work with a one time password use case.

To fix that we put the API Gateway in-between the CLI and z/OSMF, created a baseProfile that we used to exchange our user ID and password for a token, created a zosmf profile that used the endpoint of the API gateway and a basePath to identify that it wanted to route through the gateway to z/OSMF.

The magic

The reason that the requests were routed it because of the basePath of ibmzosmf/api/v1 . This is defined when the z/OSMF service registers itself with the APIML, and you can always find this by logging into the API Catalog, selecting the tile of the service and seeing its Base URL: .

When Zowe API starts it will register z/OSMF as a service by default, however it can also register other services provided by vendors and folks who create APIML extensions. If these services have the words SSO against their tiles then it means they too can accept the apimlAuthenticationToken and have requests routed to their endpoints via the API Gateway. This binding together of z/OS REST API services behind a single authentication provider is one of the neat things the Zowe AIML does. There are more that I’ll cover in future blog posts.

The funny joke

Question: Which country should you visit to buy your next mainframe computer ?

Anwer: New-z-land.

All credits to the joke go to Isabel Arnold (IBM Z social media legend and funny German comedienne).

Finding out more

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-cli or #zowe-onboarding. If this is your first time using the Open Mainframe Slack Channel register here.

Zowe is owned and managed by the Open Mainframe Project which is a Linux Foundation project.