CHGMQMAUTI (Change MQ AuthInfo object)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes

The Change MQ AuthInfo object (CHGMQMAUTI) command changes the specified attributes of an existing MQ authentication information object.

Parameters

Table 1. Command parameters
Keyword	Description	Choices	Notes
AINAME	AuthInfo name	Character value	Required, Key, Positional 1
MQMNAME	Message Queue Manager name	`Character value`, *DFT	Optional, Key, Positional 2
AUTHTYPE	AuthInfo type	CRLLDAP, OCSP, IDPWOS, IDPWLDAP	Optional, Positional 3
CONNAME	Connection name	`Character value`, *SAME	Optional, Positional 4
TEXT	Text 'description'	`Character value`, SAME, NONE	Optional, Positional 5
USERNAME	User name	`Character value`, SAME, NONE	Optional, Positional 6
PASSWORD	User password	`Character value`, SAME, NONE	Optional, Positional 7
OCSPURL	OCSP Responder URL	`Character value`, *SAME	Optional, Positional 8
CHCKCLNT	Authentication checks required	ASQMGR, REQUIRED, *REQADM	Optional, Positional 9
CHCKLOCL	Authentication checks required	NONE, OPTIONAL, REQUIRED, REQADM	Optional, Positional 10
FAILDELAY	Failure delay	`Integer value`	Optional, Positional 11
BASEDNU	Base user DN	`Character value`, *SAME	Optional, Positional 12
ADOPTCTX	Context adoption	`Integer value`	Optional, Positional 13
CLASSUSER	LDAP object class	`Character value`, *SAME	Optional, Positional 14
USERFIELD	LDAP user record	`Character value`, *SAME	Optional, Positional 15
SHORTUSER	User record	`Character value`, *SAME	Optional, Positional 16
SECCOMM	LDAP communications	`Character value`, *SAME	Optional, Positional 17
AUTHORMD	Authorization method	`Character value`, OS, SEARCHGRP, SEARCHUSR, SRCHGRPSN	Optional, Positional 18
BASEDNG	Base DN for groups	`Character value`, *SAME	Optional, Positional 19
CLASSGRP	Object class for group	`Character value`, *SAME	Optional, Positional 20
FINDGRP	Attribute to find group membership	`Character value`, *SAME	Optional, Positional 21
GRPFIELD	Simple name for group	`Character value`, *SAME	Optional, Positional 22
NESTGRP	Group nesting	NO YES	Optional, Positional 23
AUTHENMD	Authentication method	*OS Cannot be changed	Optional, Positional 24

AuthInfo name (AINAME)

The name of the authentication information object to change.

The possible values are:

authentication-information-name: Specify the name of the authentication information object. The maximum string length is 48 characters.

Message Queue Manager name (MQMNAME)

The name of the queue manager.

The possible values are:

*DFT: Use the default queue manager.
queue-manager-name: The name of an existing message queue manager. The maximum string length is 48 characters.

Adopt context (ADOPTCTX)

Whether to use the presented credentials as the context for this application. This means that they are used for authorization checks, shown on administrative displays, and appear in messages.

YES: The user ID presented in the MQCSP structure, which has been successfully validated by password, is adopted as the context to use for this application. Therefore, this user ID will be the credentials checked for authorization to use IBM® MQ resources.
If the user ID presented is an LDAP user ID, and authorization checks are done using operating system user IDs, the SHORTUSR associated with the user entry in LDAP will be adopted as the credentials for authorization checks to be done against.
NO: Authentication will be performed on the user ID and password presented in the MQCSP structure, but then the credentials will not be adopted for further use. Authorization will be performed using the user ID the application is running under.

This attribute is only valid for an AUTHTYPE of *IDPWOS and *IDPWLDAP.

Authentication method (AUTHENMD)

The authentication method used for this application.

*OS

Use operating system groups to determine permissions associated with a user.

You can use only *OS to set the authentication method.

This attribute is valid only for an AUTHTYPE of *IDPWOS.

Authorization method (AUTHORMD)

The authorization method used for this application.

*OS: Use operating system groups to determine permissions associated with a user.
This is how IBM MQ has previously worked, and is the default value.
*SEARCHGRP: A group entry in the LDAP repository contains an attribute listing the Distinguished Name of all the users belonging to that group. Membership is indicated by the attribute defined in FINDGRP. This value is typically member or uniqueMember.
*SEARCHUSR: A user entry in the LDAP repository contains an attribute listing the Distinguished Name of all the groups to which the specified user belongs. The attribute to query is defined by the FINDGRP value, typically memberOf.
*SRCHGRPSN: A group entry in the LDAP repository contains an attribute listing the short user name of all the users belonging to that group. The attribute in the user record that contains the short user name is specified by SHORTUSR.
Membership is indicated by the attribute defined in FINDGRP. This value is typically memberUid.
Note: This authorization method should only be used if all user short names are distinct.

