liberty profile z/os and z/os connect hands-on labs · liberty profile z/os and z/os connect...

ZCONN1- z/OS Connect and Mobile Access to z/OS

Liberty Profile z/OS and z/OS Connect

Hands-on Labs

Lab Version Date: October 28, 2014

© 2014, IBM Corporation 1


Table of ContentsUnit 2 Lab – Liberty Profile and WOLA................................................................................................3

Create foundational RACF profiles......................................................................................................................3Create server and validate in the UNIX shell.......................................................................................................4Start server as a started task under LIBSERV ID ...............................................................................................5Start Angel ........................................................................................................................................................ 11Configure WOLA support into Liberty Profile server..........................................................................................12Install WOLA support into CICS region and validate.........................................................................................17

Unit 3 Lab – z/OS Connect..................................................................................................................21Configure basic registry and validate access to z/OS Connect.........................................................................21Configure backend CICS service and validate..................................................................................................23Configure data transformation to CICS.............................................................................................................27Explore REST APIs........................................................................................................................................... 31

Unit 4 Lab – z/OS Connect Security Topics.......................................................................................35Review SAF jobs submitted earlier.................................................................................................................... 35Moving basic authentication and role checking to SAF.....................................................................................37Authorization interceptors.................................................................................................................................. 40Passing identity over WOLA into CICS..............................................................................................................44SAF certificates and client certificate authentication.........................................................................................48



Unit 2 Lab – Liberty Profile and WOLACreate foundational RACF profiles

Note: There's a handful of RACF profiles that need to be created in preparation for running Liberty Profile z/OS. We've created the jobs ahead of time. What they do will be explained in the unit on security later in the workshop.

Use the "WG31" icon on the desktop to open a TN3270 session to the z/OS system. Log on with the TSO USER1 at the prompt:

Then press the host enter key (the right Ctrl key).

When prompted for a password, enter the password you are given for this ID:

Again, press the host enter key (the right Ctrl key).

When you get the three stars:

hit the host enter key. You should then be at the main ISPF panel:

Enter =3.4 at the input prompt:

And hit the host enter key.



At the "Data Set List Utility" panel (the "=3.4 panel"), type in USER1.ZCONN.CNTL

and hit the host enter key.

Place a "b" next to the data set:


Submit the ZCRACF1 job1 by typing sub in the prefix area to the left of the member name:


You should get a confirmation of a job submission:

To that simply hit the enter key.

You will then see a confirmation of the job completing:

The MAXCC=0000 string indicates the job ran successfully2.

Hit the F3 key three times to return to the ISPF main panel.

Create server and validate in the UNIX shell Using PuTTY (on the workstation desktop) open a session and log on as LIBSERV.

Using the copy-and-paste file on the desktop, enter the following commands3:

mkdir /u/libserv/liberty

export JAVA_HOME=/shared/zWebSphere/V8R55FP02/java_1.7_64/

export WLP_USER_DIR=/u/libserv/liberty

cd /shared/zWebSphere/Liberty/V8R55FP02/bin

1 This creates the server ID, the Angel ID, and the STARTED profiles/2 For those familiar with jobs that run RACF commands, it's always best to review the job output to make sure the

commands each ran successfully. For this workshop, we know the job does what it should do so we can skip that here.3 The first two create environment variables needed to create the server. The third changes directories to where the Liberty

Profile server shell script is located. The fourth creates the directory in which the server will be created.



Verify the environment variables by running the following two commands:

echo $JAVA_HOME

echo $WLP_USER_DIR

Both should return the values you set earlier.

Issue the following command to create the server:

./server create server1

You should see the following response:

Server server1 created.

Start the server with the following command:

./server start server1


Starting server server1.Server server1 started with process ID xxxxxxxxx.

Stop the server with the following command:

./server stop server1


Stopping server server1.Server server1 stopped.

Start server as a started task under LIBSERV ID Change directories to the Liberty Profile server directory:

cd /u/user1/liberty/servers/server1

Copy a pre-built server.env file so the started task will know where the Java SDK can be found:cp /wasetc/zclab/server.env /u/user1/liberty/servers/server1/server.env

Take a look at what's inside the server.env file4:

cat server.env

Go back to ISPF and enter =3.4 at the input prompt:

And hit the host enter key.

At the "Data Set List Utility" panel (the "=3.4 panel"), type in SYS1.PROCLIB


4 It's simply the same JAVA_HOME variable as before.



Enter the letter b (for "browse") next to the SYS1.PROCLIB data set name:

Look for the BBGZANGL and BBGZSRV members5:

Note: We copied those supplied Liberty Profile z/OS start procedures into the SYS1.PROCLIB data set ahead of time. They are supplied with the Liberty Profile z/OS install at this location:/<install_mount_point>/templates/zos/procs/

Enter an e next to the BBGZSRV member to edit the file:

You should see the JCL with lines 12 and 13 that look like this:

Modify the two lines so they contain the following:

// SET INSTDIR='/shared/zWebSphere/Liberty/V8R55FP02'// SET USERDIR='/u/libserv/liberty'

(These lines can be found in the lab copy-and-paste file on your desktop.)

Save the file (the F3 key).

While you're still in the SYS1.PROCLIB data set, place an e next to the BBGZANGL member (you may need to F7 to scroll up one screen) and edit it as well. You should see:

5 If needed, use PF8 to scroll down and PF7 to scroll back.



Modify the SET ROOT= line so it contains the following:

// SET ROOT='/shared/zWebSphere/Liberty/V8R55FP02'

(That line can be found in the lab copy-and-paste file on your desktop.)

Save the file (the F3 key).

At the command prompt on that screen, enter =sdsf.da as shown here6:

At the command prompt on the SDSF.DA screen, enter pre BBG* as shown here7:

The screen will be mostly blank at first because you've not yet started the server:

Enter a single forward slash8 at the command prompt:

Now enter the start command at the prompt:

S BBGZSRV,PARMS='server1'

You should now see the BBGZSRV started task in the "DA" listing9:

6 The =SDSF.DA panel shows active tasks. DA stands for "display active."7 This sets a "prefix" so only tasks that start with BBG are shown. The server and the Angel JCL start procedures started

with the letters BBG.8 This opens up the MVS "command extension" for entering the START command. We do this because the Liberty Profile

START comamnd PARMS= contains mixed case letters, and the command extension preserves the case.9 Hit the enter key to refresh the listing of active tasks.



At the command prompt, enter =3.17 to go to the z/OS UNIX Directory List Utility panel. Enter the directory to the Liberty Profile server you created:

/u/libserv/liberty/servers/server1

(That line can be found in the lab copy-and-paste file on your desktop.)

Enter an e next to the server.xml file:

Hit enter again when you're prompted with the edit confirmation panel:

When the server.xml file comes open for edit, place in i (for "insert") on line 9 in the prefix area on the left to insert a new line:

Hit the enter key.



