ALTER AUTHINFO (alter authentication information object)

Use the MQSC command ALTER AUTHINFO to alter an authentication information object. These objects contain the definitions required to perform certificate revocation checking using OCSP or Certificate Revocation Lists (CRLs) on LDAP servers, and the definitions required to check authentication credentials provided by applications.

Using MQSC commands

For information on how you use MQSC commands, see Administering IBM® MQ using MQSC commands.

Parameters not specified in the ALTER AUTHINFO command result in the existing values for those parameters being left unchanged.

[z/OS] You can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which you can issue MQSC and PCF commands on IBM MQ for z/OS®.

There are separate syntax diagrams for each AUTHTYPE parameter option:

Syntax diagram for TYPE(CRLLDAP)
Syntax diagram for TYPE(OCSP)
Syntax diagram for TYPE(IDPWOS)
Syntax diagram for TYPE(IDPWLDAP)
Parameter descriptions for ALTER AUTHINFO

Syntax diagram for AUTHTYPE(CRLLDAP)

Synonym: ALT AUTHINFO

ALTER AUTHINFO

Notes:

¹ Valid only when the queue manager is a member of a queue sharing group. You can use queue sharing groups only on IBM MQ for z/OS.
² Valid only on z/OS.

Syntax diagram for AUTHTYPE(OCSP)

Synonym: ALT AUTHINFO

ALTER AUTHINFO

Notes:

¹ Valid only when the queue manager is a member of a queue sharing group. You can use queue sharing groups only on IBM MQ for z/OS.
² Valid only on z/OS.

Syntax diagram for AUTHTYPE(IDPWOS)

Synonym: ALT AUTHINFO

ALTER AUTHINFO

Notes:

¹ Valid only when the queue manager is a member of a queue sharing group. You can use queue sharing groups only on IBM MQ for z/OS.
² Valid only on z/OS.
³ Not valid on z/OS and PAM value can be set only on AIX® and Linux®.
⁴ Not valid on z/OS.

Syntax diagram for AUTHTYPE(IDPWLDAP)

Synonym: ALT AUTHINFO

ALTER AUTHINFO

Notes:

¹ Not valid on z/OS.

Parameter descriptions for ALTER AUTHINFO

name

Name of the authentication information object. This parameter is required.

The name must not be the same as any other authentication information object name currently defined on this queue manager (unless REPLACE or ALTER is specified). See Rules for naming IBM MQ objects.

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 in the authentication credentials presented in the MQCSP structure, which have been successfully validated, is adopted as the context to use for this application. Therefore, this user ID has the credentials checked for authorization to use IBM MQ resources.; If the application presents a user ID and password, the user ID in the MQCSP structure is adopted if the password is successfully validated.; If the application presents an authentication token, and the token is successfully validated, the user ID in the token user claim is adopted as the context for the application. The name of the token user claim is specified by the UserClaim attribute in the AuthToken stanza of the qm.ini file. For more information about the UserClaim attribute, see UserClaim.; 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.; ADOPTCTX(YES) has an effect only if CHCKCLNT or CHCKLOCL is set to a value that causes the credentials to be validated.
NO: Authentication is performed on the credentials presented in the MQCSP structure, but then the credentials are not adopted for further use. Authorization is performed using the user ID that the application is running under.

The ADOPTCTX attribute is only valid for an AUTHTYPE of IDPWOS and IDPWLDAP.

AUTHENMD

Authentication method. Whether to use the operating system or Pluggable Authentication Method (PAM) to authenticate user passwords.

OS: Use the traditional UNIX password verification method.
PAM: Use the PAM to authenticate the user password.; You can set the PAM value only on AIX and Linux.

Changes to this attribute are effective only after you run the REFRESH SECURITY TYPE(CONNAUTH) command.

The AUTHENMD attribute is valid only for an AUTHTYPE of IDPWOS.

AUTHORMD

Authorization method.

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.

AUTHTYPE

The type of authentication information.

CRLLDAP: Certificate Revocation List checking is done using LDAP servers.
IDPWLDAP: Connection authentication user ID and password checking is done using an LDAP server.
IDPWOS: Connection authentication user ID and password checking is done using the operating system.; Authentication tokens supplied by IBM MQ MQI clients are validated if the queue manager is configured to accept authentication tokens using the AuthToken stanza of the qm.ini file. For more information about the AuthToken stanza, see AuthToken stanza of the qm.ini file.
OCSP: Certificate revocation checking is done using OCSP.; An authentication information object with AUTHTYPE(OCSP) does not apply for use on IBM i or z/OS queue managers. However, it can be specified on those platforms to be copied to the client channel definition table (CCDT) for client use.

The AUTHTYPE parameter is required.

You cannot define an authentication information object as LIKE another authentication object with a different AUTHTYPE. You cannot alter the AUTHTYPE of an authentication information object after you have created it.

BASEDNG

Base DN for groups.

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.

BASEDNU(base DN)

In order to be able to find the short user name attribute, SHORTUSR, this parameter must be set with the base DN to search for users within the LDAP server.

The BASEDNU attribute is valid only for an AUTHTYPE of IDPWLDAP.

