Set Channel Authentication Record

The Set Channel Authentication Record (MQCMD_SET_CHLAUTH_REC) command sets the allowed partner details and mappings to MCAUSER for a channel or set of channels.

Syntax diagram

See the syntax diagram in the MQSC SET CHLAUTH command for combinations of parameters and values that are allowed.

Required parameters

• MQACT_ADD or MQACT_REPLACE
• MQACT_REMOVE
• MQACT_REMOVEALL

ProfileName (MQCFST)

The name of the channel or set of channels for which you are setting channel authentication configuration (parameter identifier: MQCACH_CHANNEL_NAME). We can use one or more asterisks (*), in any position, as wildcards to specify a set of channels. If you set Type to MQCAUT_BLOCKADDR, you must set the generic channel name to a single asterisk, which matches all channel names.

The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

Type (MQCFIN)

The Type parameter must follow the ProfileName parameter. The type of channel authentication record for which to set allowed partner details or mappings to MCAUSER (parameter identifier: MQIACF_CHLAUTH_TYPE). The following values are valid:

MQCAUT_BLOCKUSER

This channel authentication record prevents a specified user or users from connecting. The MQCAUT_BLOCKUSER parameter must be accompanied by a UserList.

MQCAUT_BLOCKADDR

This channel authentication record prevents connections from a specified IP address or addresses. The MQCAUT_BLOCKADDR parameter must be accompanied by an AddrList.

MQCAUT_SSLPEERMAP

This channel authentication record maps TLS Distinguished Names (DNs) to MCAUSER values. The MQCAUT_SSLPEERMAP parameter must be accompanied by an SSLPeer.

MQCAUT_ADDRESSMAP

This channel authentication record maps IP addresses to MCAUSER values. The MQCAUT_ADDRESSMAP parameter must be accompanied by an Address.

MQCAUT_USERMAP

This channel authentication record maps asserted user IDs to MCAUSER values. The MQCAUT_USERMAP parameter must be accompanied by a ClntUser.

MQCAUT_QMGRMAP

This channel authentication record maps remote queue manager names to MCAUSER values. The MQCAUT_QMGRMAP parameter must be accompanied by a QMName.

Optional parameters

Action (MQCFIN)

The action to perform on the channel authentication record (parameter identifier: MQIACF_ACTION). The following values are valid:

MQACT_ADD

Add the specified configuration to a channel authentication record. This is the default value.

For types MQCAUT_SSLPEERMAP, MQCAUT_ADDRESSMAP, MQCAUT_USERMAP and MQCAUT_QMGRMAP, if the specified configuration exists, the command fails.

For types MQCAUT_BLOCKUSER and MQCAUT_BLOCKADDR, the configuration is added to the list.

MQACT_REPLACE

Replace the current configuration of a channel authentication record.

For types MQCAUT_SSLPEERMAP, MQCAUT_ADDRESSMAP, MQCAUT_USERMAP and MQCAUT_QMGRMAP, if the specified configuration exists, it is replaced with the new configuration. If it does not exist it is added.

For types MQCAUT_BLOCKUSER and MQCAUT_BLOCKADDR, the configuration specified replaces the current list, even if the current list is empty. If you replace the current list with an empty list, this acts like MQACT_REMOVEALL.

MQACT_REMOVE

Remove the specified configuration from the channel authentication records. If the configuration does not exist the command fails. If you remove the last entry from a list, this acts like MQACT_REMOVEALL.

MQACT_REMOVEALL

Remove all members of the list and thus the whole record (for MQCAUT_BLOCKADDR and MQCAUT_BLOCKUSER ) or all previously defined mappings (for MQCAUT_ADDRESSMAP, MQCAUT_SSLPEERMAP, MQCAUT_QMGRMAP and MQCAUT_USERMAP ) from the channel authentication records. This option cannot be combined with specific values supplied in AddrList, UserList, Address, SSLPeer, QMName or ClntUser. If the specified type has no current configuration the command still succeeds.

Address (MQCFST)

