Configuring Transports for WSO2 MB

WSO2 Message Broker (WSO2 MB) uses two transport protocols for the purpose of brokering messages between publishers and subscribers. These protocols are the Advanced Message Queueing Protocol (AMQP) and the Message Queueing and Telemetry Transport (MQTT).

The following topics explain how these protocols are enabled and configured for WSO2 MB:

Advanced Message Queuing Protocol (AMQP)

The Advance Message Queueing Protocol (AMQP) is a wire-level messaging protocol used by WSO2 MB for message queueing. The <MB_HOME>/repository/conf/broker.xml file contains parameters related to configuring the AMQP transport.

Enabling the transport

The transport is enabled by default, as shown in the following extract of the broker.xml file:

<amqp enabled="true">
	<defaultConnection enabled="true" port="5672" />
</amqp>

As shown above, if the value of this parameter is true, the AMQP transport is enabled and the AMQP protocol will be applied to messages sent to the specified listening port. The default listening port specified for the AMQP transport is 5672. That is, the AMQP broker will be initialized with this port by default.

Configuring the SSL connection

You can configure a SSL connection for the AMQP transport using the <sslConnection> element in the broker.xml file. See Enabling SSL Support in the Broker for information.

Related Parameters

Once you have enabled the AMQP transport, you can update the following related parameters as required.

<amqp enabled="true">
	............
    <maximumRedeliveryAttempts>10</maximumRedeliveryAttempts>
    <allowSharedTopicSubscriptions>false</allowSharedTopicSubscriptions>
    <allowStrictNameValidation>true</allowStrictNameValidation>
	............
</amqp>

Parameter Name	Description	Default Value
maximumRedeliveryAttempts	The maximum number of times WSO2 MB should attempt to redeliver a message that has not reached a subscriber. For example, when this value is set to 10, another 10 attempts will be made to deliver the message. The default value can be changed depending on your reliability requirements. Read more about message redelivery.	10
allowSharedTopicSubscriptions	If this parameter is `true`, a durable subscription to a topic can be shared among multiple subscribers. That is, multiple clients can subscribe to a topic in WSO2 MB using the same client ID. Read more about durable subscriptions to topics.	false
allowStrictNameValidation	If this parameter is true, the queue names and topic names will be validated according to the AMQP specification. When this parameter is set to `false`, it is possible to use ":" in topic names. Read more about this in 'Adding topics from management console'.	true

Refer the description of the broker.xml file for further details.

Message Queueing and Telemetry Transport

The Message Queueing and Telemetry Transport (MQTT) is a lightweight, broker-based publish/subscribe messaging protocol, which enables an extremely lightweight publish/subscribe messaging model. WSO2 MB 3.0.0 and later versions fully support MQTT version 3.1.0, and partially supports version 3.1.1.

The MQTT protocol allows a message to be sent to a topic based on three levels of QoS (Quality of Service) as explained below.

QoS 1 - At Most One - At this level, messages are delivered to subscribers in the most efficient manner. A message is dispatched only once.

QoS 2 - At Least One - At this level, the system will ensure that a message is received by the subscriber at least once. The level of delivery is assured through acknowledged delivery.

QoS 3 - Exactly Once - At this level, the message is delivered only once to its subscriber. This level is also defined as Assured Delivery.

Enabling the transport

The <MB_HOME>/repository/conf/broker.xml file contains parameters related to configuring the MQTT transport. The transport can be enabled as shown in the following extract of the broker.xml file.

<mqtt enabled="true">
	<defaultConnection enabled="true" port="1883" />
	.......
</mqtt>

If the value for this parameter is true, the MQTT transport is enabled and the MQTT protocol will be applied to messages that are sent to the specified listening port. The listening port for the MQTT transport is 1883. The MQTT broker will be initialized with the specified port by default. This value would be incremented based on the offset specified in the carbon.xml.

Configuring the SSL connection

You can configure the secure SSL connection for the MQTT transport using the <sslConnection> element in the broker.xml file. See Enabling SSL Support in the Broker for information.

Configuring authentication and authorization

Authentication and authorization of the MQTT connection can be configured using the following settings in the broker.xml file.

<mqtt enabled="true">
	..............
    <security>
             <authentication>OPTIONAL</authentication>
             <authenticator>org.wso2.carbon.andes.authentication.andes.CarbonBasedMQTTAuthenticator</authenticator>
			 <!--authenticator class="org.wso2.carbon.andes.authentication.andes.OAuth2BasedMQTTAuthenticator">
                <property name="hostURL">https://localhost:9443/services/OAuth2TokenValidationService</property>
				<property name="username">admin</property>
				<property name="password">admin</property>
				<property name="maxConnectionsPerHost">10</property>
				<property name="maxTotalConnections">150</property>
			</authenticator-->
			<authorization>NOT_REQUIRED</authorization>
			<authorizer class="org.wso2.carbon.andes.authorization.andes.CarbonPermissionBasedMQTTAuthorizer">
				<property name="connectionPermission">/permission/admin/mqtt/connect</property>
			</authorizer>
    </security>
</mqtt>

The <authentication> element instructs the MQTT server whether clients should always send credentials when establishing a connection. Possible values are as follows:

OPTIONAL	This is the default value. If an MQTT client sends credentials, the server will validate them. If the client does not send credentials, the server will allow the client to establish the connection without authentication. This behavior adheres to MQTT 3.1 specification.
REQUIRED	If the MQTT client doesn't send credentials or if the credentials are invalid, the server will reject the connection.

The <authenticator> element specifies the class that is implemented. By default the org.wso2.carbon.andes.authentication.andes.CarbonBasedMQTTAuthenticator class is enabled, which authenticates the user's credentials against the carbon user store.

If required, you can disable the default authenticator and enable the org.wso2.carbon.andes.authentication.andes.OAuth2BasedMQTTAuthenticator authenticator class as shown below. This enables OAuth-based authentication and authorization for MQTT.

<mqtt enabled="true">
	..............
    <security>
             .........
			 <authenticator class="org.wso2.carbon.andes.authentication.andes.OAuth2BasedMQTTAuthenticator">
                <property name="hostURL">https://localhost:9443/services/OAuth2TokenValidationService</property>
				<property name="username">admin</property>
				<property name="password">admin</property>
				<property name="maxConnectionsPerHost">10</property>
				<property name="maxTotalConnections">150</property>
			</authenticator>
			......
    </security>
</mqtt>

The <authorization> element instructs the MQTT server whether clients should be authorized before either publishing or subscribing. Possible values are as follows:

NOT_REQUIRED	This is the default value. The MQTT will skip the authorization check.
REQUIRED	The MQTT clients will be authorized before publishing mesages. This will execute the class given in the authorizer element. Note that the `<authentication>` element should be set to REQUIRED for authorization to be REQUIRED.

The <authorizer> element specifies the permissions required by a user to connect to the broker. This is applicable if the <authorization> element is set to REQUIRED.

<mqtt enabled="true">
	..............
    <security>
             ........
			<authorizer class="org.wso2.carbon.andes.authorization.andes.CarbonPermissionBasedMQTTAuthorizer">
				<property name="connectionPermission">/permission/admin/mqtt/connect</property>
			</authorizer>
    </security>
</mqtt>