Use the MQSC command SET CHLAUTH to create or modify a channel authentication record.
Using MQSC commands
For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.
|IBM® i||UNIX® and Linux®||Windows||z/OS®|
For an explanation of the symbols in the z/OS column, see Using commands on z/OS.
- 1 The channel profile name must be '*' when TYPE is BLOCKADDR.
- 2 Valid only on z/OS when the queue manager is a member of a queue-sharing group.
- 3 Valid only on z/OS.
- 4 Select the appropriate value for TYPE, depending upon the option that you select from the two types of block.
- 5 USERMAP rules apply only to server connection channels.
- 6 Not valid on z/OS.
- 7 If you allow USERSRC to default to MAP, you must set a value for the parameter MCAUSER.
- 8 Mandatory when TYPE is ADDRESSMAP.
Usage notesThe following table shows which parameters are valid for each value of ACTION:
|Parameter||ADD or REPLACE||REMOVE||REMOVEALL|
- CHLAUTH rules can be used for any channels
- USERMAP rules are valid, only for server connection channels.
- Changes, such as mapping the MCAUSER of the channel, take effect only when starting a channel.
Therefore, if a channel is already running, that channel must be stopped, and restarted, for the CHLAUTH rule changes to take effect.
- The name of the channel or set of channels for which you are setting channel authentication configuration. You can use one or more asterisks (*), in any position, as wildcards to specify a set of channels. If you set TYPE to BLOCKADDR, you must set the generic channel name to a single asterisk, which matches all channel names. On z/OS the generic-channel-name must be in quotes if it contains an asterisk.
- The TYPE parameter must follow the
The type of channel authentication record for which to set allowed partner details or mappings to MCAUSER. This parameter is required. The following values can be used:
- This channel authentication record prevents a specified user or users from connecting. The BLOCKUSER parameter must be accompanied by a USERLIST.
- This channel authentication record prevents connections from a specified IP address or addresses. The BLOCKADDR parameter must be accompanied by an ADDRLIST. BLOCKADDR operates at the listener before the channel name is known.
- This channel authentication record maps SSL or TLS Distinguished Names (DNs) to MCAUSER values. The SSLPEERMAP parameter must be accompanied by an SSLPEER.
- This channel authentication record maps IP addresses to MCAUSER values. The ADDRESSMAP parameter must be accompanied by an ADDRESS. ADDRESSMAP operates at the channel.
- This channel authentication record maps asserted user IDs to MCAUSER values. The USERMAP parameter must be accompanied by a CLNTUSER.
- This channel authentication record maps remote queue manager names to MCAUSER values. The QMGRMAP parameter must be accompanied by a QMNAME.
- The action to perform on the channel authentication record. The following values are valid:
- Add the specified configuration to a channel authentication record. This is the default value.
For types SSLPEERMAP, ADDRESSMAP, USERMAP and QMGRMAP, if the specified configuration exists, the command fails.
For types BLOCKUSER and BLOCKADDR, the configuration is added to the list.
- Replace the current configuration of a channel authentication record.
For types SSLPEERMAP, ADDRESSMAP, USERMAP and QMGRMAP, if the specified configuration exists, it is replaced with the new configuration. If it does not exist it is added.
For types BLOCKUSER and 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 REMOVEALL.
- 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 REMOVEALL.
- Remove all members of the list and thus the whole record (for BLOCKADDR and BLOCKUSER ) or all previously defined mappings (for ADDRESSMAP, SSLPEERMAP, QMGRMAP and 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.
- Attention: Host names can be specified in this parameter, only on queue managers that have IBM MQ 8.0 new functions enabled with OPMODE.The filter to be used to compare with the IP address or hostname of the partner queue manager or client at the other end of the channel. Channel authentication records containing hostnames are only checked if the queue manager is configured to look them up with REVDNS(ENABLED). Details of the values that are allowed as hostnames are defined in the IETF documents RFC 952 and RFC 1123. Hostname matching is not case sensitive.
This parameter is mandatory with TYPE(ADDRESSMAP)
This parameter is also valid when TYPE is SSLPEERMAP, USERMAP, or QMGRMAP and ACTION is ADD, REPLACE, or REMOVE. You can define more than one channel authentication object with the same main identity, for example the same SSL peer name, with different addresses. However, you cannot define channel authentication records with overlapping address ranges for the same main identity. See Generic IP addresses for more information about filtering IP addresses.
If the address is generic then it must be in quotes.
- A list of up to 256 generic IP addresses which are banned from accessing this queue manager on any channel. This parameter is only valid with TYPE(BLOCKADDR). See Generic IP addresses for more information about filtering IP addresses.
If the address is generic then it must be in quotes.
- Specifies whether the connection that matches this rule and is being allowed in with
USERSRC(CHANNEL) or USERSRC(MAP), must also specify a
valid user ID and password. The password cannot contain single quotation marks ( ' ).
Attention: This parameter is valid only on queue managers that have IBM MQ 8.0 new functions enabled with OPMODE.
Attention: If you select REQUIRED or REQDADM ( on platforms other than z/OS), and you have not set the CONNAUTH field on the queue manager, or the value of CHCKCLNT is NONE, the connection fails. You receive message AMQ9793 on platforms other than z/OS, and message 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. It only applies to inbound connections which are SVRCONN channels.Example rules that use this attribute:
- 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.
- 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.
- 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.
- Anything in the defined network can use an asserted user ID if a valid password is supplied:
SET CHLAUTH('*.SVRCONN') + TYPE(ADDRESSMAP) ADDRESS('192.0.2.*') + USERSRC(CHANNEL) CHCKCLNT(REQUIRED)
- This rule ensures that SSL authentication must succeed before processing client authentication
according to the policy set at the queue manager:
SET CHLAUTH('SSL.APP1.SVRCONN') + TYPE(SSLPEERMAP) SSLPEER('CN="Steve Smith", L="BankA"') + MCAUSER(SSMITH) CHCKCLNT(ASQMGR)
- The client asserted user ID to be mapped to a new user ID, allowed through unchanged, or blocked.
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.
The maximum length of the string is MQ_CLIENT_USER_ID_LENGTH.
- This parameter applies to z/OS only and specifies
how the command is run when the queue manager is a member of a queue-sharing group.
- ' '
- The command is run on the queue manager on which it was entered. This is the default value.
- The command is run 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 the command was entered, only if you are using a queue-sharing group environment and if the command server is enabled.
- The command is run on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect is the same as entering the command on every queue manager in the queue-sharing group.
- Reserved for future use.
- Provides descriptive information about the channel authentication record, which is displayed when you issue the DISPLAY CHLAUTH command. 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: 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.
- The user identifier to be used when the inbound connection matches the SSL or TLS DN, IP
address, client asserted user ID or remote queue manager name supplied.
This parameter is mandatory with USERSRC(MAP) and is valid when TYPE is SSLPEERMAP, ADDRESSMAP, USERMAP, or QMGRMAP.If you use lowercase user IDs you must enclose them in quotation marks: For example:
SET CHLAUTH('SYSTEM.DEF.SVRCONN') TYPE(USERMAP) CLNTUSER('johndoe') + USERSRC(MAP) MCAUSER(JOHNDOE1) + ADDRESS('::FFFF:184.108.40.206') + DESCR('Client from z/Linux machine') + ACTION(REPLACE)
This allows the lowercase user ID to use channel SYSTEM.DEF.SVRCONN on IP address
::FFFF:220.127.116.11. The MCA user for the connection is
If you display the Channel Status (CHS) of the channel, the output is
This parameter can be used only when ACTION is ADD or REPLACE.
- 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.
This parameter is valid only with TYPE(QMGRMAP).
If the queue manager name is generic then it must be in quotes.
- Attention: This parameter is valid only on queue managers that have IBM MQ 8.0 new functions enabled with OPMODE.This parameter is additional to the SSLPEER parameter.
SSLCERTI restricts matches to being within certificates issued by a particular Certificate Authority.
A blank SSLCERTI acts like a wildcard, matches any Issuer Distinguished Name.
The filter to use to compare with the Subject Distinguished Name of the certificate from the peer queue manager or client at the other end of the channel.
The SSLPEER filter is specified in the standard form used to specify a Distinguished Name. See IBM MQ rules for SSLPEER values for details.
The maximum length of the parameter is 1024 bytes.
- A list of up to 100 user IDs which are banned from use of this channel or set of channels. Use the special value *MQADMIN to mean privileged or administrative users. The definition of this value depends on the operating system, 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 channel initiator, queue manager and advanced message security address spaces are running under.
- This parameter is only valid with TYPE(BLOCKUSER).
- The source of the user ID to be used for MCAUSER at run time. The following values are valid:
- Inbound connections that match this mapping use the user ID specified in the MCAUSER attribute. This is the default value.
- Inbound connections that match this mapping have no access to the queue manager and the channel ends immediately.
- 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 USERSRC(CHANNEL), or USERSRC(MAP) are incompatible. This is because channel access is never blocked in these cases, so there is never a reason to generate a warning.
- Indicates whether this record operates in warning mode.
- This record does not operate in warning mode. Any inbound connection that matches this record is blocked. This is the default value.
- This record operates in warning mode. Any inbound connection that matches this record and would therefore be blocked is allowed access. If channel events are configured, a channel event message is created showing the details of what would have been blocked, see Channel 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.
- If you want message AMQ9787 to be generated, you must add ChlauthIssueWarn=y to the Channels stanza of the qm.ini file.