Type host="*" as shown here:

Why? This indicates what host adapter to listen on. An asterisk implies "any" host adapter. Liberty Profile by default listens on none, which is a security measure. A new Liberty Profile server is reachable only on "localhost" until someone with edit permissions updates the file.

Save the file (the F3 key). Liberty Profile will dynamically update itself with this change. Next you'll look at the log file to see indication of the change.

On the desktop open the WS-FTP client.

At the "Session Properties" panel, click "OK". We pre-set the values so it would log into your z/OS system.

Change the "Remote Site" directory to your Liberty Profile server directory:

Hit the PC enter key to change the directories. You should then see:

Double-click on the "logs" directory. This will show a listing of files in that directory:

Now select the messages.log file and click on the "View" button:



That will open up the configured text editor and display the log file on your PC. Scroll to the bottom and to the right and you should see this message:

CWWKO0219I: TCP Channel defaultHttpEndpoint has been started and is now listening for requests on host * (IPv4) port 9080.

Close the text file view of the log file.

Open a browser and point it at your Liberty Profile server:

http://wg31.washington.ibm.com:9080/

You should get the default splash-screen:

Copy an application to the /dropins directory of your server10. From the PuTTY session, issue the following command as one lone line (use copy-and-paste file to get command):

cp /wasetc/zclab/ATS_servlet.war

/u/libserv/liberty/servers/server1/dropins/ATS_servlet.war

Using the WS-FTP client again, view the messages.log file and scroll to the bottom. You should see the following message:

CWWKZ0001I: Application ATS_servlet started in 0.451 seconds.


From a browser, issue the following URL:

http://wg31.washington.ibm.com:9080/ATS_servlet/SimpleServlet

You should see:

With the displayed date and time being the real current date and time (not that shown in the bitmap capture here).

10 The "dropins" directory is monitored by your server. Application files placed in that directory will be dynamically loaded and started without requiring any configuration of the server.xml file.



Close the browser.

Close the PuTTY session by entering exit and hitting enter.

In your TN3270 session, go to =SDSF.DA and issue the /P BBGZSRV command to stop your Liberty Profile server. The "display active" listing of tasks that start with "BBG" should go blank as the server stops. (To refresh the screen, hit the host enter key a few times.)

Start Angel

Note: At this point your Liberty Profile server does not need the Angel process. It will for WOLA, but rightnow it does not. We're going to go ahead and start it just to validate it works. Earlier we had you update the BBGZANGL start procedure. Here you'll simply start the Angel and Server again.

Earlier you ran the ZCRACF1 job. The Angel needs what's in ZCRACF211. Go to ISPF =3.4 and list the data set USER1.ZCONN.CNTL. Use b to browse, then SUB to submit ZCRACF2:

Go to =SDSF.DA and enter a single forward slash ( / ) to open the command extension.

Enter the command: S BBGZANGL. You should very quickly see:

Open the command extension again and enter the server start command:

S BBGZSRV,PARMS='server1'

You should now see both the Angel and the server up and running:

Go to the WS-FTP client, select the messages.log file again and click on the "View" button. Near the top of the log file you should see this:

Notice the "is available" indicators. That's telling you the Angel is up and the SAF SERVER profiles granting access to the authorized services is enabled. That's a good sign.


11 The ZCRACF2 job sets up the necessary SERVER and CBIND profiles for the Angel and for WOLA.


Configure WOLA support into Liberty Profile server

Using the =3.17 process we used earlier12 to edit the server.xml file and add the highlighted line to the file (this line is in the copy-and-paste file on the desktop):

<server description="new server">  <featureManager> <feature>jsp-2.2</feature> <feature>zosLocalAdapters-1.0</feature> </featureManager>  <featureManager> <feature>jsp-2.2</feature> <feature>zosLocalAdapters-1.0</feature>

12 See page 8 to review the process used to edit the server.xml earlier, including how to insert a line.13 The update of the local adapters feature implied the installation of a few other supporting functions. These messages are

telling you those features were installed. This is a good validation of the update to include the local adapters feature.

</featureManager> <zosLocalAdapters wolaGroup="GROUP" wolaName2="NAME2" wolaName3="NAME3" /> <connectionFactory id="wolaCF" jndiName="eis/ola"> <properties.ola /> </connectionFactory> <!-- To access this server from a remote client add a host <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" httpsPort="9443" /> </server>

Save the file (F3 key).

Use the WS-FTP client "view" function to look at the messages.log file. Near the bottom you should see this message:CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server using the following name: GROUP NAME2 NAME3


Note: At this point your Liberty Profile z/OS server is ready to accept a WOLA registration, using the WOLA three-part name of GROUP, NAME2 and NAME3, from an outside address space. We'll first use a COBOL job to do that14, then in the next section we'll use a CICS region.

Use PuTTY to open a terminal session, but log in with the ID of USER1.

Copy another application to your /dropins directory. This is a single-line command broken here to make it fit. (Get the command from the copy-and-paste file.)

cp /wasetc/zclab/ATSSample1-new.ear

/u/libserv/liberty/servers/server1/dropins/ATSSample1-new.ear

Using ISPF =3.4, go to the data set USER1.L8552.WOLA

After hitting enter you should see15:

14 Because it's relatively easy to setup and validate.15 Those are all the data sets that start with the USER1.L8552.WOLA qualifier.


Put a B next to the CNTL data set to browse the members. Hit enter:

You should see this16:

Put an E next to the member EXER3B and press enter

This will open the member for edit.

The member is rather long. The lines we want to modify are lines 49 through 51. Scroll down(F8 key) to bring those lines into edit view.

Edit lines 49 through 51 so the following is what shows:000046 PROCEDURE DIVISION. 000047 MAINLINE SECTION. 000048 MOVE 'EXER3B' TO register-name. 000049 MOVE 'GROUP' TO daemongroup. 000050 MOVE 'NAME2' TO node-name. 000051 MOVE 'NAME3' TO server-name. 000052 MOVE 'ServiceName' TO SRV-service-name.000053 MOVE 'This is my reply back!' TO reply-message. 000054 000055 INSPECT daemongroup CONVERTING ' ' to LOW-VALUES.

Note: That matches the update to server.xml you made earlier. Your Liberty Profile server is known (from a WOLA perspective) by that three-part name. Here you are telling the COBOL program to use that three-part name to establish a WOLA registration into the Liberty Profile server.

Save the member (F3 key). That will take you back to the list of members.

16 The "EXER" jobs are from the WP101490 Techdoc WOLA "Primer" guide. They are COBOL programs that use the WOLA APIs. The other jobs are simple JCL to compile and run the compiled jobs.



Edit the COMPILE member and make the following three changes:

