1. Download IMB-5.5.1.zip from the Edge Security area of ForgeRock BackStage download site .

2. Copy (or move) and unzip the file to the installation directory:

   $ mkdir /IMB
   $ unzip ~/Downloads/IMB-5.5.1.zip -d /IMB

   The following files and directories are extracted in /IMB/imb-microservice:

   • /bin/startup.sh, to start the IMB.

   • /conf/boot/boot.properties, to configure port numbers and keys for starting the IMB.

   • /conf/logging.properties, to configure logging levels for messages to the console and file. By default, messages are logged to console at the level INFO, and to file at the level ALL.

   • /logs, the default location for log files.

   • /examples/imb_mqtt_server-default.json, the MQTT server configuration file. For more information and an example file, see Section 2.3.1, "Configuration File for MQTT Server".

     If you plan to use MQTTS for the MQTT server connection, this file must contain parameters to require SSL, and to define the path to the keystore file. For an example file, see Example 4.1, "Example Configuration Requiring MQTTS for the MQTT Server Connection".

   • /examples/imb_capture.json, to configure a print to logs for authorized messages to the IMB. For more information and an example file, see Section 2.3.2, "Configuration File for Capture".

   • /amster, to provide the AM configuration used in Appendix A, "Setting Up AM Manually for the Examples". Instead of configuring AM manually you can import the configuration through Amster, as described in that section.

Before you start, download and install the IMB as described in Section 2.2, "Downloading and Installing the IMB". The example commands are run from the installation directory /IMB/imb-microservice.

1. Run the script to start the IMB:

   $ bin/startup.sh
   INFO    | com.forgerock.imb.osgi.VertxServiceComponent | Vert.x successfully registered
   -> Service ready

   A message indicates that the microservices framework is ready.

   The bootstrap process tries to activate the IMB components by going through all of the .json files in the /conf directory. If no imb_mqtt_server-****.json is present, the IMB MQTT Server component isn't activated.

2. If you intend to run the examples, go directly to Appendix A, "Setting Up AM Manually for the Examples". Otherwise, perform this step.

   Add the MQTT server configuration file called imb_mqtt_server-default.json to the /conf directory. For an example file, see Section 2.3.1, "Configuration File for MQTT Server".

   The IMB takes a few seconds to update its configuration automatically, and displays the following message:

   INFO | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server is listening on localhost:1883

Before you start, make sure that you have completed all of the tasks in Section 3.1, "Preparing for the Examples".

1. In a terminal window for IMB, start the IMB:

   $ /IMB/imb-microservice/bin/startup.sh
   INFO    | com.forgerock.imb.osgi.VertxServiceComponent | Vert.x successfully registered
   -> Service ready

2. Include the configuration to set up the connections to the IMB:

   1. Copy /examples/imb_mqtt_server-default.json to the /conf directory:

      {
        "config" : {
          "mqtt" : {
            "host" : "0.0.0.0",
            "port" : 1883
          },
          "security" : {
            "openam-uri" : "http://openam.example.com:8088/openam",
            "policy-set" : "things",
            "operator" : {
              "username" : "imb_oidc_client",
              "password" : "password",
              "realm" : "/"
            }
          }
        }
      }

      For information about the file, see Section 2.3.1, "Configuration File for MQTT Server".

   2. Check the IMB terminal for an updated message like this:

      INFO | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server is listening on 0.0.0.0:1883

3. Publish a message anonymously:

   1. In a terminal for device-1, run the following command:

      $ mosquitto_pub -h localhost -p 1883 -t "/device-1/messages" -m "1266193804 32" -d

      device-1 tries to connect to the IMB without providing credentials.

   2. Check the device-1 terminal for a message to confirm that the connection was refused:

      Client mosqpub/...- sending CONNECT
      Client mosqpub/...- received CONNACK
      Connection Refused: bad user name or password.
      Error: The connection was refused.

4. Publish a message with credentials:

   1. Run the following command, replacing <id_token-device-1> and <access_token-device-1> with the values returned in Section 3.1.2, "Getting ID Tokens":

      $ mosquitto_pub -h localhost -p 1883 -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d

   2. Check the device-1 terminal for a message to confirm that the that the IMB accepted the connection:

      Client mosqpub/...- sending CONNECT
      Client mosqpub/...- received CONNACK
      Client mosqpub/...- sending PUBLISH (d0, q0, r0, m1, '/device-1/messages', ... (10 bytes))
      Client mosqpub/...- sending DISCONNECT

