Page Comparison

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).

...

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.

...

<mqtt enabled="true">
	<port>1883</port>
	<sslPort>8883</sslPort> <!-- put proper default ssl port -->
    <inboundBufferSize>32768</inboundBufferSize>
    <deliveryBufferSize>32768</deliveryBufferSize>
    <security>
             <authentication>OPTIONAL</authentication>
             <authenticator>org.wso2.carbon.andes.authentication.andes.CarbonBasedMQTTAuthenticator</authenticator>
    </security>
</<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.

...

<mqtt enabled="true">
	................
	<sslConnection enabled="true" port="8883">
    	<keyStore>
        	<location>repository/resources/security/wso2carbon.jks</location>
            <password>wso2carbon</password>
            <certType>SunX509</certType>
    	</keyStore>
        <trustStore>
            <location>repository/resources/security/client-truststore.jks</location>
            <password>wso2carbon</password>
            <certType>SunX509</certType>
        </trustStore>
    </sslConnection>
    ............
</mqtt>

Related Parameters

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

...

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.

  Code Block
  language xml
  <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.

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