Copy MQ AuthInfo object (CPYMQMAUTI)

    Where allowed to run
    All environments (*ALL)

    Threadsafe
    Yes

The Copy MQ AuthInfo object (CPYMQMAUTI) command creates an authentication information object of the same type and, for attributes not specified in the command, with the same attribute values as an existing object.


Parameters

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


From AuthInfo name (FROMAI)

The name of an existing authentication information object to provide values for the attributes not specified in this command.

The possible values are:

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


To AuthInfo name (TOAI)

The name of the new authentication information object to create.

If an authentication information object with this name already exists, REPLACE(*YES) must be specified.

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.

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


Replace (REPLACE)

Specifies whether the new authentication information object should replace an existing authentication information object with the same name.

The possible values are:

    *NO
    This definition does not replace any existing authentication information object with the same name. The command fails if the named authentication information object already exists.

    *YES
    Replace an existing authentication information object. A new object is created if the named authentication information object does not exist.


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


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.


Examples

None


Error messages

Unknown