This blog post was written as background to some blog posts on Zowe API-ML. It provides back ground knowledge for HTTPS servers running on z/OS, and I think it is useful on its own. Ive written about an MQWEB server – because I have configured this on my system.
- Which architecture
- Connecting to the MQWEB server
- Setting up a pass ticket
- JSON Web Tokens
- The JWT has limited access
The problem
I want to manage my z/OS queue manager from my Linux machine.I have several ways of doing it.
Which architecture?
- Use an MQ client. Establish a client connect to the CHINIT, and use MQPUT and MQGET administration messages to the queue manager.
- You can issue a command string, and get back a response string which you then have to parse
- You can issue an MQINQ API request to programmatically query attributes, and get the values back in fields. No parsing, but you have to write a program to do the work.
- Use the REST API. This is an HTTP request in a standard format into the MQWEB server.
- You can issue a command string, and get back a response string which you then have to parse to extract the values.
- You can issue a JSON object where the request is encoded in a URL, and get the response back in JSON format. It is trivial to extract individual fields from the returned data.
Connecting to the MQWEB server
If you use REST (over HTTPS) there are several ways of doing this
- You can connect using userid and password. It may be OK to enter your password when you are at the keyboard, but not if you are using scripts and you may be away from your keyboard. If hackers get hold of the password, they have weeks to use it, before the password expires. You want to give your password once per session, not for every request.
- You can connect using certificates, without specifying userid and password.
- It needs a bit of set up at the server to map your certificate to a userid.
- It takes some work to set up how to revoke your access, if you leave the company, or the certificate is compromised.
- Your private key could be copied and used by hackers. There is discussion about reducing the validity period from over a year to 47 days. For some people this is still too long! You can have your private certificate on a dongle which you have to present when connecting to a back end. This reduces the risk of hackers using your private key.
- You can connect with a both certificate and userid and password. The certificate is used to establish the TLS session, and the userid and password are used to logon to the application.
- You can use a pass ticket. You issue a z/OS service which, if authorised, generates a one time password valid for 10 minutes or less. If hackers get hold of the pass ticket, they do not have long to be able to exploit it. The application generating the pass ticket, does not need the password of the userid, because the application has been set up as trusted.
- You can use a JSON Web Token (JWT). This has some similarities with certificates. In the payload is a userid value and issuer value . I think of issuer as the domain the JWT has come from – it could be TEST or a company name. From the issuer value, and IP address range, you configure the server to specify a realm value. From the userid and realm you can map this to a userid on the server. This JWT can be valid from minutes to many hours (but under a day). The userid and realm mapping to a userid is different to certificate mapping to a userid.
Setting up a pass ticket
The passticket is used within the sysplex. It cannot be used outside of a sysplex. The pass ticket is a password – so needs to be validated against the RACF database.
The application that generates the pass ticket must be authorised to a profile for the application. For example, define the profile for the application TSO on system S0W1, the profile is TSOS0W1.
RDEFINE PTKTDATA TSOS0W1
and a profile to allow a userid to create a pass ticket for the application
RDEFINE PTKTDATA IRRPTAUTH.TSOS0W1.* UACC(NONE)
PERMIT IRRPTAUTH.TSOS0W1.* CLASS(PTKTDATA) ID(COLIN) ACCESS(UPDATE)
PERMIT IRRPTAUTH.TSOS0W1.* CLASS(PTKTDATA) ID(IBMUSER)ACCESS(UPDATE)
Userids COLIN and IBMUSER can issue the callable service IRRSPK00 to generate a pass ticket for a user for the application TSOS0W1.
The output is a one-use password which has a validity of up to 10 minutes.
As an example, you could configure your MQWEB server to use profile name MQWEB, or CSQ9WEB.
How is it used
A typical scenario is for an application running on a work station to issue a request to an “application” on z/OS, like z/OSMF, to generate a pass ticket for a userid and application name.
The client on the work station then issues a request to the back end server, with the userid and pass ticket. If the back end server matches the application name then the pass ticket will be accepted as a password. The logon will fail if a different application is used, so a pass ticket for TSO cannot be used for MQWEB.
This is more secure than sending a userid and password up with every back end request, but there is additional work in creating the pass ticket, and two network flows.
This solution scales because very little work needs to be done on the work station, and there is some one-off work for the setup to generate the pass tickets.
JSON Web Tokens
See What are JSON Web Tokens and how do they work?
The JWT sent from the client has an expiry time. This can be from seconds to hours. I think it should be less than a day – perhaps a couple of hours at most. If a hacker has a copy of the JWT, they can use it until it expires.
The back end server needs to authenticate the token. It could do this by having a copy of the public certificate in the server’s keyring, or send a request down to the originator to validate it.
If validation is being done with public certificates, because the client’s private key is used to generate the JWT, the server needs a copy of the public certificate in the server’s keyring. This can make it hard to manage if there are many clients.
The Liberty web server has definitions like
<openidConnectClient id="RSCOOKIE"
clientId="COLINCOO2"
realmName="zOSMF"
inboundPropagation="supported"
issuerIdentifier="zOSMF"
mapIdentityToRegistryUser="false"
signatureAlgorithm="RS384"
trustAliasName="CONN1.IZUDFLT"
trustStoreRef="defaultKeyStore"
userIdentifier="sub"
>
<authFilter id="afint">
<remoteAddress id="myAddress" ip="10.1.0.2" matchType="equals" />
</authFilter >
</openidConnectClient>
For this entry to be used various parameters need to match
- The issuerIdentifier. This string identifies the client. It could be MEGABANK, TEST, or another string of your choice. It has to match what is in the JWT.
- signatureAlgorithm. This matches the incoming JWT.
- trustAliasName and trustStoreRef. These identify the certificate used to validate the certificate
- remoteAddress. This is the address, or address range of the client’s IP addresses.
If you have 1000 client machines, you may need 1000 <openidConnectClient…/> definitions, because of the different certificate and IP addresses.
You may need 1000 entries in the RACMAP mapping of userid + realm to userid to be used on the server.
How is it used
You generate the JWT. There are different ways of doing this.
- Use a service like z/OSMF
- Use a service on your work station. I have used Python to do this. The program is 30 lines long and uses the Python jwt package
You get back a long string. You can see what is in the string by pasting the JWT in to jwt.io.
You pass this to the backend as a cookie. The cookie name depends on what the server is expecting. For example
'Authorization': "Bearer " + token
The JWT has limited access
For the server to use the JWT, it needs definitions to recognise it. If you have two back end servers
- Both servers could be configured to accept the JWT
- If the server specified a different REALM, then the mapped userid from the JWT could be different for each server because the userid/realm to userid mapping can be different.
- One server is configured to accept the JWT
- If only one server has the definitions for the JWT, then trying to use the JWT to logon to another server will fail.
ColinPaice 