Chapter 4. Using AMQ Management Console

Procedure

1. Configure Red Hat Single Sign-On:

   1. Navigate to the realm in Red Hat Single Sign-On that you want to use for securing AMQ Management Console. Each realm in Red Hat Single Sign-On includes a client named Broker. This client is not related to AMQ.
   2. Create a new client in Red Hat Single Sign-On, for example artemis-console.

   3. Navigate to the client settings page and set:

      • Valid Redirect URIs to the AMQ Management Console URL followed by *, for example:

        https://broker.example.com:8161/console/*

      • Web Origins to the same value as Valid Redirect URIs. Red Hat Single Sign-On allows you enter +, indicating that allowed CORS origins includes the value for Valid Redirect URIs.
   4. Create a role for the client, for example guest.
   5. Make sure all users who require access to AMQ Management Console are assigned the above role, for example, using Red Hat Single Sign-On groups.

2. Configure the AMQ Broker instance:

   1. Add the following to your <broker-instance-dir>/instances/broker0/etc/login.config file to configure AMQ Management Console to use Red Hat Single Sign-On:

      console {
          org.keycloak.adapters.jaas.BearerTokenLoginModule required
              keycloak-config-file="${artemis.instance}/etc/keycloak-bearer-token.json"
              role-principal-class=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal
          ;
      };

      Adding this configuration sets up a JAAS principal and a requirement for a bearer token from Red Hat Single Sign-On. The connection to Red Hat Single Sign-On is defined in the keycloak-bearer-token.json file, as described in the next step.

   2. Create a file <broker-instance-dir>/etc/keycloak-bearer-token.json with the following contents to specify the connection to Red Hat Single Sign-On used for the bearer token exchange:

      {
        "realm": "<realm-name>",
        "resource": "<client-name>",
        "auth-server-url": "<RHSSO-URL>/auth",
        "principal-attribute": "preferred_username",
        "use-resource-role-mappings": true,
        "ssl-required": "external",
        "confidential-port": 0
      }

      <realm-name>

      the name of the realm in Red Hat Single Sign-On

      <client-name>

      the name of the client in Red Hat Single Sign-On

      <RHSSO-URL>

      the URL of Red Hat Single Sign-On

   3. Create a file <broker-instance-dir>/etc/keycloak-js-token.json with the following contents to specify the Red Hat Single Sign-On authentication endpoint:

      {
        "realm": "<realm-name>",
        "clientId": "<client-name>",
        "url": "<RHSSO-URL>/auth"
      }

   4. Configure the security settings by editing the the <broker-instance-dir>/etc/broker.xml file.

      For example, to allow users with the amq role consume messages and allow users with the guest role send messages, add the following:

               <security-setting match="Info">
                  <permission roles="amq" type="createDurableQueue"/>
                  <permission roles="amq" type="deleteDurableQueue"/>
                  <permission roles="amq" type="createNonDurableQueue"/>
                  <permission roles="amq" type="deleteNonDurableQueue"/>
                  <permission roles="guest" type="send"/>
                  <permission roles="amq" type="consume"/>
               </security-setting>

3. Run the AMQ Broker instance and validate AMQ Management Console configuration.

Procedure

1. Open the <broker_instance_dir>/etc/bootstrap.xml file.

2. In the <web> element, add the following attributes:

   <web path="web">
       <binding uri="https://0.0.0.0:8161" keyStorePath="<path_to_keystore>" keyStorePassword="<password>"
       clientAuth="<true/false>" trustStorePath="<path_to_truststore>" trustStorePassword="<password>">
       </binding>
   </web>

   bind

   For secure connections to the console, change the URI scheme to https.

   keyStorePath

   Path of the keystore file. For example:

   keyStorePath="<broker_instance_dir>/etc/keystore.jks"

   keyStorePassword

   Key store password. This password can be encrypted.

   clientAuth

   Specifies whether client authentication is required. The default value is false.

   trustStorePath

   Path of the trust store file. You need to define this attribute only if clientAuth is set to true.

   trustStorePassword

   Trust store password. This password can be encrypted.

Procedure

