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 or Java (using the IBM MQ classes for JMS/ Jakarta Messaging)
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.

[MQ 9.3.5 Feb 2024] From IBM MQ 9.3.5, JMS client applications can directly provide a token when connecting (see Obtaining an authentication token from your chosen token issuer). In IBM MQ 9.3.4, Java applications can indirectly provide a token by way of an exit program. 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 Obtaining 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

To supply 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         */

To supply an authentication token from a Java application:
Applications using the IBM MQ classes for JMS/Jakarta Messaging can provide a token through any of the createContextor createConnection methods, which take a username and password.
To provide an authentication token, the :
- UserID must be set to either null or an empty string, that is, without spaces , ""
- The token is provided as the Password string.
This applies to all IBM MQ implementations of the ConnectionFactory interface.
Either the explicit parameter forms, for example, createContext(String userID, String password) can be used, or the implicit parameter versions, for example, createContext().

In the latter case, the empty userID and Token Password must have first been provided as properties on the connection factory.
Example Java code to connect to a queue manager using an authentication token:
```
// Obtain token from authentication provider here:

String myToken = "xxxxxxxxxxxxxxxx";

// Acquire instance of an MQ connection Factory:

JmsFactoryFactory ff = JmsFactoryFactory.getInstance(WMQConstants.WMQ_PROVIDER);

JmsConnectionFactory cf = ff.createConnectionFactory();

// Configure any required CF properties here - e.g. MQ Channel details

// Connect to (and authenticate with) the queue manager:

context = cf.createContext(null, myToken); // NOTE - null userID indicates token being provided
```
If the connection fails with reason code MQRC_NOT_AUTHORIZED (2035) or MQRC_SECURITY_ERROR (2063), check the queue manager error log for an error message that contains more information about the cause of the failure. For more help with diagnosing problems with authentication tokens, see Troubleshooting authentication token problems.

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.