Getting z/OS Explorer to work with z/OS Connect EE

Ive been trying to set up z/OS Connect, so I could look at the MQ support within it.

Setting up z/OS Connect in the first place, was a challenge, which I’ll blog about some other time.  I was looking for an Installation Verification Program (IVP) and tried to use the z/OS Explorer.  This was another challenge.  Like many problem there are answers, but it is hard to find the information.

Installing z/OS Explorer

This was easy.  I started here and installed z/OS explorer for Aqua – Eclipse tools.  Then select  IBM z/OS Connect EE.  I selected Aqua 3.2, and chose to install using eclipse p2. I have tried to avoid installation manager as it always seemed very complex and frustrating.

I tried to extend an existing eclipse, but this failed due to incompatibilities.  I used start from fresh, and this worked fine.

Adjust the z/OS Connect server configuration.

I enabled logon logging.

 <httpEndpoint id="defaultHttpEndpoint" 
    host="*" 
    accessLoggingRef="hal1" 
    httpPort="19080" 
    httpsPort="19443" > 
   <accessLogging enabled="true" 
     logFormat='h:%h i:%i u:%u t:%t r:%r s:%s b:%b D: %D m:%m' 
    /> 
<sslOptions sslRef="defaultSSLSettings"/> 
</httpEndpoint> 

This creates a file in the  location http_access.log within the log directory. It has output like

10.1.1.1 ADCDC 08/Sep/2020:17:50:40 +0000 "GET /zosConnect/services/stockQuery HTTP/1.1" 200

You can see where the request came from (10.1.1.1), user (ADCDC), the date and time, the request (“GET /zosConnect/services/stockQuery HTTP/1.1”), and the response code(200).

Getting started with z/OS Explorer

You need to define host connections.

If you totally disable security on your server you can use http.

1. On z/OS explorer,display the Connections tab. (Window -> Show View -> Host connections)
2. Right click on z/OS Connect Enterprise Edition, and select New z/OS Connect Enterprise Edition, Connection
   1. Name: this is displayed in the tooling
   2. Host name: I used 10.1.3.10 which is my VIPA address of the server
   3. Port number:   This comes from the  httpEndpoint for the server.  The default is http:9080 and https:9443 – but as every Liberty product uses these values, your server may have different values.  I used 19080.
   4. I initially left Secure connection(TLS/SSL) unticked
   5. Click Save and Connect
3. A panel was displayed asking for credentials. Either create new credentials (userid and password) or select an existing credential.
4. Double click on the connection you just created.
   1. An error of “302, Found” is an http response meaning redirection.  In the z/OS connect case, this means you are trying to use an http connection when an https ( a TLS connection) was expected.  I got this because I had not disabled security in my server.

The normal way of accessing z/OS connect is to use TLS to protect the session.  As well as TLS to protect the session you can also use client certificate authentication.  This is what I used.

You will need to set up certificates, keystores and keyrings on z/OS and get the Certificate Authority certificates sent to the “other” system.  I used my definitions from using MQWEB.

1. On z/OS explorer, set up the keystores
   1. Window -> Preferences -> Explorer-> certificate manager
   2. The truststore contains the CA certificates to validate the certificate send down from the z/OS server.  Enter the file name (or use Browse), the pass phrase, and the key store.  My truststore was JKS.
   3. The keystore contains the client certificate used to identify this client to the server.
   4. Smart card details.  Ignore this – (despite it saying you must configure a PKCS11 driver).   This section is used if you select smart card to identify yourself, and it would be better if the wording said “If you are using Smart card authentication you must configure a PKCS11 driver ).
   5. Leave the “Do not validate server certificate trust” unticked.  This will check the passwords etc of the key stores.
   6. At the bottom I used “Secure socket protocol-> TLS v1.2” though this is optional.
   7. Select Apply and Close
2. Display the Connections tab. (Window -> Show View -> Host connections)
3. Right click on z/OS Connect Enterprise Edition, and select New z/OS Connect Enterprise Edition, Connection
   1. Name: this is displayed in the tooling
   2. Host name: I used 10.1.3.10 which is my VIPA address of the server
   3. Port number:   This comes from the  httpEndpoint for the server.  The default is http:9080 and https:9443 – but as every Liberty product uses these values, your server may have different values.  I used 19443
   4. I ticked Secure connection(TLS/SSL).  If you do not select this, you will not be able to use a certificate to logon.
   5. Click Save and Connect
4. A panel was displayed asking for credentials.   When I used an existing credential I failed to connect to the server.
   1. Select Create new credentials
   2. Click on Username and Password pull down – and select Certificate from Keystore.
   3. Enter credentials name – this is just used within the tooling
   4. Userid – this seems to be ignored.  I used certificate mapping on the z/OS to map the certificate to a userid.
   5. Choose a certificate – select one from the pull down.  In my Linux box the choice of certificates came out in yellow writing on a yellow background!
   6. Click OK
   7. The connection should appear on the Connections page, under z/OS Connect Enterprise Edition.  It should go yellow while it is connecting, and green, with a padlock once it has connected

Use z/OS Connect

Use Window-> Show View -> zOS Connect EE Servers

You should see your connection displayed  with the IP address and port. Underneath this are any APIs or Services you have defined.

If you have any APIs or Services, you should be able to right click and select Show Properties View.  You can click on the links, or copy the links and use them, for example  in a web browser directly,or via curl.

If you try to use the APIs or Services, you may not be authorised.  You will need to configure

1. <zosconnect_zosConnectManager …>
2. <zosconnect_zosConnectAPIs>   <zosConnectAPI name=”stockmanager”  ….
3. <zosconnect_service>  <service name=”stockquery”

Good luck.