Using authentication tokens in an application

Write your application to supply an authentication token when it connects to an IBM® MQ queue manager.

Before you begin

From IBM MQ 9.3.4, applications can supply an authentication token when they connect to a queue manager.

The application must meet the following requirements:

It must be written in C.
It must connect to the queue manager as an IBM MQ client. That is, the application must connect to the queue manager over a network, instead of using local bindings.
It must connect to a queue manager that runs on AIX® or Linux®.

If the application does not meet these requirements, the connection fails and reason code MQRC_FUNCTION_NOT_SUPPORTED (2298) is returned to the application.

The application that supplies the authentication token can run on any platform that supports IBM MQ MQI clients.

Clients that use automatic client reconnection cannot supply an authentication token when they connect. 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 MQRC_RECONNECT_INCOMPATIBLE (2547) is returned to the application. For more information about automatic client reconnection, see Automatic client reconnection.

If you cannot write the application to supply an authentication token due to these requirements, you can alternatively migrate your application to use authentication tokens by using a client security exit. The client security exit can be written to set the authentication token in the MQCSP structure. For more information about security exits, see Security exits on a client connection.

IBM MQ 9.3.4 introduces limited support for authentication tokens for Java applications but only through the use of security exits. New classes for JMS are added for use in security exits that can use the information in the MQCSP to add the token when the JMS application connects to the queue manager. For more information, see Java class MQCSP.

About this task

Note: An authentication token that conforms to the JSON Web Signature (JWS) standard is signed to allow the token's authenticity to be validated, but it is not encrypted. Therefore, it can be read, and possibly reused, by anyone who has access to the token. Configure the connection to the queue manager to ensure that the authentication token is protected by using encryption when it is sent over the network, for example, by using TLS. For more information about the options to protect credentials that are supplied by an application, see MQCSP password protection.

Before modifying applications to connect using a token ensure:

The queue manager has been configured to accept authentication tokens by following the steps in Configuring a queue manager to accept authentication tokens
Your application can obtain a valid token as required from your authentication server, see Obtain an authentication token from your chosen token issuer.

To supply an authentication token when the application connects to an IBM MQ queue manager, include the following process.

Procedure

Supplying an authentication token from a C (MQI) application.

The application must connect using MQCONNX (rather than MQCONN) and supply an MQCSP structure:

The AuthenticationType field must be set to MQCSP_AUTH_ID_TOKEN.
The version of the structure must be set to MQCSP_VERSION_3.
The TokenPtr or TokenOffset field must reference your authentication token.
The TokenLength field must be set to the length of the authentication token.

Example C code to connect to a queue manager using MQCSP Version 3 and authentication token:


MQCNO cno = {MQCNO_DEFAULT};   /* Connection options  */
MQCSP csp = {MQCSP_DEFAULT};   /* Security parameters */

char  token[MQ_CSP_TOKEN_LENGTH +1] = {0};  /* Authentication token string */

/* Set the connection options */
cno.SecurityParmsPtr = &csp;
cno.Version = MQCNO_VERSION_5;

/* Set the security parameters */
csp.Version = MQCSP_VERSION_3;
csp.AuthenticationType = MQCSP_AUTH_ID_TOKEN;
csp.TokenPtr = token;
csp.TokenLength = (MQLONG) strlen(token);

/* Connect to the queue manager */
MQCONNX(qmName,                 /* Queue manager name  */
        &cno,                   /* Connection options  */
        &hCon,                  /* Connection handle   */
        &compCode,              /* Completion code     */
        &reason);               /* Reason code         */

Results

The application is now connected to the queue manager. It remains connected until it disconnects, even if the token that was used to authenticate expires. If the application disconnects from the queue manager and needs to reconnect, it might need to obtain a new authentication token with a later expiry time before it can reconnect.