Configuring a queue manager to accept authentication tokens

Configure your IBM® MQ queue manager to authenticate users and applications with authentication tokens.

1. 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.*

2. 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.
3. 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.
4. 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.
5. 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

6. 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)