Connect to an AMQP 1.0 Broker

This topic describes how to configure the gateway to connect to an AMQP 1.0 Broker as a Generic JMS provider (for example, Apache ActiveMQ).
gateway92
This topic describes how to configure the 
CA API Gateway
to connect to an AMQP 1.0 Broker as a Generic JMS provider (for example, Apache ActiveMQ).
Contents:
Prerequisites
  • AMQP 1.0 Broker is configured (for the supported versions of Apache ActiveMQ, see Requirements and Compatibility)
  • Keystore and trust store files are generated and downloaded 
  • You have access to the Policy Manager
  • You have downloaded and decompressed the Qpid JMS (AMQP 1.0) client tarball file from https://qpid.apache.org/download.html
    The integration was tested using the
    apache-qpid-jms-0.20.0-bin.tar.gz
    file. Later versions of this file should be compatible, but are untested. Contact CA Support if you encounter issues.
    The following files are used in the configuration:
    geronimo-jms_2.0_spec-1.0-alpha-2.jar
    netty-buffer-4.1.6.Final.jar
    netty-codec-4.1.6.Final.jar
    netty-common-4.1.6.Final.jar
    netty-handler-4.1.6.Final.jar
    netty-transport-4.1.6.Final.jar
    proton-j-0.16.0.jar
    qpid-jms-client-0.20.0.jar
    qpid-jms-discovery-0.20.0.jar
    slf4j-api-1.7.22.jar
Not Supported
  • JMS Templates are not supported for JMS with AMQP 1.0 Broker. Reason: The JNDI URL is left empty in the JMS destination for AMQP 1.0.
  • The SSL configuration cannot be applied if you use a Hardware Security Module.
    Reason:
    You are not able to export private keys from the Gateway.
Step 1: Set Up the Gateway for AMQP 1.0 Broker
To set up the Gateway for AMQP 1.0 Broker:
  1. Stop the Gateway:
    # service ssg stop
  2. Copy all the .jar files under "Prerequisites" to the following location on the Gateway:
    /opt/SecureSpan/Gateway/runtime/lib/ext
  3. Set permission and ownership:
    # chmod 444 geronimo-jms_
    <version>
    .jar netty-*.jar proton-j-
    <version>
    .jar qpid-jms-client-
    <version>
    .jar qpid-jms-discovery-
    <version>
    .jar slf4j-api-
    <version>
    .jar
    # chown layer7:layer7 geronimo-jms_
    <version>
    .jar netty-*.jar proton-
    <version>
    .jar qpid-jms-client-
    <version>
    .jar qpid-jms-discovery-
    <version>
    .jar slf4j-api-
    <version>
    .jar
  4. Restart the Gateway:
    # service ssg start
