I spent a week trying to get MQWEB on z/OS to work using digital certificates using RACF as a repository, and had lots of frustrations, and some successes. I found that to get security working you need an Angel process.
Some parts are well document, some other parts are not, so I’ll try to fill some of the gaps.
How does MQWEB do security?
The Liberty server has a couple of ways of Authentication and Authorisation.
- The basic repository where you define users, passwords and their role (MQWebAdmin, MQWebAdminRO or MQWebUser) within the xml configuration file. This provides the most basic levels of protection – for example the MQ administrator has to create and maintain the passwords. It is easy to set up, but not very secure.
- Using the System Authorization Facility (SAF) interface. This is an interface which applications can use to get to the security back end. There is a choice of back-ends, for example RACF from IBM, and Top Secret from CA. This can be configured to be very secure, but has more administrator work to set up.
How does SAF work?
There are RACF profiles which control access to restricted facilities. If you have access to the profile you can perform the function. For example when you logon to the a server, the server thread has to run as your userid, to allow your userid access to resources. You set up a profile, and explicitly give the server access to the profile permitting the server to “run on behalf of another userid”.
There is a C function on z/OS that allows my userid to check to see if your userid is authorised to a resource. If my userid has access to the correct profile, my userid can get the information about your userid.
Some “system-like” functions assume the requester is authorised, and bypass some of the checks. For example the RACROUTE FASTAUTH check request. These have another level of control in that they need to be in a restricted, Supervisor (kernel) state, to be able to issue the requests.
What is the angel process?
Instead of giving Java programs access to this restricted Supervisor mode, there is an Angel address space which can execute the restricted requests, and the Java program can call the code running in the Angel address space. (Under the covers there is a Program Call to execute the code, in the same way that MQ and DB2 requests do.) Of course, there is a RACF profile to control which address spaces can access the Angel, and other profiles to configure what restricted functions the Angel process can execute.
If the Angel process was not running, I could not logon to MQWEB. There were messages saying my userid did not have access to MQWebAdmin, MQWebAdminRO or MQWebUser. The checking is done within the LIberty and is very simple, and restrictive – and does not work because it looks for group names MQWebAdmin etc… but MQWebAdmin is too long for a z/OS group name which can have up to 8 characters in it.
Setting up the Angel process.
- The Angel process can be shared by all of the web servers on the LPAR.
- In a highly available environment you need more than one Angel on an LPAR.
- MQ ships Angel code, but it may be at a different level to other Liberty servers’s Angel code. You should run on the latest level of code, but I expect if they are reasonably current( within 1 year) they should all work ok.
- This gives a good overview of the Angel.
- This also gives a good overview and instructions
- See here for configuration instructions.
- I think the only Angel interface used by MQWEB is SAFCRED (SAF Credentials) and PRODMGR, but it does no harm having access to services you do not use.
- You cannot stop an Angel process if it has servers “connected” to it.
- If you cancel the Angel, the Web Server stops working, it may get CEE3250C The system or user abend S0D6 R=00000027 was issued in the message.log file, and abend.
- For availability you may want two queue managers on an LPAR, so you need two Angel process.
- There is no configuration you do to an Angel, so the only reason why you may want to shut down the Angel during normal running is to apply fixes.
- You need to ensure the Angel process is started before the Web Server is started, as the Web Server only connects at start up, see below.
- Each Angel running in an LPAR needs a unique name. You can have a default, unnamed Angel, or give your Angel a name.
I called my angel process ANGEL. From WAS and z/OS Connect they talk about their Angels with names like BBZANGL, BAQZANGL, which are not very memorable, hard to remember, and easy to mistype.
You start an angel process (once the JCL has been configured) using a command like
- S ANGEL
- S ANGEL,NAME=ANGEL1
- S ANGEL.ANGEL1,NAME=ANGEL1
- S ANGEL.ANGEL2,NAME=ANGEL2
The first command starts the default, unnamed, Angel.
Using the S ANGEL.name command is useful if you have more than one angel as it means you can use the STOP name command to that particular instance.
Configure your web server to end if the angel is not available
You can configure your Liberty server to end if the Angel process is not running. Without it, the Web Server would start, and requests to use it would fail, because the unauthorised interface would be used. Using this option means you find out Sunday night and not when your business starts at 0900 on Monday morning!
You configure it by editing the server jvm.options file by adding
-Dcom.ibm.ws.zos.core.angelRequired=true
If the Angel is not available, this statement prevents the Web Server from starting
You can specify the angel name using
-Dcom.ibm.ws.zos.core.angelName=MYANGEL
If you are using the default angle name, comment this out
# -Dcom.ibm.ws.zos.core.angelName=
When your Web Server starts you should get messages in the message.log like
CWWKB0103I: Authorized service group SAFCRED is available.
Tracing violations.
You can start an Angel using
S ANGEL,SAFLOG=YES
I gave my MWEB userid no access to SAFCRED, and restarted MQWEB. With SAFLOG=YES, I got the following on the joblog
ICH408I USER(START1 ) GROUP(SYS1 ) NAME(####################)
BBG.AUTHMOD.BBGZSAFM.SAFCRED CL(SERVER )
INSUFFICIENT ACCESS AUTHORITY
ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )
and in the MQWEB directory/logs/message.log file
CWWKB0104I: Authorized service group SAFCRED is not available.
With SAFLOG=NO, there was no message on the joblog, but the same message in MQWEB directory/log/message.log file
CWWKB0104I: Authorized service group SAFCRED is not available.
From this we can see that you should always specify SAFLOG=YES.
Angel commands
You can use
F ANGEL,DISPLAY,SERVERSThis gives a message like
CWWKB0052I ACTIVE SERVER ASID 3f JOBNAME CSQ9WEB
You can use
F ANGEL,TRACE=Y
This writes a trace to //STDOUT in the Angel job.
The output is like
Trace: 2020/07/25 15:38:07.877974 t=8D5E88 key=S2 (04002008)
Description: write_to_operator_location, entry
message_p: CWWKB0057I WEBSPHERE FOR Z/OS ANGEL PROCESS ENDED NORMALLY
Which is not very helpful, as it traces what the Angel process is doing – rather than the Web Servers using it.
ColinPaice 