Change, Copy, and Create Authentication Information Object

The Change authentication information command changes attributes of an existing authentication information object. The Create and Copy authentication information commands create new authentication information objects - the Copy command uses attribute values of an existing object.

The Change authentication information (MQCMD_CHANGE_AUTH_INFO) command changes the specified attributes in an authentication information object. For any optional parameters that are omitted, the value does not change.

The Copy authentication information (MQCMD_COPY_AUTH_INFO) command creates new authentication information object using, for attributes not specified in the command, the attribute values of an existing authentication information object.

The Create authentication information (MQCMD_CREATE_AUTH_INFO) command creates an authentication information object. Any attributes that are not defined explicitly are set to the default values on the destination queue manager. A system default authentication information object exists and default values are taken from it.


Required parameters (Change authentication information)

    AuthInfoName (MQCFST)
    The authentication information object name (parameter identifier: MQCA_AUTH_INFO_NAME).

    The maximum length of the string is MQ_AUTH_INFO_NAME_LENGTH.

    AuthInfoType (MQCFIN)
    The type of authentication information object (parameter identifier: MQIA_AUTH_INFO_TYPE). The value can be:

      MQAIT_CRL_LDAP
      This defines this authentication information object as specifying an LDAP server containing Certificate Revocation Lists.

      MQAIT_OCSP
      This value defines this authentication information object as specifying certificate revocation checking using OCSP.

      AuthInfoType MQAIT_OCSP does not apply for use on IBM® i or z/OS® queue managers, but it can be specified on those platforms to be copied to the client channel definition table for client use.

      MQAIT_IDPW_OS
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through the operating system.

      MQAIT_IDPW_LDAP
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through an LDAP server. Important: This option is not valid on z/OS.

    See Securing for more information.


Required parameters (Copy authentication information)

    FromAuthInfoName (MQCFST)
    The name of the authentication information object definition to be copied from (parameter identifier: MQCACF_FROM_AUTH_INFO_NAME).

    On z/OS, the queue manager searches for an object with the name you specify and a disposition of MQQSGD_Q_MGR or MQQSGD_COPY to copy from. This parameter is ignored if a value of MQQSGD_COPY is specified for QSGDisposition . In this case, an object with the name specified by ToAuthInfoName and the disposition of MQQSGD_GROUP is searched for to copy from.

    The maximum length of the string is MQ_AUTH_INFO_NAME_LENGTH.

    ToAuthInfoName (MQCFST)
    The name of the authentication information object to copy to (parameter identifier: MQCACF_TO_AUTH_INFO_NAME).

    The maximum length of the string is MQ_AUTH_INFO_NAME_LENGTH.

    AuthInfoType (MQCFIN)
    The type of authentication information object (parameter identifier: MQIA_AUTH_INFO_TYPE). The value must match the AuthInfoType of the authentication information object from which you are copying. The value can be:

      MQAIT_CRL_LDAP
      This value defines this authentication information object as specifying Certificate Revocation Lists that are held on LDAP.

      MQAIT_OCSP
      This value defines this authentication information object as specifying certificate revocation checking using OCSP.

      MQAIT_IDPW_OS
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through the operating system.

      MQAIT_IDPW_LDAP
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through an LDAP server. Important: This option is not valid on z/OS.

    See Securing for more information.


Required parameters (Create authentication information)

    AuthInfoName (MQCFST)
    Authentication information object name (parameter identifier: MQCA_AUTH_INFO_NAME).

    The maximum length of the string is MQ_AUTH_INFO_NAME_LENGTH.

    AuthInfoType (MQCFIN)
    The type of authentication information object (parameter identifier: MQIA_AUTH_INFO_TYPE). The following values are accepted:

      MQAIT_CRL_LDAP
      This value defines this authentication information object as specifying an LDAP server containing Certificate Revocation Lists.

      MQAIT_OCSP
      This value defines this authentication information object as specifying certificate revocation checking using OCSP.

      An authentication information object with AuthInfoType MQAIT_OCSP does not apply for use on IBM i or z/OS queue managers, but it can be specified on those platforms to be copied to the client channel definition table for client use.

      MQAIT_IDPW_OS
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through the operating system.

      MQAIT_IDPW_LDAP
      This value defines this authentication information object as specifying certificate revocation checking using user ID and password checking through an LDAP server. Important: This option is not valid on z/OS.

    See Securing for more information.


