Using authentication tokens in an application

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

• 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 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.
• To supply an authentication token from a Java application where the IBM MQ JMS library retrieves a token on the application's behalf from a token provider URL:
  The connection factory definition must include the TOKEN_CLIENT_ID and TOKEN_ENDPOINT and TOKEN_CLIENT_SECRET properties as shown in the following example:
  Example Java code to connect to a queue manager using an authentication token:

  // Acquire instance of an MQ connection Factory:
  JmsFactoryFactory ff = JmsFactoryFactory.getInstance(WMQConstants.WMQ_PROVIDER);
  
  JmsConnectionFactory cf = ff.createConnectionFactory();
  // Configure any required CF properties here
  cf.setStringProperty(WMQConstants.TOKEN_ENDPOINT, tokenEndpoint);
  cf.setStringProperty(WMQConstants.TOKEN_CLIENT_ID, clientId);
  cf.setStringProperty(WMQConstants.TOKEN_CLIENT_SECRET, clientSecret);
  context = cf.createContext();

  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.