Skip to content

Implementing Basic Authentication Using SAF for the MQ Web Console

Audience level

Some knowledge of MQ, z/OS, and Liberty

Skillset

MQ Administration, z/OS systems programming

Background

Basic authentication uses a user ID and password to access a resource. The MQ Web Console supports two basic authentication approaches: the basic registry and the SAF registry. This lab covers the SAF registry approach.

Modern production environments often prefer stronger authentication approaches such as tokens, passkeys, or enterprise single sign-on. For that reason, this lab should be treated as a learning exercise for sandbox or lab environments rather than a production deployment pattern.

Overview of the exercise

In this lab, you will:

I. Copy zos_saf_registry.xml

II. Alter server.xml

III. Customize zos_saf_registry.xml

IV. Configure RACF for the MQ Web Console SAF registry

V. Start the Liberty angel process

VI. Configure RACF for the angel process

VII. Restart and validate the MQ Web Console

Prerequisites

Before you begin, make sure the following are available:

  • IBM MQ for z/OS with the MQ Web Console installed
  • Access to the mqweb server configuration directory
  • Authority to edit the Liberty configuration files
  • Authority to define and permit RACF resources in the APPL, EJBROLE, and SERVER classes
  • The user ID under which the MQ Web Console started task runs
  • The SAF profile prefix you intend to use, for example MQW942
  • The unauthenticated or pre-authentication user ID you intend to use, for example MQGUEST
  • Authority to start the Liberty angel started task and the MQ Web Console started task

Note: This lab uses MQW942 as the profile prefix and SYSPROG as the started task user in examples. Replace those values with the ones used in your environment.

Exercise

I. Copy zos_saf_registry.xml

  1. From the ISPF main menu, enter:
tso omvs
  1. In OMVS, list the sample MQ Web Console configuration files:
ls /usr/lpp/mqm/V9R4M2X/web/mq/samp/configuration

You should see a list of XML files, including zos_saf_registry.xml.

  1. Change to the mqweb server directory and copy the sample SAF registry file into it:
cd /var/mqm/servers/mqweb
cp /usr/lpp/mqm/V9R4M2X/web/mq/samp/configuration/zos_saf_registry.xml .

Important: Do not miss the final .. It means the file is copied into the current directory.

  1. Type exit to leave OMVS.

  2. Return to the mqweb directory in ISPF and confirm that zos_saf_registry.xml is now present.

II. Alter server.xml

  1. Navigate to the /var/mqm/servers/mqweb directory from ISPF option 3.4.

  2. List the contents of the directory and locate server.xml and zos_saf_registry.xml.

  3. Edit server.xml.

  4. Replace:

<include location="basic_registry.xml"/>

with:

<include location="zos_saf_registry.xml"/>
  1. Save server.xml and exit.

III. Customize zos_saf_registry.xml

  1. Edit zos_saf_registry.xml in ASCII mode.

  2. Modify the sample configuration so it looks similar to the following:

<server>
    <featureManager>
        <feature>appSecurity-2.0</feature>
        <feature>zosSecurity-1.0</feature>
        <feature>basicAuthenticationMQ-1.0</feature>
        <feature>apiDiscovery-1.0</feature>
    </featureManager>

    <enterpriseApplication id="com.ibm.mq.console" />

    <enterpriseApplication id="com.ibm.mq.rest" />

    <safRegistry id="saf" />
    <safAuthorization id="saf" reportAuthorizationCheckDetails="true"/>
    <safCredentials unauthenticatedUser="MQGUEST" profilePrefix="MQW942" suppressAuthFailureMessages="false"/>
    <sslDefault sslRef="mqDefaultSSLConfig"/>
</server>
  1. Review the key values:
  2. profilePrefix="MQW942" identifies the RACF profile prefix used by Liberty and MQ Web
  3. unauthenticatedUser="MQGUEST" identifies the user used before full authentication occurs, allowing the login page to be presented

  4. safAuthorization enables SAF-based authorization for the web console and REST applications

  5. Save the file and exit.

  6. Edit mqwebuser.xml in ASCII mode and make sure it contains a configuration similar to the following:

