Requirements for authentication tokens
Validation requirements, structure, and algorithms for authentication tokens used with IBM® MQ.
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.
- 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.
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. |
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
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
- 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.