CHCKCLNT

This attribute determines the authentication requirements for client applications, and is valid only for an AUTHTYPE of IDPWOS or IDPWLDAP. The possible values are:

NONE: Authentication credentials supplied by client applications are not checked. If a user ID and password, or an authentication token, is supplied by a client application, the credentials are ignored. ADOPTCTX will have no effect and any user IDs contained within the MQCSP will not be used for authorization checks later.
OPTIONAL: Client applications are not required to provide authentication credentials.; Any applications that do provide a user ID and password in the MQCSP structure have them authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection is only allowed to continue if the user ID and password are valid.; If an application provides an authentication token, and the queue manager is configured to accept authentication tokens, the token is validated. The connection is only allowed to continue if the token is issued by a trusted issuer.; This option might be useful during migration, for example.
REQUIRED: All client applications must provide authentication credentials in the MQCSP structure.; If an application provides a user ID and password, these credentials are authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection is only allowed to continue if the user ID and password are valid.; If an application provides an authentication token, and the queue manager is configured to accept authentication tokens, the token is validated. The connection is only allowed to continue if the token is issued by a trusted issuer.; If an application does not provide any authentication credentials, the connection is rejected.
REQDADM: All client applications using a privileged user ID must provide authentication credentials in the MQCSP structure. Any client applications using a non-privileged user ID are not required to provide authentication credentials and are treated as with the OPTIONAL setting.; A privileged user is one that has full administrative authorities for IBM MQ. See Privileged users for more information.; Any provided user ID and password are authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection is only allowed to continue if the user ID and password are valid.; If an application provides an authentication token, and the queue manager is configured to accept authentication tokens, the token is validated. The connection is only allowed to continue if the token is issued by a trusted issuer.; Note: The REQDADM value for the CHCKCLNT attribute is irrelevant if the authentication type is LDAP. This is because there is no concept of privileged user ID when using LDAP user accounts. LDAP user accounts and groups must be assigned permission explicitly.; This setting is not allowed on z/OS systems.

Important:

This attribute can be overridden by the CHCKCLNT attribute of the CHLAUTH rule that matches the client connection. The CONNAUTH AUTHINFO CHCKCLNT attribute on the queue manager therefore determines the default client checking behavior for client connections that do not match a CHLAUTH rule, or where the CHLAUTH rule matched has CHCKCLNT ASQMGR.
On Multiplatforms, if you select NONE and the client connection matches a CHLAUTH record with CHCKCLNT REQDADM, the connection fails. You receive message AMQ9793.
On z/OS, if you select NONE and the client connection matches a CHLAUTH record with CHCKCLNT REQUIRED, the connection fails. You receive message CSQX793E.
This parameter is valid only with TYPE(USERMAP), TYPE(ADDRESSMAP) and TYPE (SSLPEERMAP), and only when USERSRC is not set to NOACCESS.
This parameter applies only to inbound connections that are server-connection channels.

CHCKLOCL

This attribute determines the authentication requirements for locally bound applications, and is valid only for an AUTHTYPE of IDPWOS or IDPWLDAP.

For information about use of this attribute on IBM MQ Appliance, see Control commands on the IBM MQ Appliance in the IBM MQ Appliance documentation.

The possible values are:

NONE: Authentication credentials supplied by client applications are not checked. If a user ID and password is supplied by a locally bound application, the credentials are ignored.
OPTIONAL: Locally bound applications are not required to provide authentication credentials.; Any applications that do provide a user ID and password in the MQCSP structure have them authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection is only allowed to continue if the user ID and password are valid.; Authentication tokens cannot be supplied by locally bound applications.; This option might be useful during migration, for example.
REQUIRED: All locally bound applications must provide authentication credentials in the MQCSP structure.; If an application provides a user ID and password, these credentials are authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection will only be allowed to continue if the user ID and password are valid.; Authentication tokens cannot be supplied by locally bound applications.; If an application does not provide any authentication credentials, the connection is rejected.; If your user ID has UPDATE access to the BATCH profile in the MQCONN class, you can treat CHCKLOCL(REQUIRED) as if it is CHCKLOCL(OPTIONAL). That is, you do not have to supply a password, but if you do, the password must be the correct one.; See Using CHCKLOCL on locally bound applications.
REQDADM: All locally bound applications using a privileged user ID must provide authentication credentials in the MQCSP structure. Any locally bound applications using a non-privileged user ID are not required to provide authentication credentials and are treated as with the OPTIONAL setting.; A privileged user is one that has full administrative authorities for IBM MQ. See Privileged users for more information.; Any provided user ID and password will be authenticated by the queue manager against the password store indicated by the AUTHTYPE. The connection will only be allowed to continue if the user ID and password are valid.; Authentication tokens cannot be supplied by locally bound applications.; (This setting is not allowed on z/OS systems.)

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.

CLASSUSR(LDAP class user)

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 is often user.

This attribute is valid only for an AUTHTYPE of IDPWLDAP.

CMDSCOPE

This parameter applies to z/OS only and specifies how the command runs when the queue manager is a member of a queue sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.