1. Obtain certificates for the broker and clients from a trusted certificate authority or generate self-signed certificates. If you want to generate self-signed certificates, complete the following steps:

   1. Generate a self-signed certificate for the broker.

      $ keytool -storetype pkcs12 -keystore broker-keystore.p12 -storepass securepass -keypass securepass -alias client -genkey -keyalg "RSA" -keysize 2048 -dname "CN=ActiveMQ Broker, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -ext bc=ca:false -ext eku=cA

   2. Export the certificate from the broker keystore, so that it can be shared with clients.

      $ keytool -storetype pkcs12 -keystore broker-keystore.p12 -storepass securepass -alias client -exportcert -rfc > broker.crt

   3. On the client, import the broker certificate into the client truststore.

      $ keytool -storetype pkcs12 -keystore client-truststore.p12 -storepass securepass -keypass securepass -importcert -alias client-ca -file broker.crt -noprompt

   4. On the client, generate a self-signed certificate for the client.

      $ keytool -storetype pkcs12 -keystore client-keystore.p12 -storepass securepass -keypass securepass -alias client -genkey -keyalg "RSA" -keysize 2048 -dname "CN=ActiveMQ Client, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -ext bc=ca:false -ext eku=cA

   5. Export the client certificate from the client keystore to a file so that it can be added to the broker truststore.

      $ keytool -storetype pkcs12 -keystore client-keystore.p12 -storepass securepass -alias client -exportcert -rfc > client.crt

   6. Import the client certificate into the broker truststore.

      $ keytool -storetype pkcs12 -keystore client-truststore.p12 -storepass securepass -keypass securepass -importcert -alias client-ca -file client.crt -noprompt

      Note

      On the broker machine, ensure that the keystore and truststore files are in a location that is accessible to the broker.

2. In the <broker_instance_dir>/etc/bootstrap.xml file, update the web configuration to enable the HTTPS protocol and client authentication for the broker console. For example:

   ...
   <web path="web">
       <binding uri="https://localhost:8161" keyStorePath="${artemis.instance}/etc/server-keystore.p12" keyStorePassword="password"
       clientAuth="true" trustStorePath="${artemis.instance}/etc/client-truststore.p12" trustStorePassword="password">
       ...
       </binding>
   </web>
   ...

   binding uri

   Specify the https protocol to enable SSL and add a host name and port.

   keystorePath

   The path to the keystore where the broker certificate is installed.

   keystorePassword

   The password of the keystore where the broker certificate is installed.

   ClientAuth

   Set to true to configure the broker to require that each client presents a certificate when a client tries to connect to the broker console.

   trustStorePath

   If clients are using self-signed certificates, specify the path to the truststore where client certificates are installed.

   trustStorePassword

   If clients are using self-signed certificates, specify the password of the truststore where client certificates are installed .

   NOTE. You need to configure the trustStorePath and trustStorePassword properties only if clients are using self-signed certificates.

3. Obtain the Subject Distinguished Names (DNs) from each client certificate so you can create a mapping between each client certificate and a broker user.

   1. Export each client certificate from the client’s keystore file into a temporary file. For example:

      keytool -export -file <file_name> -alias broker-localhost -keystore broker.ks -storepass <password>

   2. Print the contents of the exported certificate:

      keytool -printcert -file <file_name>

      The output is similar to that shown below:

      Owner: CN=AMQ Client, OU=Artemis, O=AMQ, L=AMQ, ST=AMQ, C=AMQ
      Issuer: CN=AMQ Client, OU=Artemis, O=AMQ, L=AMQ, ST=AMQ, C=AMQ
      Serial number: 51461f5d
      Valid from: Sun Apr 17 12:20:14 IST 2022 until: Sat Jul 16 12:20:14 IST 2022
      Certificate fingerprints:
      	 SHA1: EC:94:13:16:04:93:57:4F:FD:CA:AD:D8:32:68:A4:13:CC:EA:7A:67
      	 SHA256: 85:7F:D5:4A:69:80:3B:5B:86:27:99:A7:97:B8:E4:E8:7D:6F:D1:53:08:D8:7A:BA:A7:0A:7A:96:F3:6B:98:81

      The Owner entry is the Subject DN. The format used to enter the Subject DN depends on your platform. The string above could also be represented as;

      Owner: `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`

