Requirements for authentication tokens

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

Requirements

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) specification in RFC7519, and the JSON Web Signature (JWS) specification in RFC7515.
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. 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.


{
 "typ":"JWT",
 "alg":"HS256"
}

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. If a token contains more than one parameter or claim with the same name, the last parameter or claim with the duplicate name is used.

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".
Header	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.

Algorithms

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

Asymmetric key certificate requirements

If a token is signed with an asymmetric key, the public key certificate from the token issuer must be in the key repository that the queue manager uses for token authentication. When the authentication token is received, the certificate must be within its validity period. No checks are made to ensure that the certificate from the token issuer has not been revoked.

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.