<server>
    <featureManager>
        <feature>appSecurity-2.0</feature>
    </featureManager>
    <webAppSecurity allowFailOverToBasicAuth="true"/>
    <webAppSecurity overrideHttpAuthMethod="BASIC"/>
    <variable name="httpsPort" value="9443"/>
    <variable name="httpHost" value="-1"/>
    <httpEndpoint host="*" httpPort="-1" httpsPort="9443"
        id="defaultHttpEndpoint"/>
    <sslDefault sslRef="mqDefaultSSLConfig"/>
</server>
  1. Save mqwebuser.xml and exit.

Note: Some sites choose to keep this configuration in a single file. In this lab, the configuration is kept separate to make it easier to switch between basic registry and SAF registry examples.

IV. Configure RACF for the MQ Web Console SAF registry

  1. Return to the ISPF main menu and enter option 6 for the TSO command line.

  2. Define the application profile for the MQ Web Console using your SAF profile prefix. For example:

RDEFINE APPL MQW942 UACC(NONE)
  1. Permit access to users who need to reach the MQ Web login screen, including the unauthenticated user ID specified in zos_saf_registry.xml. For example:
PERMIT MQW942 CLASS(APPL) ACCESS(READ) ID(MQGUEST)
PERMIT MQW942 CLASS(APPL) ACCESS(READ) ID(userID)
  1. Refresh the APPL class:
SETROPTS RACLIST(APPL) REFRESH
  1. Define the EJBROLE profiles used for MQ Console and REST security roles:
RDEFINE EJBROLE MQW942.com.ibm.mq.console.MQWebAdmin UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.console.MQWebAdminRO UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.console.MQWebUser UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.rest.MQWebAdmin UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.rest.MQWebAdminRO UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.rest.MQWebUser UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.rest.MFTWebAdmin UACC(NONE)
RDEFINE EJBROLE MQW942.com.ibm.mq.rest.MFTWebAdminRO UACC(NONE)
  1. Permit users to the appropriate roles. For example, to allow a user full administrative access to the REST API:
PERMIT MQW942.com.ibm.mq.rest.MQWebAdmin CLASS(EJBROLE) ACCESS(READ) ID(userID)

  1. Repeat the necessary PERMIT commands for the MQ Console and REST roles required by your users.

  2. A simple role mapping summary is shown below:

Role Typical use
MQWebAdmin Full administrative access to the MQ Web Console or REST API
MQWebAdminRO Read-only administrative access
MQWebUser Basic user access with fewer administrative capabilities
  1. Refresh the relevant RACF class for these role definitions according to your site standards.

Note: If EJBROLE is RACLISTed in your environment, refresh that class after the updates. The original lab refreshed APPL a second time here, but in practice you should make sure the class containing the updated definitions is refreshed.

V. Start the angel process

  1. The Liberty angel process is a started task that allows Liberty servers to use z/OS authorized services. It is long-lived and can be shared by multiple Liberty servers.

  2. Navigate to SDSF from the ISPF main menu.

  3. In the SDSF command input line, start the angel task:

/S MQANGEL
  1. In SDSF DA, set the prefix to MQ* and confirm that the MQANGEL address space is running.

VI. Configure the MQ Web started task for angel usage

  1. Return to ISPF option 3.4 and navigate to the procedure library that contains the MQ Web started task, for example SYS1.PROCLIB.

  2. Locate the MQWEBS procedure and edit it.

  3. Review the STDENV section. Make sure the following Java option is present in the active environment section used by the started task:

IBM_JAVA_OPTIONS=-Dcom.ibm.ws.zos.core.angelName=MQANGEL

  1. Make sure it is placed in the active environment section, not in an unused or commented section.

  2. Save the procedure and exit.

VII. Configure RACF for angel process access

  1. If you now try to restart the MQ Web Console, it may fail because the started task user ID does not yet have access to the required Liberty angel resources. In the following examples, the MQ Web started task user is SYSPROG.

  2. From ISPF option 6, define a profile for the angel and permit the started task user:

