Configuring 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 you begin

When you configure a SAF registry, you 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. You 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 Enabling z/OS authorized services on Liberty for z/OS for more information.
To complete this task, you must have write access to the mqwebuser.xml file, and authority to define security manager profiles.

Note:

From IBM MQ 9.1.0 Fix Pack 20, the sample configuration file zos_saf_registry.xml has been updated to remove a duplicate safAuthorization entry.

This update fixes an issue where an ICH408I error can occur when the MQ Console on z/OS is upgraded to a level that ships WebSphere Liberty Profile 22.0.0.12 or later: that is, from IBM MQ 9.1.0 Fix Pack 15. Having more than one safAuthorization statement is not supported and might cause an ICH408I error when users who are not in either MQWebAdmin or MQWebAdminRO roles, in the EBJROLE class, try to access a z/OS queue manager through the MQ Console.

The default for racRouteLog, which specifies the types of access attempts to log, is NONE. If you require an additional report or record for security auditing, see SAF Authorization (safAuthorization) 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.

Procedure

Follow the steps in Enabling 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/V9R1M0/web.

See Administering Liberty on z/OS for further information on stopping and starting the angel process.
Follow the steps in Liberty: Setting up the System Authorization Facility (SAF) unauthenticated user to create the unauthenticated user needed by Liberty.
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.
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.
Optional: If you previously changed any configuration settings in mqwebuser.xml, copy them into the sample file.
Delete the existing mqwebuser.xml file and rename the sample file to mqwebuser.xml.
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 MQWEB910 and MQWEB905.
2. Set unauthenticatedUser to the name of the unauthenticated user created in step 2.
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)
```
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)
```

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)

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. 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

You 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 you can optionally configure the expiry interval for the LTPA token. For more information, see Configuring 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 Using 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, you must use a secure connection. That is, you must use HTTPS. For more information, see Using 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 Using token-based authentication with the REST API. You can configure the expiry interval for the LTPA token. For more information, see Configuring 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 Using client certificate authentication with the REST API and IBM MQ Console.