//COMPILE JOB (),'USER1',REGION=0M,MSGCLASS=H,NOTIFY=&SYSUID //* //MYPROCS JCLLIB ORDER=USER1.L8552.WOLA.CNTL //* //COBOL EXEC IGYWCL, // PARM.COBOL='NODYNAM,LIST,DATA(31),RENT', // PARM.LKED='LIST,XREF,LET,MAP,AMODE(31),RMODE(ANY),CALL' //****************************************************************//* Update the member name to point to your COBOL source *//****************************************************************//COBOL.SYSIN DD DSN=USER1.L8552.WOLA.CNTL(EXER3B),DISP=SHR //* //LKED.SYSLIB DD DSN=SYS1.LEMVS.SCEELKED,DISP=SHR // DD DSN=USER1.L8552.WOLA.LOADLIB,DISP=SHR //****************************************************************//* Update the member name AND the module name to match the name *//* of the module you are creating *//****************************************************************//LKED.SYSLMOD DD DSN=USER1.L8552.WOLA.LOADLIB(EXER3B),DISP=SHR //LKED.SYSPRINT DD SYSOUT=* //LKED.SYSIN DD * NAME EXER3B(R) /*

Note: This job will compile and link-edit the EXER3B program.

Save the file (F3).

Submit the COMPILE job17. You should see a RC=0 indicating successful compilation. If you get something other than RC=0, look at the job output or call an instructor over to take a look.

Edit the RUNPROG member and make the following one change:

//RUNPROG JOB (),'USER1',REGION=0M,MSGCLASS=H,NOTIFY=&SYSUID //******************************************************************//* CHANGE PGM= TO THE NAME OF THE WOLA PROGRAM MODULE TO RUN *//******************************************************************//WOLA EXEC PGM=EXER3B //* //STEPLIB DD DSN=USER1.L8552.WOLA.LOADLIB,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=*

Note: This job will run the program.

Save the file (F3).

Submit the RUNPROG job. This job will not complete right away as it is designed to register into the Liberty Profile server and "listen" (using the WOLA BBOA1SRV API) until Java in Liberty calls over to it.

Go to =SDSF.DA and set the prefix to RUN* (with the command pre RUN*). You should see the RUNPROG job in the listing:

17 By entering SUB in the prefix area to the left of the member and hitting enter.



Now place an s next to the job and hit enter:

This will open up the listing for the job. Scroll to the bottom and look for this:

That's your indication that the COBOL program has successfully registered into the running Liberty Profile z/OS server.

Earlier you copied an application to the /dropins directory. Open a browser and drive that application with the following URL:

http://wg31.washington.ibm.com:9080/ATSSample1Web/

Now do the following18:

You should get back the following:

The EXER3B program sends back a fixed-text string with a loop counter. It does not echo back what you sent it.

Use the browser back button to return to the input panel of the web application.

18 You're telling the program to use the registration established by the EXER3B program (line 48 in COBOL source), and to call the service hosted by the program (line 52 in COBOL source). Loop 5 times.



Change the text string to uppercase STOP and the loop counter to 1 and click the button19:

You will see the following:

Go to =SDSF.DA and you'll find the RUNPROG job has ended

Install WOLA support into CICS region and validate

In ISPF, enter =3.4 and enter USER1.L8552.WOLA to list all the data sets that start with that qualifier. Like before, you should see this:

Place a B (for browse) next to the SAMPLES data set. Hit enter. You should see:

Note: These are samples supplied with Liberty Profile z/OS for use with WOLA. See the WP101490 Techdoc at ibm.com/support/techdocs for where to get these samples. It's a simple process which we did ahead of time. We customized the samples to compile on the workshopsystem.

19 The EXER3B program checks to see if uppercase STOP is received, and if so then branch to exit. The reason why we have you change the iteration count to 1 is because if the web application tries to drive WOLA after the first STOP is issued, nobody will be there to respond. An exception will be thrown. It's ugly. Better to issue only one STOP.



Submit the following three jobs – using SUB in the prefix area, one at a time sequentially, looking for RC=0 each time – in the following order:

CSDSAMPS

CSDUPDAT

OLACB01

Now to go SYS1.PROCLIB and edit the member CICSX.

Add the WOLA load module library to the DFHRPL DD.

// DD DSN=USER1.L8552.WOLA.LOADLIB,DISP=SHR

The line to be added can be found in the copy-and-paste file on the desktop.

Note: This is what gives the CICS region knowledge of the WOLA modules. The modules are in thatdata set. We copied those modules from the Liberty Profile z/OS install directory ahead of time.

Save the member (F3).

Go to =SDSF.DA and set the prefix to PRE CICS*

From the =SDSF.DA panel, enter the command /S CICSX

You should see the CICS region come active:

From the 3270 session program (IBM Personal Communications), select File and then Run the Same:

This will open up a new TN3270 window to your z/OS system.



In the new window, enter CICSX at the prompt:

And then enter. You should see a CICS screen:

Anywhere in that screen click the right mouse button. That brings up a pad with buttons. Clickthe "Clear" button:

Enter the following command:

BBOC START_TRUE

Note: This starts the WOLA "Task Related User Exit" (TRUE) in the region. There are ways to have that start automatically when the region is started. We're doing it manually here.

You should see the following:



Clear the screen again, and then enter this command as one long command:

BBOC START_SRVR RGN=CICSXREG DGN=GROUP NDN=NAME2 SVN=NAME3

SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y

You should then see:

Note: This starts the the "Link Server Task" and processes the registration into your Liberty Profile z/OS server. The DGN=, NDN= and SVN= values match what you have in your server.xml for the WOLA three-part name.

To exercise WOLA we'll use the same web application you used before:

http://wg31.washington.ibm.com:9080/ATSSample1Web/

Fill in the fields with the following values, then click the "Run" button:

You should see:

You have just validated WOLA into CICS.

On the CICS terminal session, clear the screen and enter the command:

BBOC STOP_SRVR RGN=CICSXREG

After a moment or two you should see:

End of Unit 2 Lab


Unit 3 Lab – z/OS ConnectWe are now ready to configure and start using z/OS Connect. In this lab we'll explore z/OS Connectusing a minimal security model. In the next unit we'll explore the question of security more fully.

Configure basic registry and validate access to z/OS Connect In ISPF, go to =3.17 and edit the server.xml file. The file is located in this directory:


Add the lines highlighted here to the server.xml file (lines may be found in copy-and-paste file on the desktop):<server description="new server">  <featureManager> <feature>jsp-2.2</feature> <feature>appSecurity-2.0</feature> <feature>zosConnect-1.0</feature> <feature>zosLocalAdapters-1.0</feature> </featureManager>

<keyStore id="defaultKeyStore" password="Liberty"/> <webAppSecurity allowFailOverToBasicAuth="true" /> <basicRegistry id="basic1" realm="zosConnect"> <user name="Fred" password="fredpwd" /> </basicRegistry> <authorization-roles id="zos.connect.access.roles"> <security-role name="zosConnectAccess"> <user name="Fred"/> </security-role> </authorization-roles> <zosLocalAdapters wolaGroup="GROUP" wolaName2="NAME2" wolaName3="NAME3" /> <connectionFactory id="wolaCF" jndiName="eis/ola"> <properties.ola /> </connectionFactory> <!-- To access this server from a remote client add a <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" httpsPort="9443" /> </server>

