View Only

How to use AMS to enforce security and governance by encrypting IBM MQ messages on OpenShift

By Théo Reignier posted Thu July 28, 2022 12:16 PM




You have an IBM MQ queue manager. An application is putting messages to a queue. Another application gets these messages from the queue.

Initial scenario


You want to encrypt sensitive messages in the queue such as those containing Personally Identifiable Information (PII) or financial transactions.

IBM MQ Administrators, such as engineers working on the system, should not be able to read these messages from the queue to enforce confidentiality and governance.

Applications authenticated as the sender (putter apps) must encrypt the messages before putting them in the queue, while applications authenticated as the receiver (getter app) are the only party able to retrieve and decrypt this information.


You have a messaging app that allows individuals to communicate with each other, using IBM MQ.

The following three personas will be used throughout this tutorial:

  • Alice, the message sender
  • Bob, the message receiver
  • James, the IBM MQ Administrator

Alice can send a message containing PII to Bob that only he can read, which James cannot decrypt.

Proposed solution using AMS


Advanced Messaging Security (AMS) is an MQ feature which performs this encryption.

The authenticated sender (Alice) encrypts the messages before putting them in the queue. Only the authenticated receiver (Bob) is able to decrypt them upon reception.

AMS is then enforced by default to avoid human error. You cannot forget to encrypt a message.



If you want to create the entire end-to-end demo solution as described above from scratch, you can simply follow the instructions below.

You will need:

  • A Red Hat OpenShift cluster version 4.10 or later (required for IBM MQ operator v2.0.0 [ref])
  • On your local machine:

The instructions below are broken into sections, so if you instead want to use this tutorial as the basis for adding to an existing scenario (e.g. you already have an IBM MQ queue manager and want to add AMS) you can just choose the relative sections to follow.

IBM MQ with AMS on OpenShift

Setup LDAP

Install a development LDAP server that will manage user identities for the IBM MQ queue manager.

In order to authenticate applications to MQ, LDAP is required when running in a container as system users can't be used. An install script for LDAP has been provided in the 01-install-ldap directory.


LDAP installation

Two LDAP users are defined in ldap-config.ldif, both members of the same group:

    • mqwrite user for the putter app to put messages in the queue
dn: uid=mqwrite,ou=people,dc=ibm,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: mqwriteCN
sn: mqwriteSN
uid: mqwrite
userPassword: mqwrite
    • mqread user for the Getter app to get messages from the queue
dn: uid=mqread,ou=people,dc=ibm,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: mqreadCN
sn: mqreadSN
uid: mqread
userPassword: mqread
    • mqusers group which includes both mqwrite and mqread users
dn: cn=mqusers,ou=groups,dc=ibm,dc=com
objectClass: groupOfUniqueNames
objectClass: top
cn: mqusers

Generate certificates

Generate a new self-signed Certificate Authority (CA), and use it to create certificates for the MQ queue manager and the JMS MQ client apps.

Certificates are used to secure the connection between the apps and the MQ Queue Manager. The queue manager will only accept connections from certified apps.

These certificates will be used locally by the apps and stored in OpenShift secrets to be used by MQ.

Generating certificates for MQ

To generate certificates for MQ, update the variables at the top of the script before running it:

# Certificate information - Edit these variables to suit your project
export ORGANISATION=acmeinc
export LOCALITY=Hursley
export STATE=Hampshire

This script will create a 02-cert-generation/certs directory where the following files will be stored:

  • ams-ca files - with the CA used to sign all certs in the tutorial demo
  • ams-client files - used by the JMS applications
  • ams-mq-server files - used by the IBM MQ queue manager

Generate MQS keys

Generate MQS keys to authenticate MQ users and enable encryption.

Only one user is allowed to send and encrypt messages (Alice), while only one user is allowed to receive and decrypt messages (Bob).

Generating MQS keys

AMS makes use of MQS keys to:

  • Authenticate the user performing the get/put action on the queue
  • Encrypt messages with Alice's MQS key such that they can only be decrypted using Bob's MQS key

Setup IBM MQ on OpenShift

Create and configure a queue manager with AMS using IBM MQ OpenShift operator.

In order to deploy the IBM MQ operator on Red Hat OpenShift and deploy a Queue Manager with AMS, follow the steps below.

This tutorial assumes that you will be following the instructions on an OpenShift cluster where the MQ operator has not already been installed. Please read the instructions carefully if you already have a version of the operator installed.