Before you start, work through Section 3.2, "Validating a Token for Connect".

1. Include configuration to capture messages coming into the IMB:

   1. Copy /examples/imb_capture.json to the /conf directory.

      The file contains the following configuration to capture messages coming into the Identity Message Broker:

      {}

      For information about the file, see Section 2.3.2, "Configuration File for Capture".

   2. Check the IMB terminal for a message to confirm that the configuration has been updated:

      INFO | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server is listening on 0.0.0.0:1883
      INFO | com.forgerock.imb.client.text.TextualClientVerticle | Textual Client started>

2. Publish a message with authentication, but to an unauthorized topic:

   1. In the device-1 terminal, run the following command, to publish a message to /temperature, replacing <id_token-device-1> and <access_token-device-1> with the values returned in Section 3.1.2, "Getting ID Tokens":

      $ mosquitto_pub -h localhost -p 1883 -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/temperature" -m "1266193804 32" -d
      Client mosqpub/...- sending CONNECT
      Client mosqpub/...- received CONNACK
      Client mosqpub/...- sending PUBLISH (d0, q0, r0, m1, '/temperature', ...)
      Client mosqpub/...- sending DISCONNECT

      Although an AM policy authorizes device-1 to publish on /device-1/messages there is no policy to authorize it to publish on /temperature.

   2. In the IMB terminal, check that there is no message to indicate that the IMB accepted the publish.

   3. View the IMB logs for a message that the publish was not allowed.

3. Publish a message with authentication, but to an authorized topic:

   1. Run the following command to publish a message to /device-1/messages:

      $ mosquitto_pub -h localhost -p 1883 -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
      Client mosqpub/...- sending CONNECT
      Client mosqpub/...- received CONNACK
      Client mosqpub/...- sending PUBLISH (d0, q0, r0, m1, '/device-1/messages', ... (10 bytes))
      Client mosqpub/...- sending DISCONNECT

   2. In the IMB terminal, check that there is a message to indicate that the IMB received the publish message from device-1, and the capture component was able to display it:

      Message received on /device-1/messages
      * issuer: device-1

Before you start, work through Section 3.3, "Authorizing on Publish".

1. In a terminal window, run the following command to introspect the access_token for device-1:

   $ http POST openam.example.com:8088/openam/oauth2/realms/root/introspect client_id==imb_oidc_client client_secret==password token==<access_token-device-1>
   HTTP/1.1 200 OK
   ...
   {
     "active": true,
     "client_id": "oidc_client",
     "exp": 1505386947,
     "iss": "http://openam.example.com:8088/openam/oauth2",
     "scope": "openid",
     "sub": "device-1",
     "token_type": "access_token",
     "user_id": "device-1"
   }

   Note that the token is active.

2. Publish a message from device-1:

   1. In a terminal for device-1 publish a message to /device-1/messages:

      $ mosquitto_pub -h localhost -p 1883 -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
      Client mosqpub/...- sending CONNECT
      Client mosqpub/...- received CONNACK
      Client mosqpub/...- sending PUBLISH (d0, q0, r0, m1, '/device-1/messages', ... (10 bytes))
      Client mosqpub/...- sending DISCONNECT

   2. In the IMB terminal, check that the IMB received the message:

      Message received on /device-1/messages
      * issuer: device-1

3. Revoke the access_token for device-1:

   1. In a terminal window, run the following command to revoke the access_token:

      $ http POST openam.example.com:8088/openam/oauth2/token/revoke client_id==oidc_client client_secret==password token==<access_token-device-1>
      HTTP/1.1 200 OK
      ...
      {}

   2. Introspect the token to check that it is revoked:

      $ http POST openam.example.com:8088/openam/oauth2/realms/root/introspect client_id==imb_oidc_client client_secret==password token==<access_token-device-1>
      HTTP/1.1 200 OK
      ...
      {
        "active": false
      }

      Note that the token is not active.