Attention: Host names can be specified in this parameter, only on queue managers that have IBM MQ Version 8.0 new functions enabled with OPMODE. The filter to be used to compare with the IP address, or host name, of the partner queue manager or client at the other end of the channel (parameter identifier: MQCACH_CONNECTION_NAME).

This parameter is mandatory when Type is MQCAUT_ADDESSMAP and is also valid when Type is MQCAUT_SSLPEERMAP, MQCAUT_USERMAP, or MQCAUT_QMGRMAP and Action is MQACT_ADD, MQACT_REPLACE, or MQACT_REMOVE. We can define more than one channel authentication object with the same main identity, for example the same TLS peer name, with different addresses. See Generic IP addresses for channel authentication records for more information about filtering IP addresses.

The maximum length of the string is MQ_CONN_NAME_LENGTH.

AddrList (MQCFSL)

A list of up to 100 generic IP addresses which are banned from accessing this queue manager on any channel (parameter identifier: MQCACH_CONNECTION_NAME_LIST).

This parameter is only valid when Type is MQCAUT_BLOCKADDR.

The maximum length of each address is MQ_CONN_NAME_LENGTH.

CheckClient (MQCFIN)

Attention: This parameter is valid only on queue managers that have IBM MQ Version 8.0 new functions enabled with OPMODE. The user ID and password requirements for the client connection to be successful. The following values are valid:

MQCHK_REQUIRED_ADMIN