Many LDAP servers use an attribute of the group object to determine group membership and you should, therefore, set this value to SEARCHGRP.

Microsoft Active Directory typically stores group memberships as a user attribute. The IBM Tivoli Directory Server supports both methods.

In general, retrieving memberships through a user attribute will be faster than searching for groups that list the user as a member.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

AuthInfo type (AUTHTYPE)

The type of the authentication information object. There is no default value

The possible values are:

*CRLLDAP: The type of the authentication information object is CRLLDAP.
*OCSP: The type of the authentication information objects is OCSPURL.
*IDPWOS: Connection authentication user ID and password checking is done using the operating system.
*IDPWLDAP: Connection authentication user ID and password checking is done using an LDAP server.

Base DN for groups (BASEDNG)

In order to be able to find group names, this parameter must be set with the base DN to search for groups in the LDAP server.

This attribute is valid only for AUTHTYPE of *IDPWLDAP.

Base user DN (BASEDNU)

In order to be able to find the short user name attribute (see SHORTUSR ) this parameter must be set with the base DN to search for users within the LDAP server. This attribute is valid only for AUTHTYPE of *IDPWLDAP.

Check client (CHCKCLNT)

Whether connection authentication checks are required by all locally bound connections, or only checked when a user ID and password are provided in the MQCSP structure.

These attributes are valid only for an AUTHTYPE of *IDPWOS or *IDPWLDAP. The possible values are:

*ASQMGR: In order for the connection to be allowed in, it must meet the connection authentication requirements defined on the queue manager. If the CONNAUTH field provides an authentication information object, and the value of CHCKCLNT is *REQUIRED, the connection will not be successful unless a valid user ID and password are supplied. If the CONNAUTH field does not provide an authentication information object, or the value of CHCKCLNT is not *REQUIRED, then the user ID and password are not required.
*REQUIRED: Requires that all applications provide a valid user ID and password.
*REQDADM: Privileged users must supply a valid user ID and password, but non-privileged users are treated as with the *OPTIONAL setting.

Check local (CHCKLOCL)

Whether connection authentication checks are required by all locally bound connections, or only checked when a user ID and password are provided in the MQCSP structure.

These attributes are valid only for an AUTHTYPE of *IDPWOS or *IDPWLDAP. The possible values are:

*NONE: Switches off checking.
*OPTIONAL: Ensures that if a user ID and password are provided by an application, they are a valid pair, but that it is not mandatory to provide them. This option might be useful during migration, for example.
*REQUIRED: Requires that all applications provide a valid user ID and password.
*REQDADM: Privileged users must supply a valid user ID and password, but non-privileged users are treated as with the *OPTIONAL setting.

Class group (CLASSGRP)

The LDAP object class used for group records in the LDAP repository.

If the value is blank, groupOfNames is used.

Other commonly used values include groupOfUniqueNames or group.

This attribute is valid only for AUTHTYPE of *IDPWLDAP.

Class user (CLASSUSR)

The LDAP object class used for user records in the LDAP repository.

If blank, the value defaults to inetOrgPerson, which is generally the value needed.

For Microsoft Active Directory, the value you require required is often user.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

Connection name (CONNAME)

The DNS name or IP address of the host on which the LDAP server is running, together with an optional port number. The default port number is 389. No default is provided for the DNS name or IP address.

This field is only valid for *CRLLDAP or *IDPWLDAP authentication information objects, when it is required.

When used with IDPWLDAP authentication information objects, this can be a comma separated list of connection names.

The possible values are:

*SAME: The connection name remains unchanged from the original authentication information object.
connection-name: Specify the fully qualified DNS name or IP address of the host together with an optional port number. The maximum string length is 264 characters.

Failure delay (FAILDELAY)

When a user ID and password are provided for connection authentication, and the authentication fails due to the user ID or password being incorrect, this is the delay, in seconds, before the failure is returned to the application.

This can aid in avoiding busy loops from an application that simply retries, continuously, after receiving a failure.

The value must be in the range 0 - 60 seconds. The default value is 1.

This attribute is only valid for AUTHTYPE of *IDPWOS and *IDPWLDAP.

Group membership attribute (FINDGRP)

Name of the attribute used within an LDAP entry to determine group membership.

When AUTHORMD = *SEARCHGRP, this attribute is typically set to member or uniqueMember.

When AUTHORMD = *SEARCHUSR, this attribute is typically set to memberOf.