' ': The command runs on the queue manager on which it was entered.
qmgr-name: The command runs on the queue manager you specify, providing the queue manager is active within the queue sharing group.
You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.
*: The command runs on the local queue manager and is also passed to every active queue manager in the queue sharing group. The effect of * is the same as entering the command on every queue manager in the queue sharing group.

CONNAME(connection name)

The host name, IPv4 dotted decimal address, or IPv6 hexadecimal notation of the host on which the LDAP server is running, with an optional port number.

If you specify the connection name as an IPv6 address, only systems with an IPv6 stack are able to resolve this address. If the AUTHINFO object is part of the CRL namelist of the queue manager, ensure that any clients using the client channel table generated by the queue manager can resolve the connection name.

On z/OS, if a CONNAME is to resolve to an IPv6 network address, a level of z/OS that supports IPv6 for connection to an LDAP server is required.

The syntax for CONNAME is the same as for channels. For example,

conname('hostname (nnn)')

where nnn is the port number.

The maximum length for the field is:

264 characters on Multiplatforms.
48 characters on z/OS.

This attribute is valid only for an AUTHTYPE of CRLLDAP and IDPWLDAP, when the attribute is mandatory.

When used with an AUTHTYPE of IDPWLDAP, this can be a comma separated list of connection names.

DESCR(string)

Plain-text comment. It provides descriptive information about the authentication information object when an operator issues the DISPLAY AUTHINFO command (see DISPLAY AUTHINFO (display authentication information) ).

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

FAILDLAY(delay time)

When authentication credentials are provided for connection authentication, and the authentication fails due to the credentials 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.

The FAILDLAY attribute is valid only for an AUTHTYPE of IDPWOS and IDPWLDAP.

FINDGRP

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

When AUTHORMD = SEARCHGRP, the FINDGRP attribute is typically set to member or uniqueMember.

When AUTHORMD = SEARCHUSR, the FINDGRP attribute is typically set to memberOf.

When AUTHORMD = SRCHGRPSN, the FINDGRP attribute is typically set to memberUid.

When left blank, if:

AUTHORMD = SEARCHGRP, the FINDGRP attribute defaults to memberOf
AUTHORMD = SEARCHUSR, the FINDGRP attribute defaults to member
AUTHORMD = SRCHGRPSN, the FINDGRP attribute defaults to memberUid

GRPFIELD

LDAP attribute that represents a simple name for the group.

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.

LDAPPWD(LDAP password)

The password associated with the Distinguished Name of the user who is accessing the LDAP server. Its maximum size is 32 characters.

On z/OS, the LDAPPWD used for accessing the LDAP server might not be the one defined in the AUTHINFO object. If more than one AUTHINFO object is placed in the namelist referred to by the QMGR parameter SSLCRLNL, the LDAPPWD in the first AUTHINFO object is used for accessing all LDAP Servers.

The GRPFIELD attribute is valid only for an AUTHTYPE of CRLLDAP and IDPWLDAP.

LDAPUSER(LDAP user)

The Distinguished Name of the user who is accessing the LDAP server. (See the SSLPEER parameter for more information about distinguished names.)

The maximum size for the user name is:

1024 characters on Multiplatforms.
256 characters on z/OS.

On z/OS, the LDAPUSER used for accessing the LDAP server might not be the one defined in the AUTHINFO object. If more than one AUTHINFO object is placed in the namelist referred to by the QMGR parameter SSLCRLNL, the LDAPUSER in the first AUTHINFO object is used for accessing all LDAP Servers.

If more than one OCSP type AUTHINFO objects is referenced in the NAMELIST, only the first entry is used.

On Multiplatforms, the maximum accepted line length is defined to be BUFSIZ, which can be found in stdio.h.

The LDAPUSER attribute is valid only for an AUTHTYPE of CRLLDAP and IDPWLDAP.

NESTGRP

Group nesting.

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.

OCSPURL(Responder URL)

The URL of the OCSP responder used to check for certificate revocation. This value 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 can be omitted. HTTP URLs are defined in RFC 1738.

This field is case sensitive. It must start with the string http:// in lowercase. The rest of the URL might be case sensitive, depending on the OCSP server implementation. To preserve case, use single quotation marks to specify the OCSPURL parameter value, for example:

OCSPURL ('http://ocsp.example.ibm.com')

This parameter is applicable only for AUTHTYPE(OCSP), when it is mandatory.

QSGDISP

This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

Table 1. Behavior for each of the QSGDISP values
QSGDISP	ALTER
COPY	The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP	The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue sharing group to attempt to refresh local copies on page set zero: `DEFINE AUTHINFO(name) REPLACE QSGDISP(COPY)` The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE	The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR	The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.

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.

The SECCOMM attribute is valid only for an AUTHTYPE of IDPWLDAP.

SHORTUSR(user name)

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.

The SHORTUSR attribute is valid only for an AUTHTYPE of IDPWLDAP and is mandatory.

USRFIELD(user field)

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

The USRFIELD attribute is valid only for an AUTHTYPE of IDPWLDAP.