4. Try to publish a message from device-1:

   1. In a terminal for device-1 publish a message to /device-1/messages:

      $ mosquitto_pub -h localhost -p 1883 -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
              Client mosqpub|... sending CONNECT
      Client mosqpub|... received CONNACK
      Connection Refused: bad user name or password.
      Error: The connection was refused.

   2. In the IMB terminal, check for an error message:

      | SEVERE  | com.forgerock.imb.mqtt.server.MqttServerVerticle | An error occurred while resolving the access_token

      The log files include other notifications that the connection was rejected.

5. If you set up AM using Amster, consider using device-2 to test the policies. For example:

   • Check that device-2 does not receive messages on the topic /device-1/messages.

   • Check that when cloud-app publishes a message to /device-1/actions, device-2 does not receive it.

Before you start, complete the setup and examples in Chapter 3, "Running MQTT Publish and Receive".

1. In AM, make sure that the policies include resources for the MQTTS port number:

   • If you configured AM with the provided Amster files, the policies are configured.

   • If you configured AM manually, see Section A.4, "Configuring a Policy Set and Policies" to make sure that the default-mqtt-server policy contains the resource mqtt+server://*:8883.

2. Generate a keystore using the Java keytool, replacing where necessary the example values with your own values:

   1. Generate an SSL key pair and keystore:

      $ keytool \
      -genkeypair \
      -alias imb \
      -keyalg rsa \
      -keystore /path/to/server_keystore.jks \
      -storepass password \
      -keypass password \
      -dname "CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown"

      Note

      Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.

      A file /path/to/server_keystore.jks is created.

   2. Export the public certificate from the keystore:

      $ keytool \
      -exportcert \
      -alias imb \
      -keystore /path/to/server_keystore.jks \
      -keypass password \
      -rfc \
      -file server_cert.pem
      Enter keystore password: password
      Certificate stored in file <server_cert.pem>

      A file /path/to/server_cert.pem is created. MQTT clients must use this certificate to connect to the IMB.

3. Update the configuration file imb_mqtt_server-default.json to require SSL, and to set the SSL endpoint and path to the keystore file. Use the following file as an example:

   Example 4.1. Example Configuration Requiring MQTTS for the MQTT Server Connection

   {
     "config" : {
       "mqtt" : {
         "host" : "0.0.0.0",
         "port" : 8883,
         "ssl" : true,
         "keyStoreOptions" : {
           "path" : "/path/to/server_keystore.jks",
           "password" : "password"
         }
       },
       "security" : {
         "openam-uri" : "http://openam.example.com:8088/openam",
         "policy-set" : "things",
         "operator" : {
           "username" : "imb_oidc_client",
           "password" : "password",
           "realm" : "/"
         }
       },
       "authentication-check-interval" : 15000
     }
   }

   
   

   The message on the IMB terminal should confirm that it is listening on the secure port 8883:

   INFO | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server is listening on 0.0.0.0:8883

   Compared to Section 2.3.1, "Configuration File for MQTT Server", this file uses a different port number, includes the ssl boolean, and defines the path and password for the keystore file.

1. In the device-1 terminal, run the following command to publish a message without using the certificate file server_cert.pem to secure the connection:

   $ mosquitto_pub -h localhost -p 8883 -u "OIDC token" -P "<id_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
   Client mosqpub/... sending CONNECT
   Error: The connection was lost.

   The message on the IMB terminal should confirm that the client failed to connect over SSL:

   Client from origin /... failed to connect over ssl:...

2. Now run the following command, using the certificate file server_cert.pem to secure the connection:

   $ mosquitto_pub -h localhost -p 8883 --cafile /path/to/server_cert.pem --insecure -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
   Client mosqpub/... sending CONNECT
   Client mosqpub/... received CONNACK
   Client mosqpub/... sending PUBLISH (d0, q0, r0, m1, '/device-1/messages', ... (13 bytes))
   Client mosqpub/... sending DISCONNECT 

   The message on the IMB terminal should confirm that it received the message over the secure port:

   Message received on /device-1/messages
   * issuer: device-1

Before you start, complete the steps in Procedure 4.1, "To Set up MQTTS for an MQTT Server Connection".

