Channel authentication records

To exercise more precise control over the access granted to connecting systems at a channel level, we can use channel authentication records.

You might find that clients attempt to connect to your queue manager using a blank user ID or a high-level user ID that would allow the client to perform undesirable actions. We can block access to these clients using channel authentication records. Alternatively, a client might assert a user ID that is valid on the client platform but is unknown or of an invalid format on the server platform. We can use a channel authentication record to map the asserted user ID to a valid user ID.

You might find a client application that connects to your queue manager and behaves badly in some way. To protect the server from the issues this application is causing, it needs to be temporarily blocked using the IP address the client application is on until such time as the firewall rules are updated or the client application is corrected. We can use a channel authentication record to block the IP address from which the client application connects.

If we have set up an administration tool such as the IBM MQ Explorer, and a channel for that specific use, you might want to ensure that only specific client computers can use it. We can use a channel authentication record to allow the channel to be used only from certain IP addresses.

If you are just getting started with some sample applications running as clients, see Preparing and running the sample programs for an example of setting up the queue manager securely using channel authentication records.

To get channel authentication records to control inbound channels, use the MQSC command ALTER QMGR CHLAUTH(ENABLED).

• To block connections from specific IP addresses.
• To block connections from specific user IDs.
• To set an MCAUSER value to be used for any channel connecting from a specific IP address.
• To set an MCAUSER value to be used for any channel asserting a specific user ID.
• To set an MCAUSER value to be used for any channel having a specific SSL or TLS Distinguished Name (DN).
• To set an MCAUSER value to be used for any channel connecting from a specific queue manager.
• To block connections claiming to be from a certain queue manager unless the connection is from a specific IP address.
• To block connections presenting a certain SSL or TLS certificate unless the connection is from a specific IP address.

We create, modify, or remove channel authentication records using the MQSC command SET CHLAUTH or the PCF command Set Channel Authentication Record.

Blocking IP addresses

Whenever an inbound connection is refused because the IP address is blocked in this manner, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_ADDRESS is issued, provided that channel events are enabled and the queue manager is running. Additionally, the connection is held open for 30 seconds prior to returning the error to ensure the listener is not flooded with repeated attempts to connect that are blocked.

To block IP addresses only on specific channels, or to avoid the delay before the error is reported, set a channel authentication record of type ADDRESSMAP with the USERSRC(NOACCESS) parameter.

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_NOACCESS is issued, provided that channel events are enabled and the queue manager is running.

See Blocking specific IP addresses for an example.

Blocking user IDs

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_USERID is issued, provided that channel events are enabled.

See Blocking specific user IDs for an example.

We can also block any access for specified user IDs on certain channels by setting a channel authentication record of type USERMAP with the USERSRC(NOACCESS) parameter.

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_NOACCESS is issued, provided that channel events are enabled and the queue manager is running.

See Blocking access for a client user ID for an example.

Blocking queue manager names

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_NOACCESS is issued, provided that channel events are enabled and the queue manager is running.

See Blocking access from a remote queue manager for an example.

Blocking SSL or TLS DNs

Whenever an inbound connection is refused for this reason, an event message MQRC_CHANNEL_BLOCKED with reason qualifier MQRQ_CHANNEL_BLOCKED_NOACCESS is issued, provided that channel events are enabled and the queue manager is running.

See Blocking access for an SSL or TLS Distinguished Name for an example.

Mapping IP addresses to user IDs to be used

If we use a port forwarder, DMZ session break, or any other setup that changes the IP address presented to the queue manager, then mapping IP addresses is not necessarily suitable for your use.

See Mapping an IP address to an MCAUSER user ID for an example.

Mapping queue manager names to user IDs to be used

See Mapping a remote queue manager to an MCAUSER user ID for an example.

Mapping user IDs asserted by a client to user IDs to be used

See Mapping a client user ID to an MCAUSER user ID for an example.

Mapping SSL or TLS DNs to user IDs to be used

See Mapping an SSL or TLS Distinguished Name to an MCAUSER user ID for an example.

Mapping queue managers, clients, or SSL or TLS DNs according to IP address

See Mapping a remote queue manager to an MCAUSER user ID for an example.

Interaction between channel authentication records

• The channel authentication record used is selected as follows:
  • A channel authentication record explicitly matching the channel name takes priority over a channel authentication record matching the channel name by using a wildcard.
  • A channel authentication record using an SSL or TLS DN takes priority over a record using a user ID, queue manager name, or IP address.
  • A channel authentication record using a user ID or queue manager name takes priority over a record using an IP address.
• If a matching channel authentication record is found and it specifies an MCAUSER, this MCAUSER is assigned to the channel.
• If a matching channel authentication record is found and it specifies that the channel has no access, an MCAUSER value of *NOACCESS is assigned to the channel. This value can later be changed by a security exit program.
• If no matching channel authentication record is found, or a matching channel authentication record is found and it specifies that the user ID of the channel is to be used, the MCAUSER field is inspected.
  • If the MCAUSER field is blank, the client user ID is assigned to the channel.
  • If the MCAUSER field is not blank, it is assigned to the channel.
• Any security exit program is run. This exit program might set the channel user ID or determine that access is to be blocked.
• If the connection is blocked or the MCAUSER is set to *NOACCESS, the channel ends.
• If the connection is not blocked, for any channel except a client channel, the channel user ID determined in the previous steps is checked against the list of blocked users.
  • If the user ID is in the list of blocked users, the channel ends.
  • If the user ID is not in the list of blocked users, the channel runs.

