Configure System Authorization Facility interface

The System Authorization Facility (SAF) interface allows the mqweb server to call the external security manager for authentication and authorization checking.

Before you begin

Ensure that we have:

• A working IBM MQ Console and REST API as described in Get started
• The WebSphere Application Server Liberty Angel process running to use the authorized interface to SAF. See Enabling z/OS authorized services on Liberty for z/OS for more information.

About this task

The SAF interface allows the mqweb server to call the external security manager for authentication and authorization checking for both the IBM MQ Console and REST API.

Note that you need to be a privileged user to perform some of the steps in this task.

Procedure

1. Follow the steps in Enabling z/OS authorized services on Liberty for z/OS to give your mqweb Liberty server access to use z/OS® authorized services. Sample JCL for starting the angel process is in USS_ROOT/web/templates/zos/procs/bbgzangl.jcl, where USS_ROOT is the path in Unix System Services where IBM MQ for z/OS USS components are installed.

   In bbgzangl.jcl, change the SET ROOT statement to point to USS_ROOT/web, for example, /usr/lpp/mqm/V9R0M0/web.

   See Administer Liberty on z/OS for further information on stopping and starting the angel process.

2. Follow the steps in Liberty: Setting up the System Authorization Facility (SAF) unauthenticated user to create the unauthenticated user needed by Liberty.
3. Use the zos_saf_registry.xml file.

   

   From IBM MQ Version 9.0.5, copy the zos_saf_registry.xml file from the following path: PathPrefix /web/mq/samp/configuration where PathPrefix is the IBM MQ Unix System Services Components installation path.

   For IBM MQ Version 9.0.4 and earlier, use this file:

   <?xml version="1.0" encoding="UTF-8"?>
   <server>
       <!-- ****************************************************************** -->
       <!--                                                                    -->
       <!--  IBM MQ security configuration for MQ Console and REST API.        -->
       <!--                                                                    -->
       <!--  Name: zos_saf_registry.xml                                        -->
       <!--                                                                    -->
       <!--  Description: SAF based registry for z/OS                          -->
       <!--                                                                    -->
       <!-- ****************************************************************** -->
       <!-- <copyright                                                         -->
       <!--     notice='lm-source-program'                                     -->
       <!--     pids='5724-H72'                                                -->
       <!--     years='2017'                                                   -->
       <!--     crc='0' >                                                      -->
       <!--                                                                    -->
       <!--                                                                    -->
       <!--     5724-H72                                                       -->
       <!--                                                                    -->
       <!--     (C) Copyright IBM Corp. 2017, 2020. All Rights Reserved.       -->
       <!--                                                                    -->
       <!--     disclosure restricted by GSA ADP Schedule Contract with        -->
       <!--     IBM Corp.                                                      -->
       <!-- </copyright>                                                       -->
   
       <!--
       Role mappings are granted by giving users and groups READ access to the 
       following profiles in the EJBROLE class:
       
       1) MQWEB.com.ibm.mq.console.MQWebAdmin 
       
       MQWebAdmin role access for the MQ Console. All MQ commands issued by the
       MQ Console use the security context of the operating system user running
       the application server.
       
       2) MQWEB.com.ibm.mq.console.MQWebAdminRO
       
       MQWebAdminRO role access for the MQ Console. The security context of
       the operating system user running the application server is used for
       all read-only MQ commands, such as DISPLAY CHANNEL, QUEUE, etc,
       issued by the MQ Console.
            
       3) MQWEB.com.ibm.mq.console.MQWebUser
   
       MQWebUser role access for the MQ Console. All MQ commands issued by
       the MQ Console use the security context of the principal and so the
       user must be known to the queue manager and authorized to issue the
       command.
       
       4) MQWEB.com.ibm.mq.rest.MQWebAdmin
       
       MQWebAdmin role access for the MQ REST API. All MQ commands issued by the
       REST API use the security context of the operating system user running
       the application server.
       
       5) MQWEB.com.ibm.mq.rest.MQWebAdminRO
       
       MQWebAdminRO role access for the MQ REST API. The security context of
       the operating system user running the application server is used for
       all read-only MQ commands, such as DISPLAY CHANNEL, QUEUE, etc,
       issued by the REST API.
       
       6) MQWEB.com.ibm.mq.rest.MQWebUser
       
       MQWebUser role access for the MQ REST API. All MQ commands issued by
       the REST API use the security context of the principal and so the
       user must be known to the queue manager and authorized to issue the
       command.
    
       In addition the sample enables HTTP Basic Authentication.
       -->
       
       <!-- 
       Enable features 
       -->
       <featureManager>
           <feature>appSecurity-2.0</feature>
           <feature>zosSecurity-1.0</feature>
           <feature>basicAuthenticationMQ-1.0</feature>
       </featureManager>
   
       <!-- 
       The MQ Console 
       -->
       <enterpriseApplication id="com.ibm.mq.console" />
   
       <!-- 
       The MQ REST API 
       -->
       <enterpriseApplication id="com.ibm.mq.rest" />
   
       <!-- 
       Example SAF Registry 
       -->
       <safAuthorization racRouteLog="ASIS"/>
       <safRegistry id="saf" />
       <safAuthorization id="saf" />
       <safCredentials unauthenticatedUser="WSGUEST" profilePrefix="MQWEB" />    
       
       <!-- 
       Enable HTTP by uncommenting the line below. 
       -->
       <!--
       <variable name="httpPort" value="9080"/>
       -->
       
       <!-- 
       By default the server listens for HTTP/HTTPS requests on localhost only. To 
       listen on all available network interfaces uncomment the line below. To listen
       on a specific IP address or hostname replace the * with an appropriate value.
       -->
       <!--
       <variable name="httpHost" value="*"/>
       -->
               
       <!--       
       Default MQ SSL configuration allows TLS v1.2 ONLY, refer to the 
       IBM Knowledge Center section on "IBM MQ Console and REST API security" 
       for details of how to configure security.
       -->             
       <sslDefault sslRef="mqDefaultSSLConfig"/>
                       
       <!-- 
       Enable client certificate authentication by uncommenting the
       block below and creating a trust.jks store. Basic registry
       maps the common name (CN=) issued by a trusted CA to
       users names in the registry. For example a certificate with 
       a distinguished name of 'CN=mqadmin,O=IBM,C=GB' will be granted 
       a MQWebAdmin role under the 'mqadmin' user.
              
       The default, auto-generated certificate held in key.jks is
       intended for developer convenience only, it is not intended for
       production use.
   
       Passwords for both defaultKeyStore and defaultTrustStore should
       be changed and encoded using the securityUtility tool, refer
       to the following IBM Developer article for further information;
   
       https://developer.ibm.com/wasdev/docs/configuring-ssl-liberty/
       -->
       <!--
       <keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="password"/>
       <keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="password"/>
       <ssl id="thisSSLConfig" clientAuthenticationSupported="true" keyStoreRef="defaultKeyStore"
            trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2" serverKeyAlias="default"/>
       <sslDefault sslRef="thisSSLConfig"/>    
       -->    
       
       <!--
       Uncomment the following two variables, and adjust them, to change 
       the default CORS settings.
       -->
       <!--
       <variable name="mqRestCorsAllowedOrigins" value="https://localhost:9883"/>
       <variable name="mqRestCorsMaxAgeInSeconds" value="120"/>
       -->    
   </server>

