AuthToken stanza of the qm.ini file

Use the AuthToken stanza to configure the queue manager to validate authentication tokens that are provided by connecting applications.

The AuthToken stanza

KeyStore=string

File path for the keystore that contains the trusted issuer's public key certificates and symmetric keys. You can add the keys to an existing keystore or create a new keystore. For more information, see Configuring a queue manager to accept authentication tokens. The queue manager uses the keys in the keystore to verify that the authentication token that the application presents is signed by the trusted issuer.

You can use either a CMS keystore with the file extension .kdb or a PKCS#12 keystore with the file extension .p12. If the keystore file does not exist or it cannot be accessed, then an AMQ7076E: Invalid value for attribute in ini file error is output to the queue manager's error log.

Ensure that the keystore type matches the file name extension for the keystore. IBM® MQ detects the correct format of the keystore, inconsistencies might cause other administrative issues however, if the keystore type and file name extension do not match.

The maximum length of the keystore file path is 256 characters.

KeyStorePwdFile=string

File path for the file that contains the encrypted password for the keystore. The file must contain the encrypted password as a single line of text. Plain text passwords are not accepted.

Use the runqmcred command to encrypt the password before you save it in the keystore password file. The keystore password file must contain only the encrypted password that is created by running the runqmcred command.

The maximum length of the plain text password before it is encrypted is 1024 characters.

This parameter is optional. If it is not provided, the queue manager looks for a stash file with the password in the same directory and with the same name as the keystore, but with the file extension .sth. If the stash file is not found, the configuration is rejected and error message AMQ7006E is output to the queue manager's error log. For more information about the options to store keystore passwords, see Encrypting key repository passwords.

The maximum length of the password file path is 256 characters.

CertLabel=string

The certificate label for a public key certificate or symmetric key in the keystore that is used to validate authentication tokens. You can provide up to 32 certificate labels by repeating the CertLabel attribute.

When you add certificates to the queue manager keystore, give them meaningful labels. Certificate labels are case-sensitive. They can contain alphanumeric characters, punctuation characters, and spaces. If an invalid character is detected, an error is returned and an error message is written to the IBM MQ error log.

Trusted token issuers might provide multiple public key certificates and symmetric keys. For example, public key certificates have validity periods. When they are close to expiry, the token issuer provides a new certificate with a fresh expiry date. For a time, both certificates might be valid.

When applications present tokens for authentication, the list of CertLabels is checked until a valid key that was used to sign the token is found. If the match is found, the token signature is validated.

If CertLabel is not specified, the connection from the application that presents the token fails with reason code 2063 MQRC_SECURITY_ERROR, and message AMQ5786E: Authentication token configuration error is written to the queue manager's error log.

The maximum length of the certificate label is 64 characters.

For example,

AuthToken:
   KeyStore=/var/mqm/qmgrs/qmgrs/qm1/tokenissuer/key.kdb
   KeyStorePwdFile=/var/mqm/qmgrs/qm1/tokenissuer/key.pw
   CertLabel=token
   CertLabel=rsakey
   CertLabel=mark
   ... up to 32 CertLabel fields

UserClaim=string

Claim within the token that contains the user ID that the queue manager adopts for authorization checks.

This parameter is optional if the queue manager is configured with ADOPTCTX(NO). If ADOPTCTX(YES) is used, then this parameter is required. ADOPTCTX is an attribute present in the authentication information (AUTHINFO) object that is referenced by the queue manager's CONNAUTH attribute.

To adopt an identity, the token must contain a claim with the name that is specified in the UserClaim attribute of the AuthToken stanza and ADOPTCTX(YES) must be used.

For example, if your token includes a claim "AppUser": "MyUserName", then you must specify UserClaim=AppUser in the AuthToken stanza of the qm.ini file to adopt the identity "MyUserName" for authorization.

The maximum length of the UserClaim attribute value is 128 characters.

Note: From IBM MQ 9.3.4, if the AuthToken stanza is specified, the effective value of the SecurityPolicy attribute of the Service stanza is set to UserExternal. Token authentication is not available if SecurityPolicy is explicitly set to Group in the Service stanza. If SecurityPolicy is set to Group, remove the SecurityPolicy attribute from the Service stanza, then restart the queue manager. For more information, see SecurityPolicy.

Note: Use the ADOPTCTX attribute of the authentication information object to control whether the user ID in the token is adopted for authorization checks. When you create the queue manager, this attribute is set to ADOPTCTX(YES). This value causes the user ID from the token to be adopted. The user ID must meet the requirements for user IDs in authentication tokens. For more information, see User IDs in authentication tokens. If the token user claim contains a user ID that does not meet the requirements, the connection is rejected with reason code 2035 MQRC_NOT_AUTHORIZED. If ADOPTCTX(NO) is set, the token is used only for authentication, and another user must be used for authorization.

AllowOSGroups=NO (default) |YES

The default value is NO. Determines whether an identity that is adopted from a token is treated as an operating system (OS) user, and whether the group memberships of the matching OS user are honored during authorization. .

AllowOSGroups=NO|N: Authorization checks are based only on the name of the user that is adopted from the token.

AllowOSGroups=YES|Y: Authorization checks are based on the name of the user and the groups they might belong to are also checked.

Example stanza - authentication only

Your AuthToken stanza can be valid with only the two minimum required parameters:

KeyStore file path, and
CertLabel name.

AuthToken:
   KeyStore=/var/mqm/qmgrs/qmgrs/qm1/tokenissuer/key.kdb
   CertLabel=token
   ... up to 32 CertLabel fields

If you only included the two minimum parameters, then:

A stash file key.sth must exist with the encrypted keystore password so the keystore password file is not required.
The token does not contain a username that is to be passed to IBM MQ for authorization. The application can connect and be authenticated but a different mechanism must be in place to provide authorization for the application to do work after it is connected.

Depending on the configuration for your queue manager, the username that is used for authorization might be the one defined on the channel through MCA rules or the username that the client app ran as might exist on your server and belong to groups with authorities. Keep in mind that when you use tokens:

Your queue manager is put into UserExternal mode, which means users that do not exist on the operating system where the queue manager is running can be used for authentication.
Even if you do not include the AllowOSGroups option in your AuthToken qm.ini stanza, the default is set to No. Therefore, if you include the UserClaim but do not specify the AllowOSGroups=Yes, the token user that is adopted for authorization is not checked for groups that it might belong to on the operating system where the queue manager is running.

Example stanza - authentication and authorization

You can define all the AuthToken parameters:

KeyStore file path,
KeyStorePwdFile file path,
CertLabel name,
UserClaim name and
AllowOSGroups option.

AuthToken:
   KeyStore=/var/mqm/qmgrs/qmgrs/QMJWT/ssl/key.kdb
   KeyStorePwdFile=/var/mqm/qmgrs/QMJWT/ssl/key.pw
   CertLabel=token
   CertLabel=rsakey
   CertLabel=mark
   ... up to 32 CertLabel fields
   UserClaim=AppUser
   AllowOSGroups=Y

If you included all the available parameters, then:

Encrypt the password for the keystore by using the runqmcred command. Save it in a file then include the file path in the AuthToken stanza.
The username that is in the authentication token user claim is used for both authentication and authorization.
- The token user might exist as a user on the operating system where the queue manager is running.
- You defined an authentication information object to enable user checking.
- You set up channel authentication records to adopt a user with authorization to interact with IBM MQ objects, based on the channel authentication or MCA rules.

Your strategy for authenticating and authorizing token users depends on your requirements and how your IBM MQ queue managers are already configured. For more information, see the Working with authentication tokens.