Configuring a queue manager to accept authentication tokens
Configure your IBM® MQ queue manager to authenticate users and applications with authentication tokens.
Before you begin
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, change the value of the SecurityPolicy attribute to UserExternal or remove it from the Service stanza, then restart the queue manager.
About this task
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.
- Create the key repository.
- 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:
If the runmqakm command returns an error, see runmqakm error codes. If the command completes successfully, use the
runmqakm -keydb -create -db /var/mqm/qmgrs/qm1/tokenissuer/key.kdb -pw MyKeystorePassword -type cms
lscommand to list the contents of the directory:
The following files are displayed:
ls -l /var/mqm/qmgrs/qm1/tokenissuer
-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
- 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.*
- 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.*
- 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.
- Encrypt the key repository password with the runqmcred command and save the encrypted string to a file.
- 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.
- 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')
- 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.keyWhen prompted, enter the key repository password. The encrypted password is output by the command.
Copy the string on the last line and save it to a file.
5724-H72 (C) Copyright IBM Corp. 1994, 2023. Enter password: ************* <QM>!2!b5rb01sMzFzc1ClZeQMryruWFM3HSm8DKyEaZK7qzWY=!TrWdU57DCDXM0Qah99I/Lg==
- Create a file to contain the initial key that is used to encrypt the key repository password.
- 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
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
runmqakm -secretkey -add -db /var/mqm/qmgrs/qm1/tokenissuer/key.kdb -pw MyKeystorePassword -label keylabel -file keyfile -format ascii
- To add the RSA public key certificate to the key repository, issue the following command:
- Add the AuthToken stanza and the following attributes to the
- 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.
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.
AuthToken: KeyStore=/var/mqm/qmgrs/qm1/tokenissuer/key.kdb KeyStorePwdFile=/var/mqm/qmgrs/qm1/tokenissuer/key.pw CertLabel=rsakeyFor 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:
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.
DISPLAY AUTHINFO(authinfo_name) ADOPTCTXSet 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:
- 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
then issue the following MQSC command:
REFRESH SECURITY TYPE(CONNAUTH)