Step 4: Register the JMS Destinations
The final step is to use the Policy Manager to register the JMS destinations.
To register a JMS destination:
  1. Click
    Add
    to create a new JMS Destination.
  2. Complete the JMS Destination Properties as follows:
    Field
    Entry
    [Basics] Tab
    Name
    Enter a name for the new JMS destination.
    Direction
    Select a direction.
    Provider Type
    Generic JMS
    [JNDI] Tab
    Initial Context Factory class name
    org.apache.qpid.jms.jndi.JmsInitialContextFactory
    JNDI URI
    Enter a single space character. This field is not used, but an entry is required to save or test the connections.
    Credentials are required to connect to JNDI
    Set as appropriate.
    Additional
    Properties
    To define a Connection Factory:
    Use the format:
     - Name:
    connectionfactory.
    <MyFactoryName>
     - Value: <URI>
    Example 1: Non-SSL URI:
    amqp://
    <message_broker>
    :5672
    Example 2: SSL URI:
    amqps://
    <message_broker>
    :5671?transport.trustStoreLocation=/opt/SecureSpan/Gateway/runtime/modules/conf/qpid/qpidclient-truststore.jks&transport.trustStorePassword=
    <password>
    Example 3: SSL Mutual URI:
    amqps://
    <message_broker>
    :5671?transport.keyStoreLocation=/opt/SecureSpan/Gateway/runtime/modules/conf/qpid/qpidclient-keystore.jks&transport.keyStorePassword=<password>&transport.trustStoreLocation=/opt/SecureSpan/Gateway/runtime/modules/conf/qpid/qpidclient-truststore.jks&transport.trustStorePassword=
    <password>
    To define a Queue:
    Use the format:
     - Name:
    queue.
    <MyQueue> - Value:
    <queueName>
    [Destination] Tab
    Destination Type
    Queue
    Connection Factory Name
    Enter the <MyFactoryName> value that is used to create a connection with the JMS provider. This name
    must
    match the Connection Factory name that is entered in the Additional Properties table in the [JNDI] tab.
    For example, if you enter
    "myFactoryLookup"
    here, there must be a corresponding
    "connectionfactory.myFactoryLookup"
    entry in the [JNDI] tab.
    Destination Name
    Enter the <MyQueue> value of the queue to use in the AMQP broker. This name
    must
    match what is entered in the Additional Properties table in the [JNDI] tab.
    For example, if you enter
    "myQueueLookup"
    here, there must be a corresponding
    "queue.myQueueLookup"
    entry in the [JNDI] tab.
    Credentials are required to connect to this Destination
    Set as appropriate.
    [Inbound Options] Tab:
    Set as appropriate.
    [Outbound Options] Tab:
    Set as appropriate.
  3. Click [
    Test Settings
    ] to validate your settings. The Gateway attempts to connect to the JMS destination and then displays the results.
  4. After a successful test, click [
    Save
    ] to register the JMS destination on the Gateway
Step 3: Configure SSL or Mutual Authentication on the Gateway
To configure SSL or mutual authentication on the Gateway:
  1. Create the following directory on the Gateway:
    /opt/SecureSpan/Gateway/runtime/modules/conf/qpid
  2. Set permission and ownership for the newly created directory:
    # chown layer7:layer7 /opt/SecureSpan/Gateway/runtime/modules/conf/qpid
    # chmod 755 /opt/SecureSpan/Gateway/runtime/modules/conf/qpid
  3. Copy client keystore and trustStore files (*.jks) to the directory created in step 2.
    Tip:
    The client keystore is required only for mutual authentication.
    1. The
      keystore
      should contain the client private key. To import the client private key to the client keystore, use this Java
      keytool
      command:
      # keytool -v -importkeystore -srckeystore client.p12 -srcstoretype PKCS12 -destkeystore qpidclient-keystore.jks -deststoretype JKS
    2. The trustStore should contain the broker server certificate. To import the broker certificate to the client trustStore, use this Java
      keytool
      command:
      # keytool -import -trustcacerts -alias "broker" -file broker.cer -keystore qpidclient-truststore.jks -deststoretype JKS
  4. Set permission and ownership for the copied files:
    # chown layer7:layer7 /opt/SecureSpan/Gateway/runtime/modules/conf/qpid/*.jks
    # chmod 644 /opt/SecureSpan/Gateway/runtime/modules/conf/qpid/*.jks
The configuration is now complete. The
CA API Gateway
can now connect to an AMQP 1.0 Broker as a Generic JMS provider.
Troubleshooting
Symptom
The Gateway displays errors similar to the following messages and fails to connect to the AMQP 1.0 Broker:
Failed to create connection to: amqps://<message_broker>:5671?transport.trustStoreLocation=client.ts&transport.trustStorePassword=<password>,caused by General SSLEngine problem, caused by General SSLEngine problem, caused by No name matching <message_broker> found 
Failed to create connection to: amqps://<message_broker>:5671?transport.trustStoreLocation=client.ts&transport.trustStorePassword=<password>,caused by General SSLEngine problem, caused by General SSLEngine problem, caused by No subject alternative names present
Possible Solutions
Solution #1:
Disable hostname verification by appending this string to the connection URL:
transport.verifyHost=false
Solution #2:
Ensure that the server certificate 'CN' matches the hostname in the connection URL.