[AIX][MQ 9.3.4 Oct 2023][Linux]

Requirements for authentication tokens

Validation requirements, structure, and algorithms for authentication tokens used with IBM® MQ.


Authentication tokens that are used with IBM MQ must meet the following requirements.
  • The token length must not exceed the maximum length of 8192 characters. For more information, see TokenLength (MQLONG) for MQCSP.
  • The token structure and encoding is valid as defined by the JSON Web Token (JWT) and JSON Web Signature (JWS) specifications.
  • The required token header parameters that are specified in Table 1 are present and the values of the parameters are valid.
  • The required payload claims specified in Table 2 are present and the values of the claims are valid.
  • The token is signed with an algorithm in Table 3 that IBM MQ supports.
  • The value of the expiry (exp) claim is later than the current time.
  • If the not before (nbf) claim is present, the value is before the current time.
  • If a user claim is present, the value must meet the requirements for User IDs in authentication tokens.

Token structure

IBM MQ accepts JWTs that conform to the RFC7519 standard. Because the standard specifies possible fields but does not mandate them, it is important to clarify the claims that the token is expected to contain when it connects to IBM MQ.

The JWT must be signed and encoded according to the JWS standard that is defined in RFC7515.

IBM MQ expects the JWS secured token to contain the following three components:
JOSE header

A JSON object that contains parameters that describe the type of token and the cryptographic algorithms that are used to secure its contents.

The following header example declares that the encoded object is a JWT, and that the header and the payload are secured by using the HMAC SHA-256 algorithm.

JWS payload
A JSON object that contains claims as specified in the JWT standard. Each member of the JSON object is a claim. Claims can assert the identity of the token issuer, or the user ID of the bearer.

 "exp": 1685529153,
 "nbf": 1685528150,
 "AppUser": "MyUserName"
JWS signature

Used to validate that the token is issued by a trusted issuer.

These components are represented in the JWS secured token as base64url-encoded strings separated by a period ('.').

An authentication token that conforms to the 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 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.

IBM MQ supports the following parameters and claims in the header and the payload of authentication tokens. Any additional parameters or claims in a token are ignored.

Table 1. Token header parameter descriptions
Token part Parameter name Data type Required Description
Header typ String Yes The token type. The value of this parameter must be "JWT".
alg String Yes The algorithm used to secure the header and the payload. The value of this parameter must be one of the algorithms in Table 3.
Table 2. Token payload claims descriptions
Token part Parameter name Data type Required Description
Payload exp Integer Yes The token expiry time, expressed as the number of seconds since 1 January 1979, 00:00 Coordinated Universal Time. The token is not accepted after this time.
nbf Integer No The time, expressed as the number of seconds since 1 January 1979, 00:00 Coordinated Universal Time before which the token is not accepted.
User claim name specified the in the UserClaim field of the AuthToken stanza in the qm.ini file. String Required only if the user claim in the token is used for authorization. The name of the claim that contains the user ID that is adopted for authorization checks.
For example, if your token has the user claim "AppUser": "MyUserName", then you must specify UserClaim=AppUser in the AuthToken stanza of the qm.ini file.

For a good example of an encoded and decoded token, see the debugger page on the jwt.io website.


IBM MQ supports a subset of algorithms that are included in the JSON Web Algorithms (JWA) specification for JWS secured tokens.
Table 3. JSON Web Algorithms (JWA) supported by IBM MQ for JWS secured tokens
alg parameter value Digital Signature or MAC Algorithm
HS256 HMAC using SHA-256
HS384 HMAC using SHA-384
HS512 HMAC using SHA-512
RS256 RSASSA-PKCS1-v1_5 using SHA-256
RS384 RSASSA-PKCS1-v1_5 using SHA-384
RS512 RSASSA-PKCS1-v1_5 using SHA-512

User IDs in authentication tokens

If the queue manager is configured to adopt the user ID that is contained in the user claim of an authentication token as the context for the application, the user ID that is adopted must meet the following requirements:
  • It can contain up to 12 characters.
  • It must start with one of the following characters:

    A-Z a-z

  • It can contain any of the following characters:

    0-9 A-Z a-z + , - . : = _

  • It must not be one of the reserved user IDs UNKNOWN and NOBODY.