Authorization requirements for monitoring IBM Integration Bus on z/OS with OMEGAMON for Messaging

Resolving The Problem

The following actions are required to authorize IBM® Integration Bus Monitoring agent (formerly called WebSphere® Message Broker Monitoring agent) to receive broker data.

To authorize IBM Integration Bus Monitoring agent on z/OS® systems, do the following procedure:

1. Ensure that the started task procedure user ID of the agent is a member of the primary group of the broker's user ID in UNIX System Services. If that is not possible, the other choice is that the started task procedure user ID of the agent is the same as the broker's user ID. 

2. Ensure that the started task procedure user ID of the agent has read access to files in the component directories that is used by the monitored brokers.

3. Ensure that the started task procedure user ID of the agent has access to the USS directory that is created by PARMGEN jobs (KQIUSPJB and KQIUSSJB) during agent configuration.
The USS directory is determined by the KQI_HFS_HFSROOT_DIR parameter. The agent needs the access to create the log directory and log files within this USS directory. 

4. Ensure that the started task procedure user ID of the agent has the access to subscribe to the broker publications under the $SYS/Broker topic tree.
The procedure of assigning appropriate access might depend on how IBM MQ is secured, which manages the pub/sub part. 

5. Ensure that the started task procedure user ID of the agent has the following authorizations:

• Authorization to run the MQOPEN and MQPUT commands on SYSTEM.BROKER.ADMIN.QUEUE and SYSTEM.BROKER.CONTROL.QUEUE
• Authorization to use SYSTEM.BROKER.MODEL.QUEUE as a model queue during MQOPEN processing
• Authorization to run the MQOPEN (for create) and MQGET commands from KQI.AGENT.REPLY.QUEUE (or the reply queue specified in the agent parameters)

6. Ensure that the started task procedure user ID of the agent is specifically permitted (in RACF®) to access the UNIXPRIV class SUPERUSER.PROCESS.GETPSENT.
If you do not do this step, the KQIA153E message with return code 319030247 is contained in the agent log, job names, start dates, and times. The ASID information from brokers or execution groups will be missing. Messages stating that a broker or execution group has a status of started when it is not actually started might be displayed.
UNIXPRIV SUPERUSER.PROCESS.GETPSENT is described in the Using UNIXPRIV Class Profiles section in the Establishing UNIX Security chapter of the IBM UNIX System Services Planning manual. To configure the agent, do the following steps:
a. Define a profile in the UNIXPRIV class to protect the resource called SUPERUSER.PROCESS.GETPSENT, by running the following command:
RDEFINE UNIXPRIV SUPERUSER.PROCESS.GETPSENT UACC(NONE)
b. Assign the started task procedure user ID of the agent by running the following command:
PERMIT SUPERUSER.PROCESS.GETPSENT
CLASS(UNIXPRIV) ID(xxxxxxx) ACCESS(READ)
where xxxxxxx is the user ID.
c. Activate the UNIXPRIV class, if it is not currently active, by running the following command:
SETROPTS CLASSACT(UNIXPRIV)
d. Activate SETROPTS RACLIST processing for the UNIXPRIV class, if it is not already active, by running the following command:
SETROPTS
RACLIST(UNIXPRIV)
e. If SETROPTS RACLIST processing is already in effect for the UNIXPRIV class, refresh SETROPTS RACLIST processing so that the changed profile in the UNIXPRIV class can take effect. Run the following command:
SETROPTS
RACLIST(UNIXPRIV) REFRESH

7. If you enabled administration security for your broker, you must authorize the agent appropriately for the IBM Integration API (also known as CMP) that the agent uses for monitoring the broker. The method of authorizing the agent depends on whether you have enabled MQ queue-based authorization or file based authorization in the broker. Refer to IBM Integration Bus documentation for more details about administration security. Note that when the IBM Integration Bus documentation refers to a role name or the system ID, the started task procedure user ID of the agent is to be used as the role name to check for configured files or MQ mode permissions.
You must grant the following access to the started task procedure user ID of the agent according to your needs:

• The started task procedure user ID of the agent must be authorized for Read/Inquire (RACF READ) access.
• If you want the agent to be able to issue Start or Stop Take Action commands, the started task procedure user ID of the agent must be authorized for Execute/Set (RACF ALTER) access.
• If you want the agent to be able to issue Change Take Action commands, the started task procedure user ID of the agent must be authorized for Write/Put (RACF UPDATE) access.

MQ queue-based authorization mode
The MQ queue-based authorization mode is used by default given that a queue manager is associated with the broker. Complete the following steps for authorization:
a. Determine the started task procedure user ID of the agent.
b. Authorize that ID for Read/Inquire (RACF READ) access to the following queues in the broker queue manager:

• SYSTEM.BROKER.AUTH
• SYSTEM.BROKER.AUTH.** (because there is an additional queue per integration server that requires access, ** means all of them with that high level qualifier for the queue name.)

c. To authorize the agent to issue any Start or Stop Take Action commands, authorize the ID for Execute/Set (RACF ALTER) access to the same queues.
d. To authorize the agent to issue any Change Take Action commands, authorize the ID for Write/Put (RACF UPDATE) access to the same queues.
File based authorization mode
File based authorization mode can also be used on z/OS systems.
You must use the mqsichangefileauth command (member BIPCHFA in the broker PDSE) to set the appropriate authorizations as listed above for both integration broker nodes and integration servers (execution groups). For more information about the mqsichangefileauth command, refer to IBM Integration Bus documentation.