Save the file (F3).


Use the WS-FTP client to look at the messages.log file for your Liberty Profile server. You will find quite a few new messages as a result of the server.xml updates. In particular, lookfor these messages:CWPKI0803A: SSL certificate created in 2.823 seconds. SSL key file:

/u/libserv/liberty/servers/server1/resources/security/key.jks

CWWKO0219I: TCP Channel defaultHttpEndpoint-ssl has been started and is now listening for requests on host * (IPv4) port 9443.

SRVE0169I: Loading Web Module: z/OS Connect.

SRVE0250I: Web Module z/OS Connect has been bound to default_host.

Note: The z/OS Connect application is marked protected, which means SSL must be used. You configured Liberty Profile to use an internal (that is, not SAF) implementation of SSL certificates. These messages are indicating SSL is enabled and the z/OS Connect application is loaded.

From a browser, send in the following URL:

http://wg31.washington.ibm.com:9080/zosConnect/services

Three things will occur:

1. Your browser will challenge you because the SSL certificate is signed by a CA not well-known to the browser. Accept the challenge.

2. Your browser will be redirected to the 9443 SSL port of the server

3. You will be prompted to enter a userid and password.

As noted, you will receive a basic authentication prompt:

Enter the ID of Fred and the password of fredpwd. (Both are case sensitive.) You should then see:

That's JSON, and that's z/OS Connect telling you no services are configured. That's correct ... you've not configurded any. Yet. That comes next.

Note: Liberty Profile is checking the Fred ID and password against what's configured in the server.xml file. That's "basic registry." Later you'll see Liberty using SAF as its registry.

Right now we have the ID of FRED created in SAF as well. It was created in the ZCRACF1 job you ran earlier. There's a known bug where Liberty Profile z/OS will do a cursory check of SAF even though basic register (XML-based registry) is configred. The workaround is to have FRED in SAF, even though that's not where the password validation check is actually made.

Close the browser. From this point forward we will use Firefox and a REST client we have installed as an add-on to Firefox.



Configure backend CICS service and validate

Note: Earlier you validated use of WOLA to CICS, and you invoked the OLACB01 sample echo program. Here you will use z/OS Connect as a front-end to OLACB01 for REST/JSON clients.

Using =3.17, edit your server.xml again. Add the following highlighted lines:

: <authorization-roles id="zos.connect.access.roles"> <security-role name="zosConnectAccess"> <user name="Fred"/> </security-role> </authorization-roles> <zosConnectService id="CICS" invokeURI="/myCICSBackend" serviceName="CICS-backend" serviceRef="wolaCICS" /> <localAdaptersConnectService id="wolaCICS" registerName="CICSXREG" serviceName="OLACB01" connectionFactoryRef="wolaCF" /> <zosLocalAdapters wolaGroup="GROUP" wolaName2="NAME2" wolaName3="NAME3" /> :

Save the file (F3).

Start the Firefox browser.

Issue the following URL to display the configured services:

https://wg31.washington.ibm.com:9443/ATSSample1Web/

Why? We need to get past the security challenge caused by the Liberty server's self-signed certificate. The REST client you will use can't do that automatically. Later we'll show the use of certificates which will not challenge you each time SSL is being set up.

Accept the security challenge and add the exception (which is caused by the self-signed certificate being issued by Liberty Profile at the moment).

You'll get a page that looks like this:

In the upper-right corner of the browser, click the following icon:



You should see a panel that looks like this:

Now send in the URL to list the configured services. Do the following:

Set the method to GET

Enter this URL:https://wg31.washington.ibm.com:9443/zosConnect/services

Click "Send"

