Set up Red Hat AMQ 7 custom certificates on OpenShift

Secure communication over a computer network is one of the most important requirements for a system, and yet it can be difficult to set up correctly. This example shows how to set up Red Hat AMQ 7 end-to-end TLS encryption using a custom X.509 certificate on the Red Hat OpenShift platform.

Prerequisites

You need to have the following in place before you can proceed with this example:

• An OpenShift cluster up and running.
• A custom X.509 certificate in PEM format (along with its chain).
• An active Red Hat Customer Portal account.

The procedure

Before we start, let's define a few handy variables:

PROJECT="demo"
USER="developer"
BASEURL="https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/74-7.4.0.GA"

The first step is to log in and create a new project to host our broker:

oc login -u $USER -p x
oc new-project $PROJECT

Then, we need to create a dedicated ServiceAccount for deployment and add the view role:

echo '{"kind": "ServiceAccount", "apiVersion": "v1", "metadata": {"name": "amq-service-account"}}' | oc create -f -
oc policy add-role-to-user view system:serviceaccount:$PROJECT:amq-service-account

At this point, we should have all custom certificate files available. Most likely, this signed custom certificate came from the security team, along with its private key and the whole certificate's chain (all in PEM format).

The certificate files consist of the following:

• rootca.pem: The root Certificate Authority (CA) in our domain.
• interm.pem: An intermediate CA created to sign the certificate in a specific context.
• server.pem: The final server certificate, which can be issued for single or multiple domains (wildcard).
• server-prk.pem: The private key associated with our server's certificate.

Using these files, create a server KeyStore, convert it to Java KeyStore (JKS) format, and then trust the chain of certificates used to sign it:

cat interm.pem rootca.pem > chain.pem
cat server.pem chain.pem > bundle.pem
openssl pkcs12 -export -in bundle.pem -inkey server-prk.pem -out server.p12 -name server -CAfile chain.pem -passout pass:secret
keytool -importkeystore -alias server -srcstoretype PKCS12 -srckeystore server.p12 -srcstorepass secret -destkeystore server.jks -deststorepass secret 
keytool -import -noprompt -trustcacerts -alias chain -file chain.pem -keystore server.jks -storepass secret

When the server KeyStore is ready, it can be imported into a Secret that must also be added to the ServiceAccount created earlier:

oc create secret generic amq-app-secret --from-file=server.jks
oc secrets add sa/amq-service-account secret/amq-app-secret

In this example, we use the persistent AMQ 7 SSL template, because we usually want our messages to survive a broker shutdown. Let's create the image stream and download the broker's template:

oc login -u system:admin
oc replace --force -f $BASEURL/amq-broker-7-image-streams.yaml
curl -o broker.yaml $BASEURL/templates/amq-broker-74-persistence-ssl.yaml

To be able to download the broker's image from the Red Hat Container Registry, we also need to add an authentication Secret and link it to the default ServiceAccount:

oc create secret docker-registry registry-auth \
    --docker-server=registry.redhat.io \
    --docker-username=<portal-username> \
    --docker-password=<portal-password>
oc secrets link default registry-auth --for=pull

The next step is to deploy the broker using the downloaded template and pass our KeyStore as a parameter:

oc login -u $USER -p x
oc process -f broker.yaml \
    -p APPLICATION_NAME=$PROJECT \
    -p AMQ_USER=admin \
    -p AMQ_PASSWORD=admin \
    -p AMQ_TRUSTSTORE=server.jks \
    -p AMQ_TRUSTSTORE_PASSWORD=secret \
    -p AMQ_KEYSTORE=server.jks \
    -p AMQ_KEYSTORE_PASSWORD=secret \
    | oc create -f -

We are almost finished. The last step is to create a service and a passthrough route to expose the desired port to the external world. Here we are exposing the AMQP port, but you can do the same with the other available protocols:

oc create -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  labels:
    application: $PROJECT-amq
  name: broker-amq-amqp-ssl
spec:
  ports:
    - port: 5671
      targetPort: 5671
  selector:
    statefulset.kubernetes.io/pod-name: $PROJECT-amq-0
EOF
oc create route passthrough --service=broker-amq-amqp-ssl

Java client setup

You can use your preferred JMS library to build your client, but you will certainly need a truststore in JKS format for one-way TLS authentication:

keytool -import -noprompt -file server.pem -alias server -keystore truststore.jks -storepass secret

If you want to access the broker from outside OpenShift, then you also need to use a ConnectionFactory URL similar to this one:

amqps://broker-amq-amqp-ssl-demo.192.168.64.53.nip.io:443?transport.verifyHost=false&transport.trustStoreLocation=src/main/resources/truststore.jks&transport.trustStorePassword=secret

Additional notes

You must bind the hostname you are using in the certificate's CN field to the cluster's HAProxy IP address in your DNS server. If you are using a homemade CA, then you also need to trust the chain on the client machine to access the Hawtio web console.