DEFINE AUTHINFO

Use the MQSC command DEFINE AUTHINFO to define 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 enable user ID and password checking.

Using MQSC commands

For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.

[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 commands on z/OS®.

Usage notes for DEFINE AUTHINFO
Parameter descriptions for DEFINE AUTHINFO
Syntax diagram for TYPE(CRLLDAP)
Syntax diagram for TYPE(OCSP)
Syntax diagram for TYPE(IDPWOS)
Syntax diagram for TYPE(IDPWLDAP)

Synonym: DEF AUTHINFO

Values shown above the main line in the railroad diagram are the defaults supplied with IBM® MQ, but your installation might have changed them. See Syntax diagrams.

Syntax diagram for TYPE(CRLLDAP)

DEFINE 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 TYPE(OCSP)

DEFINE 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 TYPE(IDPWOS)

DEFINE 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 UNIX.
⁴ Not valid on IBM MQ for z/OS.
⁵ Default for platforms other than z/OS.
⁶ Default for z/OS.

Syntax diagram for TYPE(IDPWLDAP)

DEFINE AUTHINFO

Notes:

¹ Not valid on IBM MQ for z/OS.

Usage notes for DEFINE AUTHINFO

[IBM i] On IBM i, authentication information objects of AUTHTYPE(CRLLDAP) and AUTHTYPE(OCSP) are only used for channels of type CLNTCONN through use of the AMQCLCHL.TAB. Certificates are defined by Digital Certificate Manager for each certificate authority, and are verified against the LDAP servers.

Attention: After running the DEFINE AUTHINFO command, you must restart the queue manager. If you do not restart the queue manager, the setmqaut command does not return the correct result.

Parameter descriptions for DEFINE 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 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.

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 UNIX and Linux®.

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

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

Attention: This option is not available on IBM MQ for z/OS

IDPWOS

Connection authentication user ID and password checking is done using the operating system.

OCSP

Certificate revocation checking is done using OCSP.

An authentication information object with AUTHTYPE(OCSP) does not apply for use on queue managers on the following platforms:

IBM i
z/OS

However, it can be specified on those platforms to be copied to the client channel definition table (CCDT) for client use.

This parameter is required.

You cannot define an authentication information object as LIKE one 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 (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 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

No user ID and password checks are made. If any user ID or password is supplied by a client application, the credentials are ignored.

OPTIONAL

Client applications are not required to provide a user ID and password.

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.

This option might be useful during migration, for example.

REQUIRED

All client applications must provide a user ID and password in the MQCSP structure. This user ID and password is 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.

REQDADM

All client applications using a privileged user ID must provide a user ID and password in the MQCSP structure. Any locally bound applications using a non-privileged user ID are not required to provide a user ID and password and are treated as with the OPTIONAL setting.

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.

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.

A privileged user is one that has full administrative authorities for IBM MQ. See Privileged users for more information.

[z/OS] (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.
If you select NONE and the client connection matches a CHLAUTH record with CHCKCLNT REQUIRED (or REQDADM on platforms other than z/OS), the connection fails. You receive the following message:
- AMQ9793 on Multiplatforms.
- CSQX793E on z/OS.
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.

[MQ Appliance] 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

No user ID and password checks are made. If any user ID or password is supplied by a locally bound application, the credentials are ignored.

OPTIONAL

Locally bound applications are not required to provide a user ID and password.

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.

This option might be useful during migration, for example.

REQUIRED

All locally bound applications must provide a user ID and password in the MQCSP structure. This 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.

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 a user ID and password in the MQCSP structure. Any locally bound applications using a non-privileged user ID are not required to provide a user ID and password and are treated as with the OPTIONAL setting.

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.

A privileged user is one that has full administrative authorities for IBM MQ. See Privileged users for more information.

[z/OS] (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 name )

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.

[z/OS] 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 depends on your platform:

On UNIX, Linux, and Windows, the maximum length is 264 characters.
On IBM i, the maximum length is 264 characters.
On z/OS, the maximum length is 48 characters.

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

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

[V9.1.0 Jul 2018] When AUTHORMD = SRCHGRPSN, the FINDGRP attribute is typically set to memberUid.

When the FINDGRP attribute is left blank:

If AUTHORMD = SEARCHGRP, the FINDGRP attribute defaults to memberOf.
If AUTHORMD = SEARCHUSR, the FINDGRP attribute defaults to member.
If 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.

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

[z/OS] 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.

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

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

The maximum size for the user name is as follows:

1024 characters on Multiplatforms
256 characters on z/OS

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

[UNIX, Linux, Windows, IBM i] On Multiplatforms, the maximum accepted line length is defined to be BUFSIZ, which can be found in stdio.h.

LIKE(authinfo-name)

The name of an authentication information object, with parameters that are used to model this definition.

On z/OS, the queue manager searches for an object with the name you specify and a disposition of QMGR or COPY. The disposition of the LIKE object is not copied to the object you are defining.

Note:

QSGDISP (GROUP) objects are not searched.
LIKE is ignored if QSGDISP(COPY) is specified. However, the group object defined is used as a LIKE object.

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	DEFINE
COPY	The object is defined on the page set of the queue manager that executes the command using the QSGDISP(GROUP) object of the same name as the LIKE object.
GROUP	The object definition resides in the shared repository. GROUP is allowed only if the queue manager is in a queue sharing group. If the definition is successful, the following command is generated and sent to all active queue managers in the queue sharing group to make or refresh local copies on page set zero: `DEFINE AUTHINFO(name) REPLACE QSGDISP(COPY)` The DEFINE for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE	Not permitted.
QMGR	The object is defined on the page set of the queue manager that executes the command.

REPLACE and NOREPLACE

Whether the existing definition (and on z/OS, with the same disposition) is to be replaced with this one. This parameter is optional. Any object with a different disposition is not changed.

REPLACE: The definition must replace any existing definition of the same name. If a definition does not exist, one is created.
NOREPLACE: The definition must not replace any existing definition of the same name.

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.

SHORTUSR(LDAP field 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.

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

USRFIELD( LDAP field name )

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 equals (=) 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.