You will prompted to enter a userid and password. Enter Fred and fredpwd (both are case sensitive:

When the response comes back, click on the "Response Body (Preview)" tab and you should see the following:

That is JSON nicely formatted by a REST client that understands JSON.

Note: All we've done is validate that z/OS Connect is up and that it recognizes the configured service. To actually drive the service we need to setup the WOLA connection into CICS again.That's next.



Open a "WG31" 3270 Window – either from the desktop or "File" and "Start the Same" – and open a CICS terminal session as you did before20.

Clear the screen and enter the following command21, just like you did before:




Go back to the REST client and set a header so what the client sends in is understood by z/OS Connect as JSON:

and then provide Content-Type for the name and application/json for the value:

You should see this under "Headers":

20 At the main green screen enter CICSX and hit enter. Then clear the screen and enter the WOLA commands.21 The BBOC START_TRUE command is not needed because we left the TRUE up after the last lab. We took down the

Link Server Task (BBOC STOP_SRVR), which is why we needed to re-issue that here.



Now we're ready to send in JSON to z/OS Connect and have it talk to the backend CICS. Do the following (with notes following bitmap picture):

Select the PUT method

Place the following URL in the field at the top:https://wg31.washington.ibm.com:9443/zosConnect/services

/CICS-backend?action=invoke

Note: Get that long string from the copy-and-paste file on the desktop.

For the Body, supply the following JSON string22: {"name":"value"}

Click the "Send" button

In response you should see23:

Let's see what that looked like in CICS. Go to =SDSF.DA and set PRE CICS*

Put a question mark ( ? ) next to the CICSX task and hit enter:

22 z/OS Connect requires JSON on PUT or POST. The JSON you're supplying here is really just a dummy string, but it's good enough to satisfy z/OS Connect. Later you'll do data conversion and send in more meaningful JSON.

23 That service is configured to invoke the OLACB01 echo program. It simply echoed back the JSON you sent in.



That brings up a list of DD output for the region. Enter an S next to the CEEMSG output:

Scroll to the bottom (F8, or M in the input field and F8 to max scroll to the bottom). You shouldsee something like this:

That's the {"name":"value"} you sent over, but in ASCII as displayed by an EBCDIC system like z/OS. We're setting the stage for data conversion. Three key points to take awayfrom this:

1. If no data conversion is configured for the z/OS Connect service, then z/OS Connect will simplypass the data over as JSON. The target application would need to understand the JSON format. OLACB01 does ... or, more precisely, OLACB01 doesn't care.

2. If no data conversion is configured, then the data is passed through as ASCII. Again, the targetapplication would need to understand the ASCII encoding. OLACB01 doesn't care.

3. If z/OS Connect passes JSON to the backend, then z/OS Connect expects it will get JSON back. The OLACB01 program is a simple echo program and it did just that.

One final thing to show ... the use of the invokeURI= . Earlier (page 23) you added that to the server.xml as part of configuring the service and the WOLA provider24.

Go to the REST client. In the URL field at the top, type in the following:

https://wg31.washington.ibm.com:9443/myCICSBackend

All the rest is exactly the same as before – PUT operation, JSON as payload, Send button.

You should get the exact same response back as you did with the longer ?action=invoke URL. The value of invokeURI= is it provides you a way to "hide" details of the backend service behind an alias of sorts. The URI is shorter, and use of z/OS Connect is not obvious from the URI.

Configure data transformation to CICS Edit the server.xml file and add the highlighted lines. The lines may be found in the copy-

and-paste file on the desktop:

: <zosConnectService id="CICS" invokeURI="/myCICSBackend" serviceName="CICS-backend" dataXformRef="xformJSON2Byte" serviceRef="wolaCICS" />

24 If you wish, go look at your server.xml. You see it as invokeURI="/myCICSBackend"



<zosConnectDataXform id="xformJSON2Byte" bindFileLoc="/u/libserv" bindFileSuffix=".wsbind" requestSchemaLoc="/u/libserv" responseSchemaLoc="/u/libserv" requestSchemaSuffix=".json" responseSchemaSuffix=".json" /> <localAdaptersConnectService id="wolaCICS" registerName="CICSXREG" serviceName="OLACB01" connectionFactoryRef="wolaCF" /> :

Note: The first line points to the data transform definition to be used by the configured service. The second block of lines defines the data transformation elements ... mostly where the data conversion and JSON schema files reside. Those don't yet exist ... you'll create those next.

Save the file (F3).

Use ISPF =3.4 and list USER1.ZCONN.CNTL. Put a b next to the data set to browse the members in the data set. You should see something like this:

You used ZCRACF1 and ZCRACF2 earlier. Now you'll use LS2JS to generate data conversion bind files for OLACB0125.

Browse the CB01COPY member. This is from the OLACB01 sample job you compiled earlier. Itlooks like this:

It's very simple – a single input and output COMMAREA field of 80 bytes. Your programs mayhave more complex definitions. Exit browse with F3.

25 BBGJS2LS and BBGLS2JS are JCL procs supplied with z/OS Connect. They require no modification. We copied them to this PDS for you. CB01COPY contains the data definition from the OLACB01 sample you compiled earlier. LS2JS is a relatively simple JCL job we created ahead of time that runs the data conversion utility.



Browse the LS2JS member. That looks like this:

That calls the JCL proc BBGLS2JS and passes in the parameters. Those parameters indicate where the program data structure can be found and where the bind files and JSON schema files will go. Exit the browse session with F3.

Submit LS2JS by typing sub next to the member and hitting enter:

Look for RC=0.

Use =3.17 to see the contents of the /u/libserv directory. It should contain the files generated by the utility:

Recall that the server.xml update pointed to the /u/libserv directory as the location of these files.

Browse (with a b next to the file name) the CICS-backend_request.json file. This is the schema for the request. The JSON you send in must adhere to this schema. Development tools can be used to format the JSON based on complex schema. In this workshop we'll simply give you the JSON that works.

Press F3 to exit browsing the file.



Go back to the REST client and do the following:

Note: If you wish, use the REST client "Favorite Requests" function (top menu bar) to save these settings so you can pull it up more quickly in the future.

You should get back the following, which is the JSON response:

But the real validation is to see what came through to CICS. Go to =SDSF.DA, set the prefix to PRE CICS*, place a question mark next to the CICSX region task and then an S next to the CEEMSG output. Then go to the bottom. You should see this:

Contrast that with what we saw before data conversion was in effect:

Without data conversion JSON in ASCII was passed through. With data conversion the message contained in the JSON was stripped out, converted to EBCDIC and passed over to CICS.

OLACB01 was a very simple example. The process for generating bind files for a more complex data structure is the same. The server.xml updates simply point to where the bind files and schema files are located.

Exit the view of the CICS region output by pressing F3.



Explore REST APIs

Note: All the URL strings shown here are in the copy-and-paste file on the desktop.

Go to the REST client and perform a GET operation with the following URL:

https://wg31.washington.ibm.com:9443/zosConnect/services

You should get back the one configured service you have right now:

If you had several services configured it would show them all26.

Now perform a GET operation to see the details of that service:

https://wg31.washington.ibm.com:9443/zosConnect/services/CICS-backend

You get back a bit more detail:

26 The "authorization interceptors" can limit what a given ID can do and see. More on that in the security unit.



Perform a GET with the following URL to see the status of the service:


/CICS-backend?action=status

You should see that the service is currently "Started":

The next REST API requires a PUT operation. Make sure that method is selected and the JSON body field is clear. Then PUT this URL:


/CICS-backend?action=stop

You should get JSON back indicating the service is stopped:

Try to invoke the service with the JSON as shown on page 30. You will get a message that looks like this:CWWKB0451I: The CICS-backend service is stopped. The request is rejected.



Clear the JSON payload field of the REST client and then restart the service with a PUT operation and the following URL:


/CICS-backend?action=start

You will get JSON indicating the service is started, just as you did when you initially issued theaction=status API.

Perform a GET operation with the following URL to get the JSON request schema for the service:


/CICS-backend?action=getRequestSchema

You should get back a JSON object containing the schema:

That is the JSON schema generated by the LS2JS job you ran earlier. z/OS Connect knew the directory where the schema was located based on the information in the server.xml. It read the schema and returned it to the client as a JSON object.

GET the response schema in the same way:


/CICS-backend?action=getResponseSchema

Similar response. Different schema file, but the process for request and response is the sameexcept for the action= value.

Finally, get some statistics for this service with a GET operation and this URL:


/CICS-backend?action=getStatistics

You get back the number of requests this service has provided.



Note: The "audit interceptor" provides SMF 120.11 records for each request. That is a much better tool for capturing and analyzing service metrics with z/OS Connect.

On the CICS terminal session, clear the screen and enter the command:

BBOC STOP_SRVR RGN=CICSXREG

That will stop the Link Server task and avoid it timing out after a long delay.

Close your instance of Firefox.

End of Unit 3 Lab



Unit 4 Lab – z/OS Connect Security TopicsReview SAF jobs submitted earlier

If not already logged on, log onto TSO with USER1.

Use ISPF =3.4 and browse the USER1.ZCONN.CNTL(ZCRACF1) member. Take a moment and read the comments we offer below about what that job did:

Notes:

1. Deleted the Angel and Server STARTED profiles, just in case they were out there already.

2. Added the users27 and groups.

3. Defined the STARTED profiles to enable the Angel and the server to start as started tasks and get the proper ID assigned.

27 As noted earlier, the 'FRED' ID is added here to overcome a known problem of Liberty performing a SAF check for the existence of the ID even though the basic auth information is in server.xml. Note that FRED has no password here.



Back out of your browse session with F3. Then browse the ZRACF2 job and note what it does:

Notes:

1. The LIBSERV ID we used earlier when creating the server has its password removed. It is now an ID used exclusively for the started task.

2. The SERVER profiles are created and the LIBSERV ID is granted READ to them.

3. The CBIND profile is created. This allows WOLA registration into the Liberty Profile server. TwoIDs are granted READ to this.

Note: We have you create the SERVER and CBIND profiles back in the first lab, which was before you did any z/OS Connect work. That's because these profiles were required to validate WOLA.

4. The APPL profile is created.

Back out of the browse session with F3.



Moving basic authentication and role checking to SAF

Note: Up to this point in the labs both basic authentication and z/OS Connect access role checking was done with definitions in the server.xml file. In this section you will move both security functions to SAF.

Use ISPF =3.4 and browse the USER1.ZCONN.CNTL data set ZCRACF3 member. You should see what's illustrated here. Note the comments offered here:

Notes:

1. An EJBROLE is created for access to the z/OS Connect application.

2. Note that initially nobody has READ access to it.

3. The ADDGROUP statements have nothing to do with basic authentication or role checking. They are for the authorization interceptor section later.

4. The FRED ID is granted a password that is different from what was defined in the server.xml file (XML had fredpwd while here the password is equal to the ID)

Submit the job by typing sub in the command line and hitting enter:

Look for the indication the job has completed with RC=0.

Use ISPF =3.17 to edit the server.xml file, which is located in this directory:


Remove the lines shown below with strikethrough, and add the highlighted lines. Get the lines to add from the copy-and-paste file on the desktop:

: <featureManager> <feature>jsp-2.2</feature> <feature>zosLocalAdapters-1.0</feature> <feature>appSecurity-2.0</feature> <feature>zosConnect-1.0</feature> <feature>zosSecurity-1.0</feature> </featureManager> <keyStore id="defaultKeyStore" password="Liberty"/> <webAppSecurity allowFailOverToBasicAuth="true" /> <basicRegistry id="basic1" realm="zosConnect">



<user name="Fred" password="fredpwd" /> </basicRegistry> <authorization-roles id="zos.connect.access.roles"> <security-role name="zosConnectAccess"> <user name="Fred"/> </security-role> </authorization-roles>

<safRegistry id="saf" /> <safAuthorization id="saf" /> <safCredentials unauthenticatedUser="WSGUEST" profilePrefix="BBGZDFLT" />

<zosConnectService id="CICS" invokeURI="/myCICSBackend" serviceName="CICS-backend" dataXformRef="xformJSON2Byte" serviceRef="wolaCICS" /> :

Save the file by pressing F3. The server will dynamically update with the new information.

Open an instance of Firefox and send the following URL:


Accept the security challenge.

You will receive a prompt:

Enter a user name of Fred and a password of fredpwd

You will find the prompt pops back up. This is expected because the ID/password you entered is from the earlier server.xml definition. z/OS Connect is now checking SAF, and ifyou recall from the ZCRACF3 job the ID of FRED has a password of FRED.

In TSO, go to =SDSF.LOG and look for the following message near the bottom of the log:

ICH408I USER(FRED ) GROUP(LIBGRP ) NAME(USER FRED ) LOGON/JOB INITIATION - INVALID PASSWORD IRR013I VERIFICATION FAILED. INVALID PASSWORD GIVEN.

That's exactly what happened ... the ID for Fred you entered (fredpwd) was not correct.



At the logon prompt in Firefox, enter the ID of FRED and the password of FRED. (Neither is case sensitive in SAF, so any variation of case will work okay.) You should get the following:

In TSO, go to =SDSF.LOG again and look for the following message28:

ICH408I USER(FRED ) GROUP(LIBGRP ) NAME(USER FRED ) BBGZDFLT.zos.connect.access.roles.zosConnectAccess CL(EJBROLE ) INSUFFICIENT ACCESS AUTHORITY ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )

