mq channel authentication
Overview
This resource allows you to manage a MQ Channel authenticatio record.
Here is an example on how you should use this:
mq_channel_authentication { 'QM1/EM_TEST_CHANNEL':
ensure => 'present',
...
}
When used for ADDRESMAP
records the syntax is:
mq_channel_authentication { 'QM1/ADRESSMAP/ADMIN/10.2.248.*':
ensure => 'present',
mcauser => 'my_user',
}
Attributes
Attribute Name | Short Description |
---|---|
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. |
addrlist | A list of up to 256 generic IP addresses which are banned from accessing this queue manager on any channel. |
channel_name | The name of the channel. |
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. |
clntuser | The client asserted user ID to be mapped to a new user ID, allowed through unchanged, or blocked. |
custom | Reserved for future use. |
descr | Provides descriptive information about the channel authentication record, which is displayed when you issue the DISPLAY CHLAUTH command. |
disable_corrective_change | Disable the modification of a resource when Puppet decides it is a corrective change. |
disable_corrective_ensure | Disable the creation or removal of a resource when Puppet decides is a corrective change. |
ensure | The basic property that the resource should be in. |
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. |
name | The full name of the channel. |
provider | resource. |
qmgr | The name of the queue manager containing the specfied queue. |
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. |
record_type | The TYPE parameter must follow the channel-profile-name parameter. |
sslcerti | This parameter is additional to the SSLPEER parameter. |
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. |
userlist | A list of up to 100 user IDs which are banned from use of this channel or set of channels. |
usersrc | The source of the user ID to be used for MCAUSER at run time. |
warn | Indicates whether this record operates in warning mode. |
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.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
channel_name
The name of the channel.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
Back to overview of mq_channel_authentication
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.
[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 REQADM 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)copy to clipboard
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)
Valid values are REQDADM
, REQUIRED
, ASQMGR
.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
custom
Reserved for future use.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
disable_corrective_change
Disable the modification of a resource when Puppet decides it is a corrective change.
(requires easy_type V2.11.0 or higher)
When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.
Using the disable_corrective_change
parameter, you can disable corrective changes on the current resource.
Here is an example of this:
crucial_resource {'be_carefull':
...
disable_corrective_change => true,
...
}
When a corrective ensure does happen on the resource Puppet will not modify the resource and signal an error:
Error: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change
Error: /Stage[main]/Main/Crucial_resource[be_carefull]/parameter: change from '10' to '20' failed: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change. (corrective)
Back to overview of mq_channel_authentication
disable_corrective_ensure
Disable the creation or removal of a resource when Puppet decides is a corrective change.
(requires easy_type V2.11.0 or higher)
When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.
Using the disable_corrective_ensure
parameter, you can disable corrective ensure present or ensure absent actions on the current resource.
Here is an example of this:
crucial_resource {'be_carefull':
ensure => 'present',
...
disable_corrective_ensure => true,
...
}
When a corrective ensure does happen on the resource Puppet will not create or remove the resource and signal an error:
Error: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure.
Error: /Stage[main]/Main/Crucial_resource[be_carefull]/ensure: change from 'absent' to 'present' failed: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure. (corrective)
Back to overview of mq_channel_authentication
ensure
The basic property that the resource should be in.
Valid values are present
, absent
.
Back to overview of mq_channel_authentication
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 lower case 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)copy to clipboard
This allows the lower case 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).
Back to overview of mq_channel_authentication
name
The full name of the channel. A channel’s full name constists of the name of the Queue manager a slash, then the type of record you wish to create and then the name of the channel. Here is an example:
QMGR1/BLOCKUSER/MY.FIRST.CHANNEL
Back to overview of mq_channel_authentication
provider
The specific backend to use for this mq_channel_authentication
resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.Available providers are:
- simple
- Manage MQ Channel authentication records
Back to overview of mq_channel_authentication
qmgr
The name of the queue manager containing the specfied queue.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
record_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.
This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.
Valid values are BLOCKUSER
, BLOCKADDR
, SSLPEERMAP
, ADDRESSMAP
, USERMAP
, QMGRMAP
.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
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.
Back to overview of mq_channel_authentication
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).
Back to overview of mq_channel_authentication
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.
Valid values are MAP
, NOACCESS
, CHANNEL
.
Back to overview of mq_channel_authentication
warn
Indicates whether this record operates in warning mode. Valid values are:
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. An error message is written and, 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.
Valid values are YES
, NO
.