4. Enable certificate-based authentication for the broker’s console.

   1. Open the <broker_instance_dir>/etc/login.config configuration file. Add the certificate login module and reference the user and roles properties files. For example:

      activemq {
          org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
              debug=true
              org.apache.activemq.jaas.textfiledn.user="artemis-users.properties"
              org.apache.activemq.jaas.textfiledn.role="artemis-roles.properties";
      };

      org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule

      The implementation class.

      org.apache.activemq.jaas.textfiledn.user

      Specifies the location of the user properties file relative to the directory that contains the login configuration file.

      org.apache.activemq.jaas.textfiledn.role

      Specifies the properties file that maps users to defined roles for the login module implementation.

      Note

      If you change the default name of the certificate login module configuration in the <broker_instance_dir>/etc/login.config file, you must update the value of the -dhawtio.realm argument in the <broker_instance_dir>/etc/artemis.profile file to match the new name. The default name is activemq.

   2. Open the <broker_instance_dir>/etc/artemis-users.properties file. Create a mapping between client certificates and broker users by adding the Subject DNS that you obtained from each client certificate to a broker user. For example:

      user1=CN=user1,O=Progress,C=US
      user2=CN=user2,O=Progress,C=US

      In this example, the user1 broker user is mapped to the client certificate that has a Subject Distinguished Name of CN=user1,O=Progress,C=US Subject DN. After you create a mapping between a client certificate and a broker user, the broker can authenticate the user by using the certificate.

   3. Open the <broker_instance_dir>/etc/artemis-roles.properties file. Grant users permission to log in to the console by adding them to the role that is specified for the HAWTIO_ROLE variable in the <broker_instance_dir>/etc/artemis.profile file. The default value of the HAWTIO_ROLE variable is amq. For example:

      amq=user1, user2

5. Configure the following recommended security properties for the HTTPS protocol.

   1. Open the <broker_instance_dir>/etc/artemis.profile file.

   2. Set the hawtio.http.strictTransportSecurity property to allow only HTTPS requests to the AMQ Management Console and to convert any HTTP requests to HTTPS. For example:

      hawtio.http.strictTransportSecurity = max-age=31536000; includeSubDomains; preload

   3. Set the hawtio.http.publicKeyPins property to instruct the web browser to associate a specific cryptographic public key with the AMQ Management Console to decrease the risk of “man-in-the-middle” attacks using forged certificates. For example:

      hawtio.http.publicKeyPins = pin-sha256="..."; max-age=5184000; includeSubDomains

Procedure

1. Open the <broker_instance_dir>/etc/bootstrap.xml file.

2. In the <web> element, add the customizer attribute with a value of org.eclipse.jetty.server.ForwardedRequestCustomizer. For example:

   <web path="web" customizer="org.eclipse.jetty.server.ForwardedRequestCustomizer">
   ..
   </web>

3. Save the bootstrap.xml file.

4. Start or restart the broker by entering the following command:

   • On Linux: <broker_instance_dir>/bin/artemis run
   • On Windows: <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. In the left menu, click Artemis.

2. In the main pane, click the Broker diagram tab.

   The console displays a diagram of the cluster topology. This includes all brokers in the cluster and any addresses and queues on the local broker, as shown in the figure.

   Figure 4.3. Broker diagram tab

   
3. To change what items are displayed on the diagram, use the check boxes at the top of the diagram. Click Refresh.

4. To show attributes for the local broker or an address or queue that is connected to it, click that node in the diagram. For example, the following figure shows a diagram that also includes attributes for the local broker.

   Figure 4.4. Broker diagram tab, including attributes

   

Procedure

1. In the left menu, click Artemis.
2. In the folder tree, click acceptors.

3. To view details about how an acceptor is configured, click the acceptor.

   The console shows the corresponding attributes on the Attributes tab, as shown in the figure.

   Figure 4.5. AMQP acceptor attributes

   
4. To see complete details for an attribute, click the attribute. An additional window opens to show the details.