1. Generate a keystore for the MQTT client, device-1:

   1. Generate a keystore and keypair:

      $ keytool \
      -genkeypair \
      -alias imb \
      -keyalg rsa \
      -keystore /path/to/client_keystore.jks \
      -storepass password \
      -keypass password \
      -dname "CN=device-1, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown"

      Note

      Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.

      A file /path/to/client_keystore.jks is created.

   2. Export the keystore to PKCS12 format:

      $ keytool \
      -importkeystore \
      -srckeystore client_keystore.jks \
      -destkeystore client_keystore.p12 \
      -deststoretype PKCS12
      
      Enter destination keystore password: password
      Re-enter new password:  password
      Enter source keystore password:  password
      Entry for alias imb successfully imported.
      Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

      The files client_keystore.jks and client_keystore.p12 are created.

   3. Convert the PKCS12 file containing the private key and certificates to PEM, and output the client certificate:

      $ openssl pkcs12 -in client_keystore.p12 -nokeys -out client_cert.pem
      Enter Import Password: password
      MAC verified OK

      The file client_cert.pem is created.

   4. Convert the PKCS12 file containing the private key and certificates to PEM, and output the client private key:

      $ openssl pkcs12 -in client_keystore.p12 -nodes -nocerts -out client_key.pem
      Enter Import Password: password
      MAC verified OK

      The file client_key.pem is created.

2. Import the client certificate into the server's trust store:

   keytool -importcert -file client_cert.pem -keystore /path/to/server_truststore.jks -alias "device-1"
   Enter keystore password: password
   Re-enter new password:  password
   Owner: CN=device-1, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
   Issuer: CN=device-1, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
   
   ...
   
   Trust this certificate? [no]:yes
   Certificate was added to keystore

   The file server_truststore.jks is created.

3. Update the configuration file imb_mqtt_server-default.json to require MQTT clients to authenticate to the IMB, and to set the path and password for the truststore. Use the following file as an example:

   Example 4.2. Example Configuration Requiring MQTT Clients to Authenticate

   {
     "config" : {
       "mqtt" : {
         "host" : "0.0.0.0",
         "port" : 8883,
         "ssl" : true,
         "keyStoreOptions" : {
           "path" : "/path/to/server_keystore.jks",
           "password" : "password"
         },
         "clientAuthRequired" : true,
         "trustStoreOptions" : {
           "path" : "/path/to/server_truststore.jks",
           "password" : "password"
         }
       },
       "security" : {
         "openam-uri" : "http://openam.example.com:8088/openam",
         "policy-set" : "things",
         "operator" : {
           "username" : "imb_oidc_client",
           "password" : "password",
           "realm" : "/"
         }
       },
       "authentication-check-interval" : 15000
     }
   }

   
   

   Compared to Example 4.1, "Example Configuration Requiring MQTTS for the MQTT Server Connection", this file includes the client authentication boolean, and the path and password for the truststore.

   The message on the IMB terminal should confirm that the configuration is updated:

   INFO    | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server [0.0.0.0:8883] stopped
   INFO    | com.forgerock.imb.mqtt.server.MqttServerVerticle | MQTT Server is listening on 0.0.0.0:8883

1. In the device-1 terminal, run the following command to publish a message without providing a client certificate to authenticate the MQTT client:

   $ mosquitto_pub -h localhost -p 8883 --cafile /path/to/server_cert.pem --insecure -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
   Client mosqpub/... sending CONNECT
   Error: The connection was lost.

   The message on the IMB terminal should confirm that the client failed to connect over SSL:

   Client from origin /... failed to connect over ssl:...

2. Now run the following command that provides a client certificate to authenticate the MQTT client:

   $ mosquitto_pub -h localhost -p 8883 --cafile /path/to/server_cert.pem --insecure --cert /path/to/client_server_cert.pem --key /path/to/client_key.pem -u "<id_token-device-1>" -P "<access_token-device-1>" -t "/device-1/messages" -m "1266193804 32" -d
   
   Client mosqpub/... sending CONNECT
   Client mosqpub/... received CONNACK
   Client mosqpub/... sending PUBLISH (d0, q0, r0, m1, '/device-1/messages', ... (13 bytes))
   Client mosqpub/... sending DISCONNECT

   The message on the IMB terminal should confirm that it received the message:

   Message received on /device-1/messages
   * issuer: device-1