Identifying and authenticating users using the MQCSP structure

You can specify the MQCSP connection security parameters structure on an MQCONNX call. The MQCSP structure is the primary way for applications that use the message queue interface (MQI) to control the credentials that are used for authentication.

The MQCSP structure contains credentials, which the authorization service can use to identify and authenticate the user.

The MQCSP structure can be modified by client or server-side security exits, even if the application does not explicitly provide the MQCSP structure. An example of application that does not explicitly provide an MQCSP structure is an application that uses IBM® MQ classes for JMS. 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 IDs. 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 in order to meet the 12 character user ID limit of IBM MQ when adopted as the connection context.
If ChlAuthEarlyAdopt is enabled, the truncation happens after the user credentials have been authenticated.

If ChlAuthEarlyAdopt is not enabled, the truncation happens before adoption. On Windows, if the user is supplied in the format user@domain, this means that the truncation can result in a domain specification that is not valid when the user is less than 12 characters.
For example if a user `ibmmq@windowsdomain` is provided through the MQCSP, it is truncated to `ibmmq@window` in this scenario. This results in the following error:
```
AMQ8074W: Authorization failed as the SID 'SID' does not match the entity 'ibmmq@window'
```
On this basis, if you pass a user ID longer than 12 characters, such as a Windows domain user ID in the form user@domain, through the MQCSP you should configure ChlAuthEarlyAdopt=Y in the qm.ini file to avoid this error.

Alternatively, use ADOPTCTX(NO) on the CONNAUTH AUTHINFO configuration, and use an alternate approach such as a CHLAUTH USERMAP rule, a security exit, or the channel object MCAUSER setting to set the user ID for the channel.