ALTER AUTHINFO

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.


Use MQSC commands

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

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

We can issue this command from sources 2CR. For an explanation of the source symbols, see Use commands on z/OS®.

There are separate syntax diagrams for each AUTHTYPE parameter option:

Synonym: ALT AUTHINFO


Syntax diagram for AUTHTYPE(CRLLDAP)

ALTER AUTHINFO

ALTER AUTHINFO ( name ) AUTHTYPE(CRLLDAP) CMDSCOPE(' ')CMDSCOPE(qmgr-name)
  • 1
  • CMDSCOPE(*)1
  • 2
  • QSGDISP(QMGR)QSGDISP(COPY)QSGDISP(GROUP)1
  • QSGDISP(PRIVATE)
  • 2
  • CONNAME(string)
  • DESCR(string)
  • LDAPPWD(string)
  • LDAPUSER(string)
  • Notes:

    • 1 Valid only when the queue manager is a member of a queue sharing group. We can use queue sharing groups only on IBM MQ for z/OS.
    • 2 Valid only on z/OS.


    Syntax diagram for AUTHTYPE(OCSP)

    ALTER AUTHINFO

    ALTER AUTHINFO ( name ) AUTHTYPE(OCSP) CMDSCOPE(' ')CMDSCOPE(qmgr-name)
  • 1
  • CMDSCOPE(*)1
  • 2
  • QSGDISP(QMGR)QSGDISP(COPY)QSGDISP(GROUP)1
  • QSGDISP(PRIVATE)
  • 2
  • DESCR(string)
  • OCSPURL(string)
  • Notes:

    • 1 Valid only when the queue manager is a member of a queue sharing group. We can use queue sharing groups only on IBM MQ for z/OS.
    • 2 Valid only on z/OS.


    Syntax diagram for AUTHTYPE(IDPWOS)

    ALTER AUTHINFO

    ALTER AUTHINFO ( name ) AUTHTYPE(IDPWOS) CMDSCOPE(' ')CMDSCOPE(qmgr-name)
  • 1
  • CMDSCOPE(*)1
  • 2
  • QSGDISP(QMGR)QSGDISP(COPY)QSGDISP(GROUP)1
  • QSGDISP(PRIVATE)
  • 2
  • ADOPTCTX(YES)ADOPTCTX(NO)
  • AUTHENMD(OS)AUTHENMD(PAM)3
  • CHCKCLNT(NONE)CHCKCLNT(OPTIONAL)CHCKCLNT(REQUIRED)CHCKCLNT(REQDADM)4
  • CHCKLOCL(NONE)CHCKLOCL(OPTIONAL)CHCKLOCL(REQUIRED)CHCKLOCL(REQDADM)4
  • DESCR(string)
  • FAILDLAY(integer)
  • Notes:

    • 1 Valid only when the queue manager is a member of a queue sharing group. We can use queue sharing groups only on IBM MQ for z/OS.
    • 2 Valid only on z/OS.
    • 3 Not valid on z/OS and PAM value can be set only on UNIX.
    • 4 Not valid on z/OS.


    Syntax diagram for AUTHTYPE(IDPWLDAP)

    ALTER AUTHINFO

    ALTER AUTHINFO ( name ) AUTHTYPE(IDPWLDAP)1
  • ADOPTCTX(YES)ADOPTCTX(NO)
  • AUTHORMD(OSSEARCHGRPSEARCHUSRSRCHGRPSN
  • )
  • BASEDNG(string)
  • BASEDNU(string)
  • CHCKCLNT(NONE)CHCKCLNT(OPTIONAL)CHCKCLNT(REQUIRED)CHCKCLNT(REQDADM)
  • CHCKLOCL(NONE)CHCKLOCL(OPTIONAL)CHCKLOCL(REQUIRED)CHCKLOCL(REQDADM)
  • CLASSGRP(string)
  • CLASSUSR(string)
  • CONNAME(string)
  • DESCR(string)
  • FAILDLAY(integer)
  • FINDGRP(string)
  • GRPFIELD(string)
  • LDAPPWD(string)
  • LDAPUSER(string)
  • NESTGRP(NOYES
  • )
  • SECCOMM(YES)SECCOMM(ANON)SECCOMM(NO)
  • SHORTUSR(string)
  • USRFIELD(string)
  • Notes:

    • 1 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 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 is performed on the user ID and password 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.

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

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

      We cannot define an authentication information object as LIKE another authentication object with a different AUTHTYPE. We cannot alter the AUTHTYPE of an authentication information object after we 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
        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.

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

      Important:

      1. 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.
      2. 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:

      3. This parameter is valid only with TYPE(USERMAP), TYPE(ADDRESSMAP) and TYPE (SSLPEERMAP), and only when USERSRC is not set to NOACCESS.
      4. 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
        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, we do not have to supply a password, but if you do, the password must be the correct one.

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

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

        We 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:

      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.

      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:

      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.

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

      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.