SET CHLAUTH

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.

[z/OS]You can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which you can issue MQSC commands on z/OS®.

SET CHLAUTH

Read syntax diagramSkip visual syntax diagram SET CHLAUTH ( channel-profile-name )1 TYPE Blocking BlockMapping Block2 CMDSCOPE(' ')CMDSCOPE(qmgr-name)3CMDSCOPE(*)34CUSTOM(custom-values)DESCR(' ')DESCR(string)ACTION(ADD)ACTION(REPLACE)ACTION(REMOVE)ACTION(REMOVEALL)
Blocking Block
Read syntax diagramSkip visual syntax diagram(BLOCKUSER)USERLIST(,user-name)(BLOCKADDR)ADDRLIST(,generic-ip-address)WARN(NO)WARN(YES)
Mapping Block
Read syntax diagramSkip visual syntax diagram(SSLPEERMAP)TLS Peer(ADDRESSMAP)(USERMAP)5CLNTUSER(client-user-name)CHCKCLNT(ASQMGR)CHCKCLNT(REQDADM)6CHCKCLNT(REQUIRED)(QMGRMAP)QMNAME(generic-partner-qmgr-name)USERSRC(MAP)MCAUSER(user)7USERSRC(NOACCESS)WARN(NO)WARN(YES)USERSRC(CHANNEL)ADDRESS(generic-ip-address)8
TLS Peer
Read syntax diagramSkip visual syntax diagram SSLPEER ( generic-ssl-peer-name ) SSLCERTI(generic-issuer-name)
Notes:
  • 1 The channel profile name must be '*' when TYPE is BLOCKADDR.
  • 2 Select the appropriate value for TYPE, depending upon the option that you select from the two types of block.
  • 3 Valid only on z/OS when the queue manager is a member of a queue sharing group.
  • 4 Valid only on z/OS.
  • 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 notes

The following table shows which parameters are valid for each value of ACTION:
  Action
Parameter ADD or REPLACE REMOVE REMOVEALL
CHLAUTH X X X
TYPE X X X
[z/OS]CMDSCOPE [z/OS] X [z/OS] X [z/OS] X
ACTION X X X
ADDRESS X X  
ADDRLIST X X  
CHCKCLNT X    
CLNTUSER X X  
MCAUSER X    
QMNAME X X  
SSLCERTI X X  
SSLPEER X X  
USERLIST X X  
USERSRC X    
WARN X    
DESCR X    
Note the following:
  • 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.

Parameters

channel-profile-name
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.
TYPE
The TYPE parameter must follow the channel-profile-name parameter.

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:

BLOCKUSER
This channel authentication record prevents a specified user or users from connecting. The BLOCKUSER parameter must be accompanied by a USERLIST.
BLOCKADDR
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.
SSLPEERMAP
This channel authentication record maps TLS Distinguished Names (DNs) to MCAUSER values. The SSLPEERMAP parameter must be accompanied by an SSLPEER.
ADDRESSMAP
This channel authentication record maps IP addresses to MCAUSER values. The ADDRESSMAP parameter must be accompanied by an ADDRESS. ADDRESSMAP operates at the channel.
USERMAP
This channel authentication record maps asserted user IDs to MCAUSER values. The USERMAP parameter must be accompanied by a CLNTUSER.
QMGRMAP
This channel authentication record maps remote queue manager names to MCAUSER values. The QMGRMAP parameter must be accompanied by a QMNAME.
ACTION
The action to perform on the channel authentication record. The following values are valid:
ADD
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
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
Remove the specified configuration from the channel authentication records. Note, that if the configuration does not exist the command still works. If you remove the last entry from a list, this acts like REMOVEALL.
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.
ADDRESS
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. 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 host names 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 TLS 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 channel authentication records for more information about filtering IP addresses.

If the address is generic then it must be in quotes.

ADDRLIST
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 channel authentication records for more information about filtering IP addresses.

If the address is generic then it must be in quotes.

CHCKCLNT
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 ( ' ).
REQDADM
A valid user ID and password are required for the connection to be allowed if you are using a privileged user ID.

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.

[z/OS]This option is not valid on z/OS platforms.

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.

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

Attention: If you select REQUIRED or REQDADM on Multiplatforms and you have not set the CONNAUTH field on the queue manager, or if the value of CHCKCLNT is NONE, the connection fails. On Multiplatforms, you receive message AMQ9793. On z/OS, you receive message CSQX793E.
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:
  • 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)
CLNTUSER
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.

[z/OS]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.
' '
The command runs on the queue manager on which it was entered. This is the default value.
qmgr-name
The command runs 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 runs 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.
CUSTOM
Reserved for future use.
DESCR
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.
MCAUSER
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.

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:9.20.4.136') +
    DESCR('Client from z/Linux machine') +
    ACTION(REPLACE)

This allows the lowercase user ID to use channel SYSTEM.DEF.SVRCONN on IP address ::FFFF:9.20.4.136. The MCA user for the connection is JOHNDOE1.

If you display the Channel Status (CHS) of the channel, the output is MCAUSER(JOHNDOE1).

This parameter can be used only when ACTION is ADD or REPLACE.

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

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

SSLPEER

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.

USERLIST
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:
  • [Windows]On Windows, all members of the mqm group, the Administrators group and SYSTEM.
  • [UNIX][Linux]On UNIX and Linux®, all members of the mqm group.
  • [IBM i]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.
  • [z/OS]On z/OS, the user ID that the channel initiator, queue manager and advanced message security address spaces are running under.
For more information about privileged users, see Privileged users.
This parameter is only valid with TYPE(BLOCKUSER).
USERSRC
The source of the user ID to be used for MCAUSER at run time. The following values are valid:
MAP
Inbound connections that match this mapping use the user ID specified in the MCAUSER attribute. This is the default value.
NOACCESS
Inbound connections that match this mapping have no access to the queue manager and the channel ends immediately.
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 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.

WARN
Indicates whether this record operates in warning mode.
NO
This record does not operate in warning mode. Any inbound connection that matches this record is blocked. This is the default value.
YES
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.