+

Search Tips | Advanced Search

Configure a SAF registry for the IBM MQ Console and REST API

The System Authorization Facility (SAF) interface allows the mqweb server to call the external security manager for authentication and authorization checking. A user can then log in to the IBM MQ Console and REST API with a z/OS user ID and password.


Before starting

  • When you configure a SAF registry, we must assign users a role. Each role provides different levels of privilege to access the IBM MQ Console and REST API, and determines the security context that is used when an allowed operation is attempted. We need to understand these roles before you configure the registry. For more information about each of the roles, see Roles on the IBM MQ Console and REST API.
  • You need the WebSphere Liberty Angel process running to use the authorized interface to SAF. See Enable z/OS authorized services on Liberty for z/OS for more information.
  • To complete this task, we must have write access to the mqwebuser.xml file, and authority to define security manager profiles.


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.


Procedure

  1. Follow the steps in Enable z/OS authorized services on Liberty for z/OS to give your mqweb 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/V9R2M0/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. 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.
  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 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, we will need to choose a different name for each server; for example MQWEB920 and MQWEB915.
    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. We 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. Use the SETROPTS RACF command to refresh the in-storage RACLISTed APPL class profiles: 
    SETROPTS RACLIST(APPL) REFRESH
  11. 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)
  12. 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 11. For more information about the roles, see Roles on the IBM MQ Console and REST API. 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

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


What to do next

Choose how users authenticate:

    IBM MQ Console authentication options

    • Let users authenticate by using token authentication. In this case, a user enters a user ID and password at the IBM MQ Console log in screen. An LTPA token is generated that enables the user to remain logged in and authorized for a set amount of time. No further configuration is required to use this authentication option, but we can optionally configure the expiry interval for the LTPA token. For more information, see Configure the LTPA token expiry interval.
    • Let users authenticate by using client certificates. In this case, the user does not use a user ID or password to log in to the IBM MQ Console, but uses the client certificate instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console.

    REST API authentication options

    • Let users authenticate by using HTTP basic authentication. In this case, a user name and password is encoded, but not encrypted, and sent with each REST API request to authenticate and authorize the user for that request. In order for this authentication to be secure, we must use a secure connection. That is, we must use HTTPS. For more information, see Use HTTP basic authentication with the REST API.
    • Let users authenticate by using token authentication. In this case, a user provides a user ID and password to the REST API login resource with the HTTP POST method. An LTPA token is generated that enables the user to remain logged in and authorized for a set amount of time. For more information, see Use token-based authentication with the REST API. We can configure the expiry interval for the LTPA token. For more information, see Configure the LTPA token.
    • Let users authenticate by using client certificates. In this case, the user does not use a user ID or password to log in to the REST API, but uses the client certificate instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console.

Parent topic: Configure users and roles

Last updated: 2020-10-04