4. Place the sample file in the WLP_user_directory/servers/mqweb directory, where WLP_user_directory is the directory that was specified when the crtmqweb.sh script ran to create the mqweb server definition.
5. Optional: If you previously changed any configuration settings in mqwebuser.xml, copy them into the sample file.
6. Delete the existing mqwebuser.xml file and rename the sample file to mqwebuser.xml.
7. Customize the safCredentials element in mqwebuser.xml.
   1. Set profilePrefix to a name that is unique to your Liberty server. If you have more than one mqweb server running on a single system, you will need to choose a different name for each server; for example MQWEB903 and MQWEB904.
   2. Set unauthenticatedUser to the name of the unauthenticated user created in step 2.
8. Define the mqweb server APPLID to RACF. The APPLID resource name is the value you specified in the profilePrefix attribute in step 7. The following example defines the mqweb server APPLID in RACF:

   RDEFINE APPL profilePrefix UACC(NONE)

9. Grant all users, or groups, to be authenticated to the MQ Console or REST API READ access to the mqweb server APPLID in the APPL class. You must also do this for the unauthenticated user defined in step 2. The following example grants a user READ access to the mqweb server APPLID in RACF:

   PERMIT profilePrefix CLASS(APPL) ACCESS(READ) ID(userID)

10. Define the profiles in the EJBROLE class needed to give users access to roles in the MQ Console and REST API. The following example defines the profiles in RACF, where profilePrefix is the value specified for the profilePrefix attribute in step 7.

    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebAdmin UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebAdminRO UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebUser UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebAdmin UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebAdminRO UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebUser UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MFTWebAdmin UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MFTWebAdminRO UACC(NONE)
    

    For IBM MQ Version 9.0.4 and earlier:

    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebAdmin UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebAdminRO UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.console.MQWebUser UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebAdmin UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebAdminRO UACC(NONE)
    RDEFINE EJBROLE profilePrefix.com.ibm.mq.rest.MQWebUser UACC(NONE)
    

11. Grant users access to roles in the MQ Console and REST API. To do this, give users or groups READ access to one or more of the profiles in the EBJROLE class created in step 10. The following example gives a user access to the MQWebAdmin role for the REST API in RACF, where profilePrefix is the value specified for the profilePrefix attribute in step 7.

    PERMIT profilePrefix.com.ibm.mq.rest.MQWebAdmin CLASS(EJBROLE) ACCESS(READ) ID(userID)

Results

You have set up SAF authentication for the IBM MQ Console and REST API.