Optional parameters (Change, Copy, and Create Authentication Information Object)

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

      MQADPCTX_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 ShortUser associated with the user entry in LDAP will be adopted as the credentials for authorization checks to be done against.

      MQADPCTX_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 AuthInfoType of MQAIT_IDPW_OS and MQAIT_IDPW_LDAP.

    The maximum length is MQIA_ADOPT_CONTEXT_LENGTH.

    AuthInfoConnName (MQCFST)
    The connection name of the authentication information object (parameter identifier: MQCA_AUTH_INFO_CONN_NAME).

    This parameter is relevant only when AuthInfoType is set to MQAIT_CRL_LDAP or MQAIT_IDPW_LDAP, when it is required.

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

    On Multiplatforms, the maximum length is MQ_AUTH_INFO_CONN_NAME_LENGTH.

    On z/OS, the maximum length is MQ_LOCAL_ADDRESS_LENGTH.

    AuthInfoDesc (MQCFST)
    The description of the authentication information object (parameter identifier: MQCA_AUTH_INFO_DESC).

    The maximum length is MQ_AUTH_INFO_DESC_LENGTH.

    AuthenticationMethod (MQCFIN)
    Authentication methods for user passwords (parameter identifier: MQIA_AUTHENTICATION_METHOD). Possible values are:

      MQAUTHENTICATE_OS
      Use the traditional UNIX password verification method

      This is the default value.

      MQAUTHENTICATE_PAM
      Use the Pluggable Authentication Method to authenticate the user passwords.

      We can set the PAM value only on UNIX and Linux platforms.

    This attribute is valid only for an AuthInfoType of MQAIT_IDPW_OS, and is not valid on IBM MQ for z/OS.

    AuthorizationMethod (MQCFIN)
    Authorization methods for the queue manager (parameter identifier: MQIA_LDAP_AUTHORMD). Possible values are:

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

      MQLDAP_AUTHORMD_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 FindGroup. This value is typically member or uniqueMember.

      MQLDAP_AUTHORMD_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 FindGroup value, typically memberOf.

      MQLDAP_AUTHORMD_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 ShortUser. Membership is indicated by the attribute defined in FindGroup. 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 MQLDAP_AUTHORMD_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.

    BaseDNGroup (MQCFST)
    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 (parameter identifier: MQCA_LDAP_BASE_DN_GROUPS).

    The maximum length is MQ_LDAP_BASE_DN_LENGTH.

    BaseDNUser (MQCFST)
    In order to be able to find the short user name attribute (see ShortUser ) this parameter must be set with the base DN to search for users within the LDAP server (parameter identifier: MQCA_LDAP_BASE_DN_USERS).

    This attribute is valid only for an AuthInfoType of MQAIT_IDPW_LDAP and is mandatory.

    The maximum length is MQ_LDAP_BASE_DN_LENGTH.

    Checkclient (MQCFIN)
    This attribute is valid only for an AuthInfoType of MQAIT_IDPW_OS or MQAIT_IDPW_LDAP (parameter identifier: MQIA_CHECK_CLIENT_BINDING). The possible values are:

      MQCHK_NONE
      Switches off checking.

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

      MQCHK_REQUIRED
      Requires that all applications provide a valid user ID and password.

      MQCHK_REQUIRED_ADMIN
      Privileged users must supply a valid user ID and password, but non-privileged users 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.

      (This setting is not allowed on z/OS systems.)

    Checklocal (MQCFIN)
    This attribute is valid only for an AuthInfoType of MQAIT_IDPW_OS or MQAIT_IDPW_LDAP (parameter identifier: MQIA_CHECK_LOCAL_BINDING). The possible values are:

      MQCHK_NONE
      Switches off checking.

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

      MQCHK_REQUIRED
      Requires that all applications provide a valid user ID and password.
      If your user ID has UPDATE access to the BATCH profile in the MQCONN class, you can treat MQCHK_REQUIRED as if it is MQCHK_OPTIONAL. That is, we do not have to supply a password, but if we do, the password must be the correct one.

      MQCHK_REQUIRED_ADMIN
      Privileged users must supply a valid user ID and password, but non-privileged users are treated as with the OPTIONAL setting. (This setting is not allowed on z/OS systems.)

    ClassGroup (MQCFST)
    The LDAP object class used for group records in the LDAP repository (parameter identifier: MQCA_LDAP_GROUP_OBJECT_CLASS).

    If the value is blank, groupOfNames is used.

    Other commonly used values include groupOfUniqueNames or group.

    The maximum length is MQ_LDAP_CLASS_LENGTH.

    Classuser (MQCFST)
    The LDAP object class used for user records in the LDAP repository (parameter identifier MQCA_LDAP_USER_OBJECT_CLASS).

    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 AuthInfoType of MQAIT_IDPW_LDAP.

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is executed when the queue manager is a member of a queue-sharing group. We can specify one of the following:

    • blank (or omit the parameter altogether). The command is executed on the queue manager on which it was entered.
    • a queue manager name. The command is executed on the queue manager you specify, providing it is active within the queue sharing group. If you specify a queue manager name other than the queue manager on which it was entered, you must be using a queue sharing group environment, and the command server must be enabled.
    • an asterisk (*). The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group.

    The maximum length is MQ_QSG_NAME_LENGTH.

    FailureDelay (MQCFIN)
    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 (parameter identifier: MQIA_AUTHENTICATION_FAIL_DELAY).

    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 parameter is valid only for an AuthInfoType of MQAIT_IDPW_OS or MQAIT_IDPW_LDAP.
    FindGroup (MQCFST)
    Name of the attribute used within an LDAP entry to determine group membership (parameter identifier: MQCA_LDAP_FIND_GROUP_FIELD).

    When AuthorizationMethod = MQLDAP_AUTHORMD_SEARCHGRP, this attribute is typically set to member or uniqueMember.

    When AuthorizationMethod = MQLDAP_AUTHORMD_SEARCHUSR, this attribute is typically set to memberOf.

    When AuthorizationMethod = MQLDAP_AUTHORMD_SRCHGRPSN, this attribute is typically set to memberUid.

    When left blank, if:

    The maximum length is MQ_LDAP_FIELD_LENGTH.

    GroupField (MQCFST)
    LDAP attribute that represents a simple name for the group (parameter identifier: MQCA_LDAP_GROUP_ATTR_FIELD).

    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.

    The maximum length is MQ_LDAP_FIELD_LENGTH.

    GroupNesting (MQCFIN)
    Whether groups are members of other groups (parameter identifier: MQIA_LDAP_NESTGRP). The values can be:

      MQLDAP_NESTGRP_NO
      Only the initially discovered groups are considered for authorization.

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

    LDAPPassword (MQCFST)
    The LDAP password (parameter identifier: MQCA_LDAP_PASSWORD).

    This parameter is relevant only when AuthInfoType is set to MQAIT_CRL_LDAP or MQAIT_IDPW_LDAP.

    The maximum length is MQ_LDAP_PASSWORD_LENGTH.

    LDAPUserName (MQCFST)
    The LDAP user name (parameter identifier: MQCA_LDAP_USER_NAME).

    This parameter is relevant only when AuthInfoType is set to MQAIT_CRL_LDAP or MQAIT_IDPW_LDAP.

    On Multiplatforms, the maximum length is MQ_DISTINGUISHED_NAME_LENGTH.

    On z/OS, the maximum length is MQ_SHORT_DNAME_LENGTH.

    OCSPResponderURL (MQCFST)
    The URL at which the OCSP responder can be contacted (parameter identifier: MQCA_AUTH_INFO_OCSP_URL).

    This parameter is relevant only when AuthInfoType is set to MQAIT_OCSP, when it is required.

    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.

    The maximum length is MQ_AUTH_INFO_OCSP_URL_LENGTH.

    QSGDisposition (MQCFIN)
    Disposition of the object within the group (parameter identifier: MQIA_QSG_DISP). This parameter applies to z/OSonly. Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves). The value can be any of the following values:
    QSGDisposition Change Copy, Create
    MQQSGD_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 parameter MQQSGD_COPY. Any object residing in the shared repository, or any object defined using a command that had the parameter MQQSGD_Q_MGR, is not affected by this command. The object is defined on the page set of the queue manager that executes the command using the MQQSGD_GROUP object of the same name as the ToAuthInfoName object (for Copy) or the AuthInfoName object (for Create).
    MQQSGD_GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameter MQQSGD_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 MQSC command is generated and sent to all active queue managers in the queue sharing group so that they refresh local copies on page set zero: 
    DEFINE AUTHINFO(name)