When AUTHORMD = *SRCHGRPSN, this attribute is typically set to memberUid.

When left blank, if:

AUTHORMD = *SEARCHGRP, this attribute defaults to memberOf
AUTHORMD = *SEARCHUSR, this attribute defaults to member
AUTHORMD = *SRCHGRPSN, this attribute defaults to memberUid

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

Simple name for group (GRPFIELD)

If the value is blank, commands like setmqaut must use a qualified name for the group. The value can either be a full DN, or a single attribute.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

Group nesting (NESTGRP)

The possible values are:

*NO: Only the initially discovered groups are considered for authorization.
*YES: The group list is searched recursively to enumerate all the groups to which a user belongs.

The group's Distinguished Name is used when searching the group list recursively, regardless of the authorization method selected in AUTHORMD.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

OCSP Responder URL (OCSPURL)

The URL of the OCSP Responder used to check for certificate revocation. This must be an HTTP URL containing the host name and port number of the OCSP Responder. If the OCSP Responder is using port 80, which is the default for HTTP, then the port number may be omitted.

This field is only valid for OCSP authentication information objects.

The possible values are:

*SAME: The OCSP Responder URL is unchanged.
OCSP-Responder-URL: The OCSP Reponder URL. The maximum string length is 256 characters.

Secure comms (SECCOMM)

Whether connectivity to the LDAP server should be done securely using TLS

YES

Connectivity to the LDAP server is made securely using TLS.

The certificate used is the default certificate for the queue manager, named in CERTLABL on the queue manager object, or if that is blank, the one described in Digital certificate labels, understanding the requirements.

The certificate is located in the key repository specified in SSLKEYR on the queue manager object. A cipherspec will be negotiated that is supported by both IBM MQ and the LDAP server.

If the queue manager is configured to use SSLFIPS(YES) or SUITEB cipher specs, then this is taken account of in the connection to the LDAP server as well.

ANON

Connectivity to the LDAP server is made securely using TLS just as for SECCOMM(YES) with one difference.

No certificate is sent to the LDAP server; the connection will be made anonymously. To use this setting, ensure that the key repository specified in SSLKEYR, on the queue manager object, does not contain a certificate marked as the default.

NO

Connectivity to the LDAP server does not use TLS.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP

Short user (SHORTUSR)

A field in the user record to be used as a short user name in IBM MQ.

This field must contain values of 12 characters or less. This short user name is used for the following purposes:

If LDAP authentication is enabled, but LDAP authorization is not enabled, this is used as an operating system user ID for authorization checks. In this case, the attribute must represent an operating system user ID.
If LDAP authentication and authorization are both enabled, this is used as the user ID carried with the message in order for the LDAP user name to be rediscovered when the user ID inside the message needs to be used.
For example, on another queue manager, or when writing report messages. In this case, the attribute does not need to represent an operating system user ID, but must be a unique string. An employee serial number is an example of a good attribute for this purpose.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP and is mandatory.

Text 'description' (TEXT)

A short text description of the authentication information object.

Note: The field length is 64 bytes and the maximum number of characters is reduced if the system is using a double-byte character set (DBCS).

The possible values are:

*SAME: The text string is unchanged.
*NONE: The text is set to a blank string.
description: The string length can be up to 64 characters enclosed in apostrophes.

User name (USERNAME)

The distinguished name of the user that is binding to the directory. The default user name is blank.

This field is only valid for *CRLLDAP or *IDPWLDAP authentication information objects.

The possible values are:

*SAME: The user name is unchanged.
*NONE: The user name is blank.
LDAP-user-name: Specify the distinguished name of the LDAP user. The maximum string length is 1024 characters.

User field (USRFIELD)

If the user ID provided by an application for authentication does not contain a qualifier for the field in the LDAP user record, that is, it does not contain an ' = ' sign, this attribute identifies the field in the LDAP user record that is used to interpret the provided user ID.

This field can be blank. If this is the case, any unqualified user IDs use the SHORTUSR parameter to interpret the provided user ID.

The contents of this field will be concatenated with an ' = ' sign, together with the value provided by the application, to form the full user ID to be located in an LDAP user record. For example, the application provides a user of fred and this field has the value cn, then the LDAP repository will be searched for cn=fred.

This attribute is valid only for an AUTHTYPE of *IDPWLDAP.

User password (PASSWORD)

The password for the LDAP user.

This field is only valid for *CRLLDAP or *IDPWLDAP authentication information objects.

The possible values are:

*SAME: The password is unchanged.
*NONE: The password is blank.
LDAP-password: The LDAP user password. The maximum string length is 32 characters.