Troubleshooting authentication token problems

A list of common authentication token problems, and information to help you resolve them.

The list of problems is divided according to the user who is most likely to benefit from the troubleshooting advice.

Advice for the administrator

Is the queue manager configured to accept authentication tokens?

The queue manager must be configured to accept authentication tokens. For more information, see Configuring a queue manager to accept authentication tokens.

Is the queue manager at a version that supports authentication tokens?

You can use authentication tokens with queue managers that run version IBM® MQ 9.3.4 or later on AIX® or Linux® platforms.

Has the security configuration been refreshed after changing the token authentication configuration?

Changes to the token authentication configuration take effect when the queue manager's security configuration is refreshed, or when the queue manager is restarted. To refresh the queue manager's security configuration, issue the following MQSC command:

REFRESH SECURITY TYPE(CONNAUTH)

Are there messages in the queue manager error log?

If an authentication token is rejected, check for messages in the queue manager error log. The following messages might be issued when an authentication token is rejected:

These messages might contain an error code that describes the cause of the error. For more information, see Token authentication error codes.

The following messages might be issued if the token authentication configuration in the AuthToken stanza of the qm.ini file is invalid:

Is the token issuer's certificate or symmetric key in the key repository?

The token issuer's public key certificates or symmetric keys must be imported into the token authentication key repository for the queue manager to validate the token signature. Public key certificates must not be expired.

Is there a problem accessing the token authentication key repository?

Check that the KeyStore attribute of the AuthToken stanza of the qm.ini file references the correct key repository. The key repository must be either a CMS key repository with the file extension .kdb or a PKCS#12 key repository with the file extension .p12. For more information, see Configuring a queue manager to accept authentication tokens.

Is there a problem with the key repository password?

If you encounter problems with the password to access the token authentication key repository, check the following items:

The encrypted key repository password is stored in a file that is referenced in the AuthToken stanza of the qm.ini file, or in a stash file.
- If the KeyStorePwdFile attribute of the AuthToken stanza of the qm.ini file is specified, it must reference the correct path to the file that contains the encrypted key repository password. The key repository password must be encrypted by using the runqmcred command. The key repository password file must contain only the encrypted password as a single line of text. If an initial key is specified when the password is encrypted, the same initial key must be specified in the queue manager INITKEY attribute. For more information, see runqmcred (protect authentication token keystore password).
- If a key repository password file is not specified by using the KeyStorePwdFile attribute of the AuthToken stanza, a key repository stash file must be present. The stash file has the same name as the key repository, with a .sth file name extension. The stash file is created by the runmqakm command.
The mqm user has read access to the key repository files, the file that contains the key repository password, and the directory that contains the key repository.

Is the user ID in the token not being adopted?

To adopt the user ID in the token user claim for subsequent authorization checks in IBM MQ, you must configure the following:

Set the ADOPTCTX attribute of the authentication information object that is referenced by the queue manager's CONNAUTH attribute to YES.
Set the UserClaim attribute of the AuthToken stanza of the qm.ini file to the name of the claim in the token that contains the user ID to be adopted.

For more information, see AuthToken stanza of the qm.ini file.

Is the SecurityPolicy attribute of the qm.ini Service stanza set to group?

The SecurityPolicy attribute of the Service stanza in the qm.ini file for the queue manager must either be set or allowed to default to UserExternal. If the SecurityPolicy attribute is explicitly set to Group, the authentication token configuration is rejected. For more information, see SecurityPolicy.

Advice for the developer

Is the application receiving an error code when it connects to the queue manager?

If an error occurs when the application attempts to connect to a queue manager with an authentication token, a reason code that describes the error is returned to the application. For more information, see the descriptions for the following reason codes:

Do the client and the queue manager support authentication tokens?

You can use authentication tokens from IBM MQ 9.3.4. The queue manager must run on AIX or Linux platforms. Applications must be IBM MQ MQI clients that connect in client, not bindings mode.

Are you using authentication tokens in a Java application?

You can use authentication tokens with your Java applications, but only with a security exit that uses the MQCSP structure that contains token information. For more information, see Using authentication tokens in an application and Java class MQCSP.

Make sure that your application has INQ authority on the IBM MQ object that it accesses. For more information, see Objects used by JMS that require authorization for non-privileged users.

Are you using the MQCSP structure to pass the authentication token to the queue manager?

You can use authentication tokens with IBM MQ MQI clients that use the MQCSP structure on the MQCONNX call. For more information, see Using authentication tokens in an application.

If any of the fields in the MQCSP structure that is provided by the application contain an invalid value, reason code MQRC_CSP_ERROR is returned to the application. Message AMQ8960E might also be written to the client error log to provide more information about the cause of the error.

For applications that use IBM MQ classes for JMS/Jakarta Messaging, equivalent messages from the com.ibm.mq.exits.MQCSP class are written to the IBM MQ classes for JMS log. For more information, see Error logs in IBM MQ classes for JMS.

Is the structure and contents of the authentication token correct?

An authentication token is a structure with three base64url encoded elements. The elements are the header, payload, and the signature. Each element is separated by a period (.). When decoded, the header and payload must be valid JSON objects. The header and the payload must contain the required header parameters and claims. For more information, see Requirements for authentication tokens.

Does the authentication token contain a valid user claim?

The authentication token can contain a user claim that specifies the user ID that is to be adopted for authorization checks to access IBM MQ objects. The UserClaim attribute of the AuthToken stanza of the qm.ini file must specify the name of the token claim that contains the user ID to be adopted. For example, if your token has the user claim

"AppUser":
"MyUserName"

, then you must specify UserClaim=AppUser in the AuthToken stanza of the qm.ini file. For more information, see Requirements for authentication tokens.

Is the authentication token not yet valid or expired?

The authentication token must have a valid expiry (exp) claim. The value of the claim must be after the time when the token is presented to the queue manager. If the token has a not before (nbf) claim, the time that the token is valid from must be before the time that the token is presented to the queue manager. For more information, see Requirements for authentication tokens.

Is a valid authentication token being rejected?

If the token meets all the requirements for authentication tokens, and the queue manager is configured correctly, check for error messages in the queue manager's error log. The error messages might contain an error code that describes the cause of the error. For more information, see Token authentication error codes.

Is the application attempting to use client reconnection?

You cannot use tokens to connect to IBM MQ if the reconnect option is specified. If an application supplies an authentication token, and specifies the MQCNO_RECONNECT or MQCNO_RECONNECT_Q_MGR option in the MQCNO structure, the connection fails and reason code 2547 MQRC_RECONNECT_INCOMPATIBLE is returned to the application.