RDEFINE SERVER BBG.ANGEL UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.ANGEL CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for the named angel process using the same profile prefix concept:
RDEFINE SERVER BBG.ANGEL.MQW942 UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.ANGEL.MQW942 CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for the security prefix:
RDEFINE SERVER BBG.SECPFX.MQW942 UACC(NONE)
PERMIT BBG.SECPFX.MQW942 CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for the authorized module BBGZSAFM:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSAFM CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for SAF credential services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for WLM services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.ZOSWLM UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSWLM CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for RRS transaction services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.TXRRS UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.TXRRS CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for dump services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSDUMP CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define server profiles for local adapter services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.WOLA UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSAFM.WOLA CLASS(SERVER) ACCESS(READ) ID(SYSPROG)

RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.LOCALCOM UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSAFM.LOCALCOM CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for product management services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSAFM.PRODMGR CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for asynchronous I/O services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.ZOSAIO UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSAIO CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for the authorized client module BBGZSCFM:
RDEFINE SERVER BBG.AUTHMOD.BBGZSCFM UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSCFM CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Define a server profile for the client optimized local adapter services:
RDEFINE SERVER BBG.AUTHMOD.BBGZSCFM.WOLA UACC(NONE) OWNER(SYSPROG)
PERMIT BBG.AUTHMOD.BBGZSCFM.WOLA CLASS(SERVER) ACCESS(READ) ID(SYSPROG)
  1. Refresh the SERVER class:
SETROPTS RACLIST(SERVER) REFRESH

VIII. Restart and validate MQ Web

  1. Restart the MQ Web Console started task from SDSF.

  2. Open the MQ Web Console in a browser and confirm that the login screen appears.

  3. Sign in using a permitted RACF user ID and password.

  4. Confirm that the user can access the MQ Console or REST API functions allowed by the assigned EJBROLE profiles.

Validation checklist

Before considering the lab complete, confirm the following:

  • zos_saf_registry.xml was copied into the mqweb server directory
  • server.xml includes zos_saf_registry.xml
  • zos_saf_registry.xml contains the correct profilePrefix and unauthenticatedUser
  • RACF APPL profiles were created and permitted correctly
  • RACF EJBROLE profiles were created and permitted correctly
  • MQANGEL is running
  • The MQWEBS started task environment includes the angel Java option
  • RACF SERVER profiles for angel access were defined and refreshed
  • The MQ Web Console starts successfully
  • A permitted RACF user can log in successfully

Troubleshooting

If the MQ Web Console does not work as expected, check the following:

  • The sample file was copied from the correct MQ version directory
  • server.xml includes zos_saf_registry.xml and not basic_registry.xml
  • mqwebuser.xml contains a valid httpsPort attribute and valid XML syntax
  • The profilePrefix in the XML matches the RACF profile names you created
  • The unauthenticatedUser exists and has the required APPL access
  • The MQ Web started task user has access to the required SERVER class profiles
  • MQANGEL is running
  • The Java option for the angel process is in the active STDENV section
  • The correct RACF classes were refreshed after updates
  • The MQ Web started task was restarted after configuration changes

Common symptoms and causes:

  • Login page does not appear: MQ Web did not start, XML is invalid, or HTTPS endpoint configuration is broken
  • Login page appears but authentication fails for all users: APPL profile, SAF registry, or profilePrefix configuration is wrong
  • Login works but authorization is wrong: EJBROLE definitions or PERMIT commands are incomplete
  • MQ Web fails after angel changes: MQANGEL is not running, SERVER profiles are missing, or the Liberty JVM option is not active
  • XML edit causes startup failure: the file was not edited in ASCII mode, or a syntax error was introduced

Cleanup or rollback

If you want to back out the change and return to the basic registry example:

  1. Edit server.xml and replace:
<include location="zos_saf_registry.xml"/>

with:

<include location="basic_registry.xml"/>

  1. Remove or ignore the SAF registry XML file if it is no longer needed.

  2. Back out the RACF definitions according to your site's standards if they were created only for this lab.

  3. Restart the MQ Web Console.

Appendix

More information about angel RACF profiles: IBM Documentation