Working with authentication tokens

An introduction to authentication tokens and instructions for tasks that are related to using tokens with IBM® MQ. You can use tokens for authentication when applications connect to an IBM MQ queue manager. The user ID in the token can also be used for authorization to access IBM MQ resources.

From IBM MQ 9.3.4 client applications can provide tokens to authenticate with a queue manager. The queue manager must be configured to accept authentication tokens.

Queue managers that run on AIX® or Linux® platforms support authentication tokens.

An application that supplies the authentication token can run on any platform that supports IBM MQ MQI clients. The application must be written in C and connect to the queue manager using client bindings.

Using tokens for authentication has the benefit of centralized identity management. You can use one trusted issuer so your applications can authenticate with many services without separately registering with all of them. Tokens provide increased security as credentials are not sent to each service, only to the trusted issuer.

JSON Web Tokens (JWTs), adopt a claims-based identity model. The identity and access control are abstracted into ideas of claims and trusted issuers. Claims are name value pairs that contain information about a user. The claims state information to establish who the user is, not what they can do. The token issuer is a trusted third party or a server that is only concerned with the identity of the user and this is the basis on which it issues a token for that user. The trusted issuer is not concerned with what the user can do.

In IBM MQ, the queue manager checks that an authentication token is valid and that the authenticated user is authorized to access IBM MQ objects.

The claims that the queue manager expects are therefore included based on the distinction between authentication and authorization. The token is valid with the required header parameters and the expiry claim only. The user claim is not required for authentication. However, if the queue manager is configured to adopt the token identity for authorization, the user claim must be present.

Tokens

A token is a simple structure that contains information about a user and can easily be transferred between parties over the internet. A JWT is defined through the proposed internet standard RFC7519. A JWT can be cryptographically signed to form a JSON Web Signature (JWS). This allows for the cryptographic verification of the information inside the JWT.

Tokens that are used with IBM MQ must be valid JWT tokens that have been signed as defined by the internet standard RFC7515 for JWS with an algorithm that IBM MQ supports. For examples of how content is signed to produce JWS objects, see RFC7520.

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.

How tokens work with IBM MQ

The queue manager must be configured to accept 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 can, but does not need to know of the users before they first connect in with a token. The assumption is that the IBM MQ administrator has awareness of the needs of the applications that connect to the queue manager and sets up authentication and authorization and sets 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 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. If it contains the optional user claim, the queue manager can also use the user ID contained in the token for authorization checks to access IBM MQ resources.

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 in the MQCSP structure to the queue manager on the MQCONNX call. 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 that it has in its key repository. To set up the queue manager, follow the steps in Configuring a queue manager to accept authentication tokens.
If the token contains a valid user claim, the token user can be adopted as IBM MQ user. For more information, see Adopting users for authorization.
IBM MQ administrator manages trusted issuer certificates. For more information, see the managing your certificates topic.
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 topics.

IBM MQ works with any trusted issuer that provides tokens that conform to the JWT standard that is defined in RFC7519, and are signed according to the JWS standard that is defined in RFC7515.

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.