A valid user ID and password are required for the connection to be allowed if you are using a privileged user ID. The password cannot contain single quotation marks ( ' ).

Any connections using a non-privileged user ID are not required to provide a user ID and password.

The user ID and password are checked against the user repository details provided in an authentication information object, and supplied on ALTER QMGR in the CONNAUTH field.

If no user repository details are provided, so that user ID and password checking are not enabled on the queue manager, the connection is not successful.

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

This option is not valid on z/OS® platforms.

MQCHK_REQUIRED

A valid user ID and password are required for the connection to be allowed. The password cannot contain single quotation marks ( ' ).

The user ID and password are checked against the user repository details provided in an authentication information object and supplied on ALTER QMGR in the CONNAUTH field.

If no user repository details are provided, so that user ID and password checking are not enabled on the queue manager, the connection is not successful.

MQCHK_AS_Q_MGR

In order for the connection to be allowed, 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 fails 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, the user ID and password are not required.

ClntUser (MQCFST)

The client asserted user ID to be mapped to a new user ID, allowed through unchanged, or blocked (parameter identifier: MQCACH_CLIENT_USER_ID).

This can be the user ID flowed from the client indicating the user ID the client side process is running under, or the user ID presented by the client on an MQCONNX call using MQCSP.

This parameter is valid only with TYPE(USERMAP) and when Match is MQMATCH_RUNCHECK.

The maximum length of the string is MQ_CLIENT_USER_ID_LENGTH.

CommandScope (MQCFST)

Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is run 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 run on the queue manager on which it was entered.
• a queue manager name. The command is run 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 the command was entered, you must be using a queue sharing group environment, and the command server must be enabled.
• an asterisk (*). The command is run on the local queue manager and is also passed to every active queue manager in the queue sharing group.

Custom (MQCFST)

Reserved for future use.

Description (MQCFST)

Provides descriptive information about the channel authentication record, which is displayed when you issue the Inquire Channel Authentication Records command (parameter identifier: MQCA_CHLAUTH_DESC).

This parameter must contain only displayable characters. In a DBCS installation, it can contain DBCS characters. The maximum length of the string is MQ_CHLAUTH_DESC_LENGTH.

Note: Use characters from the coded character set identifier (CCSID) for this queue manager. Other characters might be translated incorrectly if the information is sent to another queue manager.

MCAUser (MQCFST)

The user identifier to be used when the inbound connection matches the TLS DN, IP address, client asserted user ID or remote queue manager name supplied (parameter identifier: MQCACH_MCA_USER_ID).

This parameter is mandatory when UserSrc is MQUSRC_MAP and is valid when Type is MQCAUT_SSLPEERMAP, MQCAUT_ADDRESSMAP, MQCAUT_USERMAP, or MQCAUT_QMGRMAP.

This parameter is valid only when Action is MQACT_ADD or MQACT_REPLACE.

The maximum length of the string is MQ_MCA_USER_ID_LENGTH.

QMName (MQCFST)

The name of the remote partner queue manager, or pattern that matches a set of queue manager names, to be mapped to a user ID or blocked (parameter identifier: MQCA_REMOTE_Q_MGR_NAME).

This parameter is valid only when Type is MQCAUT_QMGRMAP

The maximum length of the string is MQ_Q_MGR_NAME_LENGTH.

SSLCertIssuer (MQCFST)

This parameter is additional to the SSLPeer parameter.

SSLCertIssuer restricts matches to being within certificates issued by a particular Certificate Authority.

Attention: This parameter is valid only on queue managers that have IBM MQ Version 8.0 new functions enabled with OPMODE.

SSLPeer (MQCFST)

The filter to use to compare with the Distinguished Name of the certificate from the peer queue manager or client at the other end of the channel (parameter identifier: MQCACH_SSL_PEER_NAME).

The SSLPeer value is specified in the standard form used to specify a Distinguished Name. See Distinguished Names and IBM MQ rules for SSLPEER values.

The maximum length of the string is MQ_SSL_PEER_NAME_LENGTH .

UserList (MQCFSL)

A list of up to 100 user IDs which are banned from using this channel or set of channels (parameter identifier: MQCACH_MCA_USER_ID_LIST). The following special value can be used:

*MQADMIN

The exact meaning of this value is determined at runtime. If you are using the OAM supplied with IBM MQ, the meaning depends on platform, as follows:

• On Windows, all members of the mqm group, the Administrators group and SYSTEM
• On UNIX and Linux , all members of the mqm group
• On IBM i, the profiles (users) qmqm and qmqmadm and all members of the qmqmadm group, and any user defined with the *ALLOBJ special setting
• On z/OS, the user ID that the CHINIT and the user ID that the MSTR address spaces are running under

This parameter is only valid when TYPE is MQCAUT_BLOCKUSER.

The maximum length of each user ID is MQ_MCA_USER_ID_LENGTH .

UserSrc (MQCFIN)

The source of the user ID to be used for MCAUSER at run time (parameter identifier: MQIACH_USER_SOURCE). The following values are valid:

MQUSRC_MAP

Inbound connections that match this mapping use the user ID specified in the MCAUser attribute. This is the default value.

MQUSRC_NOACCESS

Inbound connections that match this mapping have no access to the queue manager and the channel ends immediately.

MQUSRC_CHANNEL

Inbound connections that match this mapping use the flowed user ID or any user defined on the channel object in the MCAUSER field.

Note that Warn and MQUSRC_CHANNEL, or MQUSRC_MAP are incompatible. This is because channel access is never blocked in these cases, so there is never a reason to generate a warning.

Warn (MQCFIN)

Indicates whether this record operates in warning mode (parameter identifier: MQIACH_WARNING).

MQWARN_NO

This record does not operate in warning mode. Any inbound connection that matches this record is blocked. This is the default value.

MQWARN_YES

This record operates in warning mode. Any inbound connection that matches this record and would therefore be blocked is allowed access. An error message is written and, if events are configured, an event message is created showing the details of what would have been blocked. The connection is allowed to continue. An attempt is made to find another record that is set to WARN(NO) to set the credentials for the inbound channel.

Error codes

This command might return the following error codes in the response format header, in addition to the values shown at Error codes applicable to all commands.

Reason (MQLONG)

The value can be any of the following values:

MQRCCF_CHLAUTH_TYPE_ERROR

Channel authentication record type not valid.

MQRCCF_CHLAUTH_ACTION_ERROR

Channel authentication record action not valid.

MQRCCF_CHLAUTH_USERSRC_ERROR

Channel authentication record user source not valid.

MQRCCF_WRONG_CHLAUTH_TYPE

Parameter not allowed for this channel authentication record type.

MQRCCF_CHLAUTH_ALREADY_EXISTS

Channel authentication record already exists