REPLACE QSGDISP(COPY)
    The Change for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.     		The object definition resides in the shared repository. This definition is allowed only if the queue manager is in a queue sharing group. If the definition is successful, the following MQSC command is generated and sent to all active queue managers in the queue-sharing group so that they make or refresh local copies on page set zero: 
    DEFINE AUTHINFO(name)
REPLACE QSGDISP(COPY)
    The Copy or Create for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
    MQQSGD_PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with MQQSGD_Q_MGR, or MQQSGD_COPY. Any object residing in the shared repository is unaffected. Not permitted.
    MQQSGD_Q_MGR 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 parameter MQQSGD_Q_MGR. Any object residing in the shared repository, or any local copy of such an object, is not affected by this command. This value is the default value. The object is defined on the page set of the queue manager that executes the command. This value is the default value.
    Replace (MQCFIN)
    Replace attributes (parameter identifier: MQIACF_REPLACE). If an Authentication Information object with the same name as AuthInfoName or ToAuthInfoName exists, it specifies whether it is to be replaced. The value can be any of the following values:

      MQRP_YES
      Replace existing definition
      MQRP_NO
      Do not replace existing definition

    SecureComms (MQCFIN)
    Whether connectivity to the LDAP server should be done securely using TLS (parameter identifier MQIA_LDAP_SECURE_COMM).

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

      MQSECCOMM_ANON
      Connectivity to the LDAP server is made securely using TLS just as for MQSECCOMM_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.

      MQSECCOMM_NO
      Connectivity to the LDAP server does not use TLS.

    This attribute is valid only for an AuthInfoType of MQAIT_IDPW_LDAP.

    ShortUser (MQCFST)
    A field in the user record to be used as a short user name in IBM MQ (parameter identifier MQCA_LDAP_SHORT_USER_FIELD). 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 AuthInfoType of MQAIT_IDPW_LDAP and is mandatory.

    The maximum length is MQ_LDAP_FIELD_LENGTH.

    UserField (MQCFST)
    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 (parameter identifier MQCA_LDAP_USER_ATTR_FIELD).

    This field can be blank. If this is the case, any unqualified user IDs use the ShortUser field 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.

    The maximum length is MQ_LDAP_FIELD_LENGTH.