Working with authentication tokens

From IBM® MQ 9.3.4 client applications can provide tokens to authenticate with a queue manager. The user ID in the token can also be used for authorization to access IBM MQ resources.

JWTs (JSON Web Tokens) adopt a claims-based identity model. The identity and access control are abstracted into ideas of claims and token issuers.

A claim is a name value pair that contains information about a user and establishes who the user is, not what they can do.
The token issuer is a trusted third party or a server that is issues a token for a user based only on the identity of the user. The token issuer is not concerned with what the user can do.

A token is a simple structure that contains claims and can easily be transferred between parties over the internet. Using tokens for authentication has the benefit of centralized identity management. You can use one trusted token issuer so your applications can authenticate with many services without separately registering with each service. Tokens provide increased security as credentials are not sent to each service, only to the trusted issuer.

A JWT is defined through the proposed internet standard RFC7519.

How tokens work with IBM MQ

Tokens that are used with IBM MQ must be valid JWTs that have been signed with an algorithm that IBM MQ supports. The JWT must be signed according to the JSON Web Signature (JWS) standard. Tokens that use JSON Web Encryption (JWE) and JSON Web Key (JWK) JOSE technologies cannot be used with IBM MQ. For more information, see Requirements for authentication tokens.

The application that supplies the authentication token can run on any platform that supports IBM MQ clients. The application must be written in C [MQ 9.3.5 Feb 2024] or, from IBM MQ 9.3.5, in Java, and connect to the queue manager using client bindings. However, the queue manager must run on AIX® or Linux®. The queue manager must be configured to accept authentication tokens. A key repository must contain the trusted token issuer's public key certificate or symmetric key, depending on which algorithm is used to sign the token.

The token issuer is the trusted party that has the delegated security access, meaning they verify the identity of the application user. The queue manager checks that an authentication token is valid and that the authenticated user is authorized to access IBM MQ objects. The queue manager can, but does not need to know of the users before they first connect in with a token. The IBM MQ administrator must set up authentication and authorization for the applications that connect to the queue manager, and set the requirements for what the tokens must contain.

The client application can dynamically request a token from the issuer that it uses for authentication when it connects to IBM MQ. The application then uses the MQCSP structure [MQ 9.3.5 Feb 2024] or, from IBM MQ 9.3.5, the equivalent in the chosen API, to pass the token to the queue manager when it connects.

If the application cannot be changed to request an authentication token and present the token to the queue manger when it connects, a security exit can alternatively be used to provide a token in the MQCSP structure.

If the token meets the requirements for authentication tokens, and token signature is valid, the connection is established. The queue manager can also use the user ID contained in the token for authorization checks to access IBM MQ resources if the optional user claim is contained in the token. The user claim is the claim within the token that contains the user ID that the queue manager adopts for authorization checks. This name of the user claim is specified with the UserClaim attribute in the AuthToken stanza of the qm.ini file.

For more information, see Using authentication tokens in an application and MQCSP - Security parameters.

Diagram shows how an application gets a token from the token issuer and uses it to authenticate with the queue manager.

The diagram shows a basic example of the expected flow for use of tokens with IBM MQ. The expected lifecycle is as follows:

The token is issued to an application by the trusted issuer. For more information, see Requirements for authentication tokens.
The application passes the token into the queue manager when connecting. For more information, see Using authentication tokens in an application.
The queue manager validates the token signature against the trusted issuer public key or symmetric key in the key repository. To set up the queue manager, follow the steps in Configuring a queue manager to accept authentication tokens.
If the authentication token contains a valid user claim, the user in the token can be adopted for authorization checks to access IBM MQ resources . For more information, see Adopting users for authorization.
The IBM MQ administrator manages trusted token issuer certificates. When the certificate expires, a new certificate must be obtained from the token issuer and added to the key repository.
If you configured your queue manager and the application is connecting but encounter issues with the token, see Troubleshooting authentication token problems and Token authentication error codes.

IBM MQ works with any token issuer that provides tokens that conform to the JWT and JWS standards.

If you are not already using tokens but want to understand what is involved in standing up a token server, see the Getting started guide for the free and open source Keycloak project.