Configuring a queue manager to accept authentication tokens

Configure your IBM® MQ queue manager running on AIX® or Linux® to authenticate users and applications with authentication tokens.

Before you begin

For more information about how tokens work with IBM MQ, Working with authentication tokens.

Before you configure your queue manager, check that the AUTHINFO object that is referenced in the queue manager CONNAUTH attribute is of type IDPWOS. Token authentication is only available when the queue manager is configured for OS user ID and password checking.

Check that the SecurityPolicy attribute of the Service stanza is not set to Group. Token authentication is not available if SecurityPolicy is explicitly set to Group. If SecurityPolicy is set to Group, remove the SecurityPolicy attribute from the Service stanza, then restart the queue manager.

About this task

From IBM MQ 9.3.4 applications can authenticate with the queue manager by using tokens. IBM MQ accepts JSON Web Tokens (JWTs) from trusted issuers that follow the proposed internet standard RFC7519. You can use tokens to authenticate an identity, which then can be adopted for future authorization checks.

Configure your queue manager to accept tokens by saving the trusted issuer's public key certificate or symmetric key to the queue manager's key repository. Add the AuthToken stanza to the qm.ini file and refresh the security configuration so the queue manager picks up the new configuration.

Procedure

Create the key repository.
1. Create a key repository for the public key certificate or symmetric key that is received from the trusted issuer. You can use either a CMS key repository with the file extension .kdb or a PKCS#12 key repository with the file extension .p12.
  Issue the following command to create a CMS key repository:
```
runmqakm -keydb -create -db /var/mqm/qmgrs/qm1/tokenissuer/key.kdb -pw MyKeystorePassword -type cms
```
  If the runmqakm command returns an error, see runmqakm error codes. If the command completes successfully, use the ls command to list the contents of the directory:
```
ls -l /var/mqm/qmgrs/qm1/tokenissuer
```
  The following files are displayed:
```
-rw------- 1 adminuser mqm 88 Feb 22 07:50 key.crl
-rw------- 1 adminuser mqm 88 Feb 22 07:50 key.kdb
-rw------- 1 adminuser mqm 88 Feb 22 07:50 key.rdb
```
2. If necessary, change group ownership for the key repository files you created so that the mqm group can be given read access. Initially, only the admin user who ran the command has access to the created files.
```
chgrp mqm /var/mqm/qmgrs/qm1/tokenissuer/key.*
```
3. Change the mode of the key repository files to add read permissions for group mqm. For example, the following command adds read/write permissions for the file owner, and read only permission for the group.
```
chmod 640 /var/mqm/qmgrs/qm1/tokenissuer/key.*
```
Encrypt the key repository password with the runqmcred command and save the encrypted string to a file.
1. Create a file to contain the initial key that is used to encrypt the key repository password.
  The file must contain the initial key as a single line of text. The maximum length of the initial key is 256 bytes. If you have already set an initial key for the queue manager by using the INITKEY queue manager attribute, copy the value of the INITKEY attribute into the new file. If you have not already set an initial key for the queue manager, create a new, unique encryption key and add it to the initial key file.
  Note: For more information, see INITKEY. If you do not specify the initial key, a default one is used. It is more secure to use your own initial key.
  
  Note: Grant the minimum necessary permissions on the initial key file to keep the contents of the file secure. The initial key file is only used to encrypt the key repository password. Therefore, only administrators who use the initial key to encrypt passwords need access to the read the initial key file.
2. If the queue manager initial key is not already set, set the value of the queue manager INITKEY attribute to the initial key that you created in step 2.a. Use the ALTER QMGR command to set the queue manager initial key. For example:
```
ALTER QMGR INITKEY('myEncrypt10nK3y')
```
3. Issue the runqmcred command to encrypt the key repository password. Use the -sf parameter to specify the path to the file that contains the initial key.
```
runqmcred -sf initial.key
```
  When prompted, enter the key repository password. The encrypted password is output by the command.
```
5724-H72 (C) Copyright IBM Corp. 1994, 2024.
Enter password:
*************
<QM>!2!b5rb01sMzFzc1ClZeQMryruWFM3HSm8DKyEaZK7qzWY=!TrWdU57DCDXM0Qah99I/Lg==
```
  Copy the string on the last line and save it to a file.
Use one of the following methods to add the token issuer's public key certificate or symmetric key to the key repository.
- To add the RSA public key certificate to the key repository, issue the following command:
```
runmqakm -cert -add -db /var/mqm/qmgrs/qm1/tokenissuer/key.kdb -pw MyKeystorePassword -label keylabel
         -file keyfile
```
- To add a base64 encoded symmetric key to the key repository, issue the following command:
```
runmqakm -secretkey -add -db /var/mqm/qmgrs/qm1/tokenissuer/key.kdb -pw MyKeystorePassword -label keylabel
         -file keyfile -format ascii
```
Where keylabel is the label to be attached to the certificate or secret key, and keyfile is the name of the file that contains the certificate or the base64 encoded secret key.
Add the AuthToken stanza and the following attributes to the qm.ini file:
- The path to the key repository, specified by using the KeyStore attribute.
- The file that contains the password for the key repository, specified by using the KeyStorePwdFile attribute.
- The label of the certificate or symmetric key that you added in step 3, specified by using the CertLabel attribute.
For example:
```
AuthToken:
   KeyStore=/var/mqm/qmgrs/qm1/tokenissuer/key.kdb
   KeyStorePwdFile=/var/mqm/qmgrs/qm1/tokenissuer/key.pw
   CertLabel=rsakey
```
Where key.kdb is the name of the key repository that you created in step 1.a, and key.pw is the file that contains the encrypted password for the key repository that you created in step 2.c.
For more information about the AuthToken stanza, see AuthToken stanza of the qm.ini file.
If the queue manager is configured to adopt the user ID that is contained in the token user claim for use in subsequent authorization checks, add the UserClaim attribute to the AuthToken stanza.
To determine whether the queue manager is configured to adopt the user ID in the token, issue the following MQSC command:
```
DISPLAY AUTHINFO(authinfo_name) ADOPTCTX
```
Where authinfo_name is the value of the queue manager CONNAUTH attribute. If the value of the ADOPTCTX attribute is YES, the queue manager is configured to adopt the user ID in the token, and the UserClaim attribute must be specified in the AuthToken stanza.
Set the value of the UserClaim attribute to the name of the token claim that contains the user ID to be adopted. For example, if the token contains the claim "AppUser": "MyUserName", add the following line to the AuthToken stanza:
```
UserClaim=AppUser
```
Refresh the queue manager's security configuration so it picks up the token configuration from the qm.ini file. Issue the following command to start the runmqsc command:
```
runmqsc qm1
```
then issue the following MQSC command:
```
REFRESH SECURITY TYPE(CONNAUTH)
```

What to do next

Work with your developers to help them understand how they can use tokens in applications to authenticate with the queue manager.