Connection authentication: Configuration

On a queue manager object, the CONNAUTH attribute can be set to the name of an authentication information (AUTHINFO) object. The AUTHTYPE attribute of an AUTHINFO object specifies the type of the object. AUTHINFO objects that are used for connection authentication can be one of the following two types:

IDPWOS

The queue manager uses the local operating system to authenticate the user ID and password that is supplied by a connecting application.

From IBM® MQ 9.3.4, this type of AUTHINFO object also allows a queue manager that runs on AIX® or Linux® to validate authentication tokens. In addition to the AUTHINFO object that is used to configure connection authentication, the queue manager must be configured to accept authentication tokens with the AuthInfo stanza of the qm.ini file. For more information about configuring a queue manager to accept authentication tokens, see Configuring a queue manager to accept authentication tokens using a local keystore.

IDPWLDAP

The queue manager uses an LDAP server to authenticate the user ID and password that is supplied by a connecting application.

The following example MQSC commands turn on connection authentication with the following operations:

1. Define an AUTHINFO object named USE.PW.
2. Alter the queue manager CONNAUTH attribute to refer to this AUTHINFO object.
3. Issue the REFRESH SECURITY command to refresh the queue manager's connection authentication configuration. The REFRESH SECURITY command must be issued before the queue manager recognizes any changes to the connection authentication configuration.

DEFINE AUTHINFO(USE.PW) +
AUTHTYPE(IDPWOS) +
FAILDLAY(10) +
CHCKLOCL(OPTIONAL) +
CHCKCLNT(REQUIRED)

ALTER QMGR CONNAUTH(USE.PW)

REFRESH SECURITY TYPE(CONNAUTH)

CHCKLOCL accepts the values of NONE and OPTIONAL, and CHCKCLNT allows the value of NONE for the authentication requirements to be configured:

NONE

Authentication credentials that are supplied by applications are not checked.

OPTIONAL

Ensures that any credentials that are provided by an application are valid. However, it is not mandatory for applications to provide authentication credentials. This option might be useful during migration, for example.

If you:

• Provide the username and password, they are authenticated.
• Do not provide the username and password, connection is allowed.
• Provide the username, but not the password you receive an error.

Important: OPTIONAL is the minimum value that you can set if you also want to set a more restrictive option in channel authentication (CHLAUTH) rules.

If you select NONE and the client connection matches a CHLAUTH record with CHCKCLNT set to REQUIRED (or REQDADM on platforms other than z/OS®), the connection fails. You receive message AMQ9793 on Multiplatforms, and message CSQX793E on z/OS.

For more information about using channel authentication rules to set more restrictive CHCKCLNT options for some client connections, see Configuration granularity.

REQUIRED

Requires that all applications provide valid credentials. See also the following note.

REQDADM

Privileged users must supply valid credentials, but non-privileged users are treated as with the OPTIONAL setting. See also the following note. (This setting is not allowed on z/OS systems.)

You can set the overall CHCKCLNT value to OPTIONAL, for example, on the AUTHINFO object, and then upgrade it to be more stringent for certain channels by setting CHCKCLNT to REQUIRED or REQDADM on the CHLAUTH rule. By default, CHLAUTH rules are defined with CHCKCLNT(ASQMGR), so this granularity does not have to be used. For example, these MQSC commands define one CHLAUTH rule that overrides the AUTHINFO object's CHCKCLNT attribute, and one CHLAUTH rule that does not:

DEFINE AUTHINFO(USE.PW) AUTHTYPE(xxxxxx) +
CHCKCLNT(OPTIONAL)

SET CHLAUTH('*') TYPE(ADDRESSMAP) +
ADDRESS('*') USERSRC(CHANNEL) +
CHCKCLNT(REQUIRED)

SET CHLAUTH('*') TYPE(SSLPEERMAP) +
SSLPEER('CN=*') USERSRC(CHANNEL)

For more information about CHLAUTH rules, see Channel authentication records.

An error is recorded in the following situations:

• An application does not supply authentication credentials when they are required.
• An application supplies invalid authentication credentials. This situation is treated as an error even if the configuration states that it is optional for applications to supply credentials.

The error is recorded in several ways:

Application

An MQRC_NOT_AUTHORIZED (2035) reason code is returned to the application.

Administrator

An IBM MQ administrator sees the event reported in the error log. The error message shows that the connection is rejected because the credentials are invalid, rather than because, for example, the user does not have connection authority.

Monitoring tool

A monitoring tool can also be notified of the failure, if you turn on authority events, by an event message on the SYSTEM.ADMIN.QMGR.EVENT queue. To turn on authority events, issue the following MQSC command:

ALTER QMGR AUTHOREV(ENABLED)

This "Not Authorized" event is a Type 1 connect event, and provides the same fields as other Type 1 events, with an extra field, the MQCSP user ID that was provided. If the application supplied a password, it is not included in the event message. This means that there are two user IDs in the event message:

• The user ID that the application is running under.
• The user ID in the credentials that the application presented.

For more information about this event message, see Not Authorized (type 1).

You can configure the queue manager to adopt the credentials that are presented by the application as the context for the connection. Adopting the credentials means that the user ID supplied in the authentication credentials is used for authorization checks, shown on administrative displays, and appears in messages. The ADOPTCTX attribute on the AUTHINFO object controls whether credentials are adopted as the context for the application. For example, the following MQSC commands define an AUTHINFO object that is named USE.PWD that is used for connection authentication, and set the ADOPTCTX attribute to YES:

DEFINE AUTHINFO(USE.PWD) +
AUTHTYPE(xxxxxx) +
CHCKLOCL(OPTIONAL) +
CHCKCLNT(REQUIRED) +
ADOPTCTX(YES)

ALTER QMGR CONNAUTH(USE.PWD)

The following values can be specified for the ADOPTCTX attribute:

ADOPTCTX(YES)

The credentials that are supplied by the application are adopted as the application context for the duration of the connection. All authorization checks for an application are made with the user ID in the credentials that were authenticated.

Attention: When using ADOPTCTX(YES) and local operating system user IDs, you must ensure that the user ID being adopted meets the requirements for user IDs in IBM MQ. For more information, see User IDs.

ADOPTCTX(NO)

Credentials that are supplied by an application are used only for authentication at connection time. The user ID that the application is running under continues to be used for future authorization checks. You might find this option useful when migrating, or if you plan to use other mechanisms, such as channel authentication records, to assign the message channel agent user identifier (MCAUSER).