Identifying and authenticating users through the MQCSP structure

The IBM® MQ connection security parameters (MQCSP) structure contains credentials that the authorization service can use to identify and authenticate the user. Applications that use the message queue interface (MQI) use the MQCSP structure to control the credentials that are used for authentication. You can specify the MQCSP structure on an MQCONNX call.

The MQCSP structure can be modified by client or server-side security exits, even if the application does not explicitly provide the MQCSP structure. For example, an application that uses IBM MQ classes for JMS does not explicitly provide an MQCSP structure. For an example of a client-side security exit that inserts a user ID and password in the MQCSP structure, see Client side security exit to insert user ID and password ( mqccred ).

The MQCSP structure contains a user ID and password, or an authentication token. The following restrictions apply to credentials supplied in the MQCSP structure:

An application or exit must supply either a user ID and password, or an authentication token, but not both.
Only authentication tokens that meet specific formats and requirements can be used to access IBM MQ. For more information about the requirements for authentication tokens in IBM MQ, see Requirements for authentication tokens.
If the identity in the authentication token is to be adopted as the context for the application, the token must provide a suitable user claim, and the claim value must be a valid IBM MQ user ID. For example, the username must comply with maximum length and special character restrictions. For more information about adopting a user ID, see Relationship between MQCSP and ADOPTCTX settings.

For more information about the MQCSP structure, see MQCSP - Security parameters.

Warning: The credentials in an MQCSP structure for a client application are sometimes sent across the network in plain text. To ensure that client application credentials are protected, see MQCSP password protection.

Relationship between MQCSP and ADOPTCTX settings

IBM MQ always authenticates credentials that are passed in the MQCSP structure if the connection authentication feature is enabled. After the credentials are authenticated successfully, IBM MQ can adopt the user ID for subsequent authorization checks on operations performed by the connected application. The user ID in the MQCSP credentials is adopted if the authentication information (AUTHINFO) object that is referenced by the queue manager's CONNAUTH attribute is defined with ADOPTCTX(YES).

IBM MQ has a limit on the length of user IDs that it can use for authorization checks. For more information about these limits, see User identities in IBM MQ. When a user ID passed in the MQCSP structure is adopted, IBM MQ behaves differently, depending on other configuration options:

When using LDAP connection authentication, IBM MQ adopts the user ID that is in the short username attribute of the user's LDAP record. The short username attribute is set using the SHORTUSR attribute of the AUTHINFO object.
For example, if SHORTUSR is set to 'CN', and the LDAP record lists the user as 'CN=Test,SN=MQ,O=IBM,C=UK', the user ID Test is used.
When using OS connection authentication or PAM authentication, if ADOPTCTX is YES, the user ID passed in the MQCSP structure is truncated to meet the 12 character user ID limit of IBM MQ when adopted as the connection context.

When using OS connection authentication or PAM authentication, adopting a longer username in its entirety is supported on some server platforms from IBM MQ 9.4.3. See AllowLongUID. Note however that a truncated form is still passed in the message identity context (the UserIdentity field in the MQMD). For platforms and versions that do not support adopting a longer username, if ADOPTCTX is YES, the user ID passed in the MQCSP structure is truncated to meet the 12 character user ID limit of IBM MQ when adopted as the connection context.

If ChlAuthEarlyAdopt is enabled in the qm.ini file, which it is by default, you can pass a user ID longer than 12 characters through the MQCSP (such as a Windows domain user ID in the form user@domain) without generating an error. This is because the truncation happens after the user credentials have been authenticated.
If ChlAuthEarlyAdopt is not enabled, the truncation happens before adoption. This can result in a domain specification that is not valid. For example, if a user ibmmq@windowsdomain is provided through the MQCSP and ChlAuthEarlyAdopt is not enabled, the user name is truncated to ibmmq@window and the following error is displayed:
```
AMQ8074W: Authorization failed as the SID 'SID' does not match the entity 'ibmmq@window'
```
Alternatively, use ADOPTCTX(NO) on the CONNAUTH AUTHINFO configuration, and use an alternate approach to set the user ID for the channel. For example:
- a CHLAUTH USERMAP rule
- a security exit
- the channel object MCAUSER setting