This is expected: the ZCRACF3 job created the EJROLE but did not grant FRED access to it.

In TSO, go to =6 and enter the following command as one long line:

PE BBGZDFLT.zos.connect.access.roles.zosConnectAccess

CLASS(EJBROLE) ID(FRED) ACCESS(READ)

Hint: Get the string from the copy-and-paste file on the decktop:

You will get a ICH06011I message indicating changes will not take effect until a refresh is issued. Hit enter to clear the screen, then clear the previous command (the "End" key) and then enter the following:

SETR RACLIST(EJBROLE) REFRESH

Close Firefox and restart it29. Once again, enter the URL:


Accept the security challenge as you've done before.

At the authentication prompt, enter FRED with a password of FRED. You should see the following:

That is an unformatted JSON object listing the configured services. Receiving that indicates that your FRED ID was authenticated and authorized based on the EJBROLE.

28 You may see multiple instances of this message ... that's Liberty Profile behavior at work.29 A refresh here would also work. But we wanted you to see the prompt and acceptance of both ID/PW and READ to the

EJBROLE.



Authorization interceptors

Note: In this section we're going to restrict what Fred is allowed to do with z/OS Connect.

Open a "WG31" 3270 Window – either from the desktop or "File" and "Start the Same" – and open a CICS terminal session as you did before30.

Clear the screen and enter the following command31, just like you did before:




In Firefox, start the REST client:

As you did earlier, drive the REST client against the backend CICS program:

Notes:

1. Set the header to Content-Type and application/json

2. Set the method to PUT

30 At the main green screen enter CICSX and hit enter. Then clear the screen and enter the WOLA commands.31 The BBOC START_TRUE command is not needed because we left the TRUE up after the last lab. We took down the

Link Server Task (BBOC STOP_SRVR), which is why we needed to re-issue that here.



3. Set the URL to https://wg31.washington.ibm.com:9443/myCICSBackend

4. Set the JSON payload to what we used before (get from copy-and-paste file)

5. Click the "Send" button

It should succeed just like it did in the earlier lab:

Note: The ability to invoke a service means Fred has at least "Invoke" authority. Does Fred have more authority than that? At the moment, yes. We will prove that next.

In the REST client, do the following:

Leave the method as PUT

Change the URL to:

https://wg31.washington.ibm.com:9443/zosConnect/services/CICS-backend?action=stop

That's one long URL. Get from the copy-and-paste file.

Clear the request data payload area


What you should see in return is an indication the service is stopped:

Note: You did this in the earlier "Explore the REST APIs" lab. The ability to issue this action=stopcommand indicates Fred has "Operations" authority as well as "Invoke." Actually, Fred has "Admin" authority at this moment because absent the authorization interceptor, any ID with access to the EJBROLE has full Admin.



Restart the service by changing the URL to:


/CICS-backend?action=start

and clicking the "Send" button. You should get back JSON indicating the service has been started: "serviceStatus": "Started"

In TSO, go to =3.17 and edit the server.xml file. Add the highlighted lines, which you can get from the copy-and-paste file on the desktop:

<safRegistry id="saf" /> <safAuthorization id="saf" /> <safCredentials unauthenticatedUser="WSGUEST" profilePrefix="BBGZDFLT" /> <zosConnectManager globalAdminGroup="GADMIN" globalOperationsGroup="GOPERS" globalInvokeGroup="GINVOKE" globalInterceptorsRef="interceptorList_g" /> <authorizationInterceptor id="auth" /> <zosConnectInterceptors id="interceptorList_g" interceptorRef="auth"/> <zosConnectService id="CICS" invokeURI="/myCICSBackend" serviceName="CICS-backend" dataXformRef="xformJSON2Byte" serviceRef="wolaCICS" />

Save the changes by entering F3 to exit the edit session.

Go back to the Firefox REST client and try to stop the service with the URL you used earlier (hint: ?action=stop on the end of the URL). You will find Fred is now unable to issue that command. It fails with "Error 403" and "CWWKB0409W: User Fred is not authorized to perform the request."

Note: This indicates Fred does not have "Operations" authority. Does Fred have other authority? Let's see ...

In the REST client do the following:

Set the URL to https://wg31.washington.ibm.com:9443/myCICSBackend

Set the request payload to the following (get from copy-and-paste file):{ "OLACB01Operation": { "dfhcommarea": { "message_data": "Hello!" } }}

Click the "Send" button.



You will get the same "Error 403" message you received earlier.

Note: Right now Fred has no authority. He has READ to the EJROLE, which allows him access to the z/OS Connect application, but he does not have membership in any of the authorization interceptor groups (GADMIN, GOPERS, GINVOKE). The next step in the lab is to connect Fred to one of the groups.

In TSO, go to =6 and enter the following command:

CO FRED GROUP(GINVOKE)

That gives Fred membership to the GINVOKE group, which should allow him to invoke the service but not perform any operations activities against it.

Once again, in the REST client, do the following:




Now you should see the same success indication we saw earlier:

Fred has membership in GINVOKE, so Fred has invoke priviledges.

Now check Fred's ability to issue an operationsl API. In the REST client, do the following:

Leave the method as PUT

Change the URL to:

https://wg31.washington.ibm.com:9443/zosConnect/services/CICS-backend?action=stop

That's one long URL. Get from the copy-and-paste file.

Clear the request data payload area


You should see the Error 403 message. Fred is not a member of GOPERS, so he does not have authority to issue operations APIs.



Passing identity over WOLA into CICS

Note: Up to this point we have created a WOLA registration with SEC=N, meaning no security assertion over WOLA into CICS will be attempted. In this section we will show how Fred's ID can be asserted over so the invocation of the target program can be performed under Fred's ID.

Use ISPF =3.4 and browse the USER1.ZCONN.CNTL data set ZCRACF4 member. It is somewhat long and involved. Short version: it is enabling SAF to support CICS security beingenabled for a region.

In the command line enter sub and press enter to submit the job. You should get a RC=0 after a few moments.

Use ISPF =3.4 to edit the member CICSX.CICS42.SYSIN(CICSXSIP). Change SEC= to YES, XTRAN= to YES and add a line for XUSER=YES:

APPLID=CICSX CICSSVC=216 DB2CONN=YES EDSALIM=200M SEC=YES XTRAN=YES XUSER=YES XCMD=NO XDCT=NO XFCT=NO XJCT=NO

Press F3 to save the changes and exit the edit session.

Go to the CICS terminal session and do the following:

Clear the screen and then enter the following command:BBOC STOP_SRVR RGN=CICSXREG

Look for the following message:WOLA TRACE 0: Stop server completed successfully.

Clear the screen again and enter:BBOC STOP_TRUE

Look for the following message:WOLA TRACE 0: Exit disabled Successfully.

Go to =SDSF.LOG and stop the CICS region with the following command:

/F CICSX,CEMT PERFORM SHUTDOWN

Restart the CICS region:

/S CICSX

In TSO use =3.17 to edit the server.xml file. Add the highlighted line:

: <localAdaptersConnectService id="wolaCICS" registerName="CICSXREG" serviceName="OLACB01" connectionFactoryRef="wolaCF" /> <zosLocalAdapters useCicsTaskUserId="true"



wolaGroup="GROUP" wolaName2="NAME2" wolaName3="NAME3" /> <connectionFactory id="wolaCF" jndiName="eis/ola"> <properties.ola /> </connectionFactory> :

Press F3 to save the changes and exit the edit session.

Because you stopped CICS earlier, your second 3270 emulator session went into a disconnected state. Reconnect with Communication Connect.

When you get the green screen, enter CICSX. You should get the CICS screen.

Clear the screen and enter CESN

Logon with ID of USER1 and password USER1. If successful, you should see the following message at the bottom of the screen:

DFHCE3549 Sign-on is complete (Language ENU).

Clear the screen and enter BBOC START_TRUE

Clear the screen again and enter the following:

BBOC START_SRVR RGN=CICSXREG DGN=GROUP NDN=NAME2 SVN=NAME3 SVC=*

MNC=1 MXC=10 TXN=N SEC=Y REU=N TRC=1

Once again, in the REST client32, do the following:

Set the method to PUT




Rather than success, what you will see is this:

Fred's ID was asserted over WOLA, but we've not yet given Fred's ID the authority to operate inside of CICS.

32 This assumes you left Firefox up from before. If not, the restart Firefox and re-establish the SSL by entering the /zosConnect/services URL (from copy/paste file) and accepting the security challenge. You will get Error 403 message because Fred has invoke authority only, but that's okay.



Click the "Abort" button to stop the REST client's attempt to send the message.

In TSO, go to =SDSF.DA and set the prefix for CICS*. This will show the started CICS region.

Put a question mark ( ? ) next to CICSX and press enter.

Put an S next to BBOOUT and press enter:

Scroll to the bottom (PF8) and look for this message:

That's WOLA telling you the FRED ID was asserted across and into CICS.

Go to =SDSF.LOG and you should see this:

ICH408I USER(FRED ) GROUP(LIBGRP ) NAME(USER FRED BBO# CL(TCICSTRN) INSUFFICIENT ACCESS AUTHORITY FROM BB* (G) ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )

That's RACF telling you FRED did not have access.

Go to =6 and enter the following command:

PERMIT BBTRAN CLASS(GCICSTRN) ID(FRED) AC(READ)

Then:

SETR RACLIST(TCICSTRN) REFRESH

You will see the following messages, which is okay:ICH14070I SETROPTS RACLIST REFRESH had no effect on class ACICSPCT.ICH14070I SETROPTS RACLIST REFRESH had no effect on class CCICSCMD.ICH14070I SETROPTS RACLIST REFRESH had no effect on class DCICSDCT.ICH14070I SETROPTS RACLIST REFRESH had no effect on class FCICSFCT.ICH14070I SETROPTS RACLIST REFRESH had no effect on class JCICSJCT.ICH14070I SETROPTS RACLIST REFRESH had no effect on class MCICSPPT.***



Go back to the REST client and click the "Send" button again. This time it will work:

Go back to the CICS region BBOOUT held output (under =SDSF.ST) and you should see the following:

:Initiated under userid: FRED Data to be passed in a COMMAREA Calling Get Data API with connhdl: 000002000450035000000001 Get data request completed Copied linkparms to tsq: BBO00051 EXEC CICS LINK to PROGRAM: OLACB01 EXEC CICS LINK to OLACB01 with Commarea Successful! Calling Send Response API. connhdl: 000002000450035000000001 Calling Send Response, sending 80 bytes... Send Response completed. Releasing conn back to pool. connhdl: 000002000450035000000001Release connection back to pool completed. Return Code: 0 rsn Code: 0 Elapsed time: 0.000000 seconds Elapsed CPU time: 0.000889 seconds



SAF certificates and client certificate authentication Use ISPF =3.4 and browse the USER1.ZCONN.CNTL data set ZCRACF5 member. It is

somewhat long and involved. Take a moment to review this picture and the notes that follow:

Notes:

1. A Certificate Authority (CA) certificate is created

2. That CA cert is exported to a data set for download to the browser in an upcoming step

3. A server certificate is created and signed by the CA created in step one

4. A keyring is added to the LIBSERV ID

5. The server and CA certificates are connected to the keyring created in step four

6. A client certificate is created for Fred

7. Fred's client certificate is exported for download to the browser in an upcoming step

8. The LIBSERV ID is granted access to the keyring and cert

In the command line enter sub and press enter to submit the job. You should get a RC=0 after a few moments.

Next, the two exported data sets need to come down to the workstation. Do the following:

On the Windows desktop, open a command prompt

Enter the command: cd C:\temp

Enter the command: ftp wg31.washington.ibm.com

Logon with USER1 and the password for that ID

Enter the command: bin (this will set FTP mode to binary, or 'image')

Enter the command: GET 'USER1.CERTAUTH.CRT' certauth.crt



Enter the command: GET 'USER1.FRED.P12' fred.p12

Enter the command: quit

With the certificates downloaded, the next step is to import them into Firefox. That's next.

In Firefox, go to Tools Options

Click on "Advanced," then the "Certificates" tab, then click on "View Certificates":

Then click on the "Authorities" tab, and the "Import" button:

Navigate to the C:\temp directory and double-click on the certauth.crt file.

Then click the "Trust this CA to identify websites" checkbox and click "OK":



Verify the certificate has been imported by scrolling down and looking for the "CA for Liberty" certificate in the list:

Next, click the "Your certificates" tab and then the "Import" button:

It should open up at the C:\temp directory from before, but if not then navigate to that location. Locate the fred.p12 certificate and double-click on it.

A window will appear asking you to enter the password for the certificate:

Enter the value33 secret and click "OK". You should see confirmation:

Click "OK" to clear the confirmation, then "OK" to close the certificate manager panel, "OK" to close the options panel, and then close all instances of your Firefox browser.

33 Look at the ZCRACF5 job and you'll see where that password was specified when Fred's certificate was exported.


Use ISPF =3.17 to edit the server.xml file. Remove the lines with strikethrough and add the highlighted lines:

<server description="new server">  <featureManager> <feature>jsp-2.2</feature> <feature>zosLocalAdapters-1.0</feature> <feature>appSecurity-2.0</feature> <feature>zosConnect-1.0</feature> <feature>zosSecurity-1.0</feature> <feature>ssl-1.0</feature> </featureManager> <keyStore id="defaultKeyStore" password="Liberty"/> <sslDefault sslRef="DefaultSSLSettings" /> <ssl id="DefaultSSLSettings" keyStoreRef="CellDefaultKeyStore" trustStoreRef="CellDefaultTrustStore" clientAuthenticationSupported="true" clientAuthentication="true"/> <keyStore id="CellDefaultKeyStore" location="safkeyring:///Keyring.LIBERTY" password="password" type="JCERACFKS" fileBased="false" readOnly="true" /> <keyStore id="CellDefaultTrustStore" location="safkeyring:///Keyring.LIBERTY" password="password" type="JCERACFKS" fileBased="false" readOnly="true" /> <webAppSecurity allowFailOverToBasicAuth="true" /> <safRegistry id="saf" /> <safAuthorization id="saf" /> <safCredentials unauthenticatedUser="WSGUEST" profilePrefix="BBGZDFLT" /> <zosConnectManager globalAdminGroup="GADMIN" globalOperationsGroup="GOPERS" globalInvokeGroup="GINVOKE" globalInterceptorsRef="interceptorList_g" /> :

Press F3 to exit the edit session. The server will dynamically update itself.

Restart Firefox.

Open the REST client.


As you've done before, populate the screen to send a request into the service with the proper JSON payload. A reminder:

Set the method to PUT

Set the URL to: https://wg31.washington.ibm.com:9443/myCICSBackend

Set the header to Content-Type and application/json

Set the request body to the following (get from copy-and-paste file):{ "OLACB01Operation": { "dfhcommarea": { "message_data": "Hello!" } }}


You will get a "User Identification Request" prompt. The "FRED" certificate should appear in the selection box. Then click "OK":



As before, you should see the following as an indication of succesfully invoking the OLACB01program in CICS:

But did Fred's ID really get propagated into CICS? Let's check ...

Go to =SDSF.DA and set the prefix to CICS*

Put a question mark ( ? ) next to the CICSX started task

Put an S next to the BBOOUT output for CICS

Scroll to the bottom (F8), then scroll up (F7) one or two screens.

Look for this sequence of messages (mixed with others, but seek out these):Userid propagated: FREDSecurity propagation ON. Userid requested: FREDStarting with USERID FREDInitiated under userid: FREDEXEC CICS LINK to PROGRAM: OLACB01EXEC CICS LINK to OLACB01 with Commarea Successful!Return Code: 0 rsn Code: 0

That verifies that the ID of FRED worked its way through z/OS Connect, over WOLA and into CICS. The only prompt for identity was the browser prompt for the certificate. Therefore, Liberty authenticated you using Fred's client certificate.

In summary:

• Fred's client certificate used to authenticate your REST client request

• The FRED ID has READ to the EJBROLE permitting it access to z/OS Connect

• The FRED ID is a member of the GINVOKE group, giving it invoke authority

• CICS security is enabled

• The WOLA registration into Liberty Profile z/OS has SEC=Y

• The server.xml has useCicsTaskUserId="true" on the local adapters definition

• The identity of FRED was asserted across WOLA into CICS, where the BBO$ link server task started an instance of the BBO# invocation task under the ID of FRED. It was under the ID of FRED that the EXEC CICS LINK to the OLACB01 program was performed.

End of Unit 4 LabAnd End of Document


liberty profile z/os and z/os connect hands-on labs · liberty profile z/os and z/os connect...

Documents