• The most specific is a name without wildcard characters, for example:
  • A channel name of A.B.C
  • An IP address of 192.0.2.6
  • A host name of hursley.ibm.com
  • A queue manager name of 192.0.2.6
• The most generic is a single asterisk (*) that matches, for example:
  • All channel names
  • All IP addresses
  • All host names
  • All queue manager names
• A pattern with an asterisk at the start of a string is more generic than a defined value at the start of a string:
  • For channels, *.B.C is more generic than A.*
  • For IP addresses, *.0.2.6 is more generic than 192.*
  • For host names, *.ibm.com is more generic than hursley.*
  • For queue manager names, *QUEUEMANAGER is more generic than QUEUEMANAGER*
• A pattern with an asterisk at a specific place in a string is more generic than a defined value at the same place in a string, and similarly for each subsequent place in a string:
  • For channels, A.*.C is more generic than A.B.*
  • For IP addresses, 192.*.2.6 is more generic than 192.0.*.
  • For host names, hursley.*.com is more generic than hursley.ibm.*
  • For queue manager names, Q*MANAGER is more generic than QUEUE*
• Where two or more patterns have an asterisk at a specific place in a string, the one with fewer nodes following the asterisk is more generic:
  • For channels, A.* is more generic than A.*.C
  • For IP addresses, 192.* is more generic than 192.*.2.*.
  • For host names, hurlsey.* is more generic than hursley.*.com
  • For queue manager names, Q* is more generic than Q*MGR
• Additionally, for an IP address:
  • A range indicated with a hyphen (-), is more specific than an asterisk. Thus 192.0.2.0-24 is more specific than 192.0.2.*.
  • A range that is a subset of another is more specific than the larger range. Thus 192.0.2.5-15 is more specific than 192.0.2.0-24.
  • Overlapping ranges are not permitted. For example, we cannot have channel authentication records for both 192.0.2.0-15 and 192.0.2.10-20.
  • A pattern cannot have fewer than the required number of parts, unless the pattern ends with a single trailing asterisk. For example 192.0.2 is invalid, but 192.0.2.* is valid.
  • A trailing asterisk must be separated from the rest of the address by the appropriate part separator (a dot (.) for IPv4, a colon (:) for IPv6). For example, 192.0* is not valid because the asterisk is not in a part of its own.
  • A pattern can contain additional asterisks, provided that no asterisk is adjacent to the trailing asterisk. For example, 192.*.2.* is valid, but 192.0.*.* is not valid.
  • An IPv6 address pattern cannot contain a double colon and a trailing asterisk, because the resulting address would be ambiguous. For example, 2001::* could expand to 2001:0000:*, 2001:0000:0000:* and so on
• For an SSL or TLS Distinguished Name (DN), the precedence order of substrings is as follows:

  Table 1. Precedence order of substrings

  Order	DN substring	Name
  1	SERIALNUMBER=	Certificate serial number
  2	MAIL=	Email address
  3	E=	Email address (Deprecated in preference to MAIL)
  4	UID=, USERID=	User identifier
  5	CN=	Common name
  6	T=	Title
  7	OU=	Organizational unit
  8	DC=	Domain component
  9	O=	Organization
  10	STREET=	Street / First line of address
  11	L=	Locality
  12	ST=, SP=, S=	State or province name
  13	PC=	Postal code / zip code
  14	C=	Country
  15	UNSTRUCTUREDNAME=	Host name
  16	UNSTRUCTUREDADDRESS=	IP address
  17	DNQ=	Distinguished name qualifier

  Thus, if an SSL or TLS certificate is presented with a DN containing the substrings O=IBM and C=UK, IBM MQ uses a channel authentication record for O=IBM in preference to one for C=UK, if both are present.

  A DN can contain multiple OUs, which must be specified in hierarchical order with the large organizational units specified first. If two DNs are equal in all respects except for their OU values, the more specific DN is determined as follows:
  1. If they have different numbers of OU attributes then the DN with the most OU values is more specific. This is because the DN with more Organizational Units fully qualifies the DN in more detail and provides more matching criteria. Even if its top-level OU is a wildcard (OU=*), the DN with more OUs is still regarded as more specific overall.
  2. If they have the same number of OU attributes then the corresponding pairs of OU values are compared in sequence left-to-right, where the left-most OU is the highest-level (least specific), according to the following rules.
     1. An OU with no wildcard values is the most specific because it can only match exactly one string.
     2. An OU with a single wildcard at either the beginning or end (for example, OU=ABC* or OU=*ABC) is next most specific.
     3. An OU with two wildcards for example, OU=*ABC*) is next most specific.
     4. An OU consisting only of an asterisk (OU=*) is the least specific.
  3. If the string comparison is tied between two attribute values of the same specificity then whichever attribute string is longer is more specific.
  4. If the string comparison is tied between two attribute values of the same specificity and length then the result is determined by a case-insensitive string comparison of the portion of the DN excluding any wildcards.

  If two DNs are equal in all respects except for their DC values, the same matching rules apply as for OUs except that in DC values the left-most DC is the lowest-level (most specific) and the comparison ordering differs accordingly.

Displaying channel authentication records