IBM MQ on OpenShift

  1. To deploy the IBM MQ operator v2.0.0 on your cluster, run the script.

    Warning: Please note that if you already have an existing MQ Operator on your cluster, this script may introduce errors. If you do not want to run the script, you can install the IBM MQ operator manually by running oc apply -f 04-openshift/resources/catalogsource.yaml and going into the OperatorHub in the OpenShift web console. Make sure you install version 2.0.0 or later.


    IBM MQ OpenShift operator

  2. To set an IBM_ENTITLEMENT_KEY environment variable, get your key from the IBM Container Library and run:

    export IBM_ENTITLEMENT_KEY=<your-ibm-entitlement-key>
  3. To deploy the queue manager on OpenShift, run the script. This script will configure the queue manager to use LDAP, AMS, trust the JMS app certificates and recognise Alice and Bob keys.


    MQ Queue Manager on OpenShift

The main resources being deployed to OpenShift are the following:

  • ibm-operator-catalog catalogsource: the IBM OpenShift operator catalogue where you can find the IBM MQ operator
  • ibm-mq subscription: the subscription to IBM MQ operator to install it onto your cluster
  • ibm-entitlement-key pull secret: IBM entitled registry key
  • mq-server-tls secret: to store your generated certificates
  • mq-ca-tls secret: to store your generated certificates
  • mq-app-route route: used to put and get messages
  • qmgr-setup config-map: defines the behaviour of the queue manager, including channels, queues, authentication, permissions and security
  • ams-qmgr queuemanager: requires a few other resources that will be deployed automatically, including a service, a service account, the route to the web console…

Detailed MQ setup on OpenShift

After running the scripts you will have the following MQ setup running on OpenShift:

  • IBM MQ Operator v2.0.0
  • AMSQMGR Queue Manager v9.3.0.0-r1
    • AMS.QLOCAL queue
    • AMS.SVRCONN channel
    • Web console enabled
    • Trust your JMS application (certificates)
    • Only allows Alice to write and encrypt messages (MQS key)
    • Only allows Bob to read and decrypt messages (MQS key)
    • Using LDAP for authentication:
      • mqwrite user (putter app) can:
        • Connect to the queue manager
        • Access the channel
        • Write to the queue (put messages)
      • mqread user (getter app) can:
        • Connect to the queue manager
        • Access the channel
        • Read from the queue (get messages)

JMS applications

Setup the JMS apps

Compile the JMS Putter and Getter applications.

In order to build the JMS application that can send and receive encrypted messages from the queue, through authenticating as Alice or Bob, follow the steps below.

JMS applications local setup

To start with, you will need to give all the information and credentials about your MQ instance to the apps. The simplest way to do so is to download a CCDT file locally from the MQ web console and make sure the apps are reading from it.

  1. Login to the MQ web console using the following commands. Please be aware that the web console takes some time to become available after deploying the queue manager.
    1. Get the url:

      oc get queuemanager ams-qmgr -n ams-mq -ojsonpath='{.status.adminUiUrl}'
    2. If prompted, select IBM provided credentials

      MQ web console login page 1

    3. Get the password for the admin username:

      oc -n ibm-common-services get secret platform-auth-idp-credentials -ojsonpath='{.data.admin_password}' | base64 --decode

      MQ web console login page 2

  2. Download the CCDT file for your MQ instance running on OpenShift

    1. From the homepage, go to Download connection files

      MQ web console homepage

    2. Select the following values:

      • Queue Manager: AMSQMGR
      • Channel: AMS.SVRCONN
      • Cipher: leave as default

      MQ web console CCDT page 1

    3. Leave Connections as default

      MQ web console CCDT page 2

    4. Download the CCDT file locally

      MQ web console CCDT page 3

  3. Update the path to your CCDT file in the file.

    # Absolute path to the CCDT file
    ccdt_location = <local-path-to-ccdt-file>
  4. To build the JMS client apps with Maven, run the script


Run the JMS apps

Send encrypted messages and receive decrypted messsages as authenticated users, using the JMS applications.

  1. Run the script to authenticate as Alice and write encrypted messages to the queue. The script will:

    • Update the path stored in the MQS_KEYSTORE_CONF environment variable to refer to Alice MQS folder (03-ams-keys/keys/alice/)
    • Run the putter app locally. The app puts a message containing a timestamp in the queue every 2 seconds.
  2. Run the script to authenticate as Bob and read decrypted messages from the queue. The script will:

    • Update the path stored in the MQS_KEYSTORE_CONF environment variable to refer to Bob MQS folder (03-ams-keys/keys/bob/)
    • Run the Getter app locally. The app gets all the messages from the queue.
    ./ and scripts running in different terminal windows

Since the messages are now encrypted, James the MQ Administrator will not be able to read them from the MQ Console or MQ CLI. He can see information about the queue such as the number of messages but not the messages themselves. You can check this feature by login in the MQ console (instructions listed in step 1).

MQ web console queue page not displaying encrypted messages