Christoph Walcher

20. März 2020

5 Min.

MQTT meets Web - Anbindung von Webapps über MQTT

Da ein MQTT-Broker in vielen IoT-Projekten als zentrale Anlaufstelle für Zustandsinformationen sämtlicher Geräte gilt, möchten wir diesen verwenden um sämtliche Daten direkt in einer Webapp darzustellen, jedoch ohne, dass Sicherheitsaspekte unberücksichtigt bleiben.

Motivation

Das IoT-Messaging Protokoll MQTT erfreut sich in letzter Zeit immer mehr Beliebtheit, vor allem wenn es um die Anbindung und Vernetzung von IoT-Geräten geht. MQTT arbeitet dabei nach dem Publish/Subscribe-Prinzip. Dies bedeutet, dass Clients, welche sich für Nachrichten zu einem bestimmtem Thema interessieren, sich beim MQTT-Broker auf das jeweilige Topic registrieren (subscribe). Sollte daraufhin ein anderer Client eine Nachricht zu diesem Topic an den Broker senden (publish), leitet der Broker diese an die Clients weiter, welche sich zuvor auf das Topic registriert haben.

Icons: ©Fontawesome

Da ein MQTT-Broker in vielen IoT-Projekten als zentrale Anlaufstelle für Zustandsinformationen sämtlicher Geräte gilt, wäre es praktisch diese auch direkt aus dem Broker heraus in einer Webapp darstellen zu können. Jedoch darf dies auf keinen Fall ohne die notwendigen Schutzmechanismen geschehen.

Übersicht

In unserem Fall benutzen wir HiveMQ als zentralen MQTT-Broker. An diesem ist zum einen ein Client verbunden, welcher ein Gerät simulieren soll und zum anderen die mittels Angular umgesetzte Webapp. Als Identityprovider/Authentifizierungsserver kommt zusätzlich noch Keycloak zum Einsatz. Keycloak stellt der Webapp, ein Token (JWT) zur Verfügung, falls die Authentifizierung des Benutzers erfolgreich war. Daraufhin kann die Webapp, dieses Token dazu verwenden, sich gegenüber dem Broker zu authentifizieren. Dieser Vorgang läuft dabei nach dem OpenID-Connect Standard ab. In einem größeren System, kann dieser Identityprovider natürlich auch für weitere Dienste verwendet werden.

Das ganze Projekt haben wir auf GitHub veröffentlicht und schauen uns deshalb nur die wichtigsten Stellen an.

Keycloak

Beginnen wir mit Keycloak, unserem Identityprovider. Für dessen Einrichtung sind folgende Schritte nötig, um die Clients und Benutzer anzulegen:

Aufruf des Adminpanels, bei unserem Container: http://localhost:8083/auth/admin/ Benutzername: admin, Passwort: Pa55w0rd
Anlegen des Clients für den Broker: Links im Menu: Clients -> Create -> Client ID: hivemq -> Save -> Access Type: confidential, Standard Flow Enabled: off -> Save -> Credentials -> Secret wird später benötigt.
Anlegen des Clients für die Webapp: Links im Menu: Clients -> Create -> Client ID: frontend -> Save -> Implicit Flow Enabled: on, Standard Flow Enabled: off, Valid Redirect URIs: http://localhost:8080/* (die Url, auf welcher die Webapp erreichbar ist) -> Save
Anlegen extra Benutzer: Links im Menü: Users -> Add User

HiveMQ

Wir haben uns für HiveMQ als MQTT-Broker entschieden, weil er in großen Anwendungen nahezu linear im Cluster skaliert. Außerdem bietet er die Enterprise-Security-Extension an, die uns dabei hilft, Clients über ihre mit übermittelten Token bzw. OpenID-Connect zu authentifizieren.

Den Broker müssen wir so einrichten, dass er auch auf MQTT-Nachrichten über WebSockets lauscht. Dafür haben wir in die config.xml folgenden Block eingefügt:

<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="hivemq-config.xsd">
  <listeners>
    ...
    <websocket-listener>
      <port>8081</port>
      <bind-address>0.0.0.0</bind-address>
      <path>/mqtt</path>
      <name>websocket-frontend</name>
      <subprotocols>
        <subprotocol>mqttv3.1</subprotocol>
        <subprotocol>mqtt</subprotocol>
      </subprotocols>
      <allow-extensions>true</allow-extensions>
    </websocket-listener>
  </listeners>
  ...
</hivemq>

<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="hivemq-config.xsd">

...

<websocket-listener>

<bind-address>0.0.0.0</bind-address>

<name>websocket-frontend</name>

<subprotocol>mqttv3.1</subprotocol>

</subprotocols>

<allow-extensions>true</allow-extensions>

</websocket-listener>

</listeners>

...

</hivemq>

Die Authentifikation über OpenID-Connect/JWTs übernimmt bei HiveMQ die Enterprise-Security-Extension. Sie musste noch dementsprechend konfiguriert werden, um die Tokens über unseren Keycloak zu authentifizieren. Über den JWKS-Endpoint erhält der Broker das Zertifikat um das Token lokal zu überprüfen. Der Introspection-Endpoint dient als zusätzliche Sicherheitsstufe. An diesen Endpoint wird beim Verbindungsaufbau eines MQTT-Client das jeweilige Token gesendet, um es zusätzlich zu überprüfen. Dieser Schritt ist jedoch nur optional.

<enterprise-security-extension
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="enterprise-security-extension.xsd">
  <realms>
    <jwt-realm>
      <name>master</name>
      <enabled>true</enabled>
      <configuration>
        <jwks-endpoint>http://keycloak:8083/auth/realms/master/protocol/openid-connect/certs</jwks-endpoint>
        <introspection-endpoint>http://keycloak:8083/auth/realms/master/protocol/openid-connect/token/introspect</introspection-endpoint>
        <simple-auth>
          <username>hivemq</username>
          <password> -- Secret aus Keycloak von vorher -- </password>
        </simple-auth>
      </configuration>
    </jwt-realm>
  </realms>
  <pipelines>
    <listener-pipeline name="keycloak-pipeline" listener="ALL">
      <jwt-authentication-manager>
        <realm>master</realm>
        <jwt-validation>
          <enable-introspection>true</enable-introspection>
          <reserved-claims>
            <sub>${mqtt-username}</sub> <!-- Der MQTT-Benutzername muss mit dem JWT-Subject übereinstimmen. -->
          </reserved-claims>
        </jwt-validation>
      </jwt-authentication-manager>
      <allow-all-authorization-manager/> <!-- Wir prüfen die Berechtigungen nicht tiefer, wer ein valides Token besitzt, darf alles tun. 
        Alternativ sql-authentication-manager, dieser bezieht die Berechtigungen aus DB -->
    </listener-pipeline>
  </pipelines>
</enterprise-security-extension>

<enterprise-security-extension

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="enterprise-security-extension.xsd">

<jwt-realm>

<name>master</name>

<jwks-endpoint>http://keycloak:8083/auth/realms/master/protocol/openid-connect/certs</jwks-endpoint>

<introspection-endpoint>http://keycloak:8083/auth/realms/master/protocol/openid-connect/token/introspect</introspection-endpoint>

<simple-auth>

<username>hivemq</username>

<password> -- Secret aus Keycloak von vorher -- </password>

</simple-auth>

</configuration>

</jwt-realm>

</realms>

<listener-pipeline name="keycloak-pipeline" listener="ALL">

<jwt-authentication-manager>

<realm>master</realm>

<jwt-validation>

<enable-introspection>true</enable-introspection>

<reserved-claims>

<sub>${mqtt-username}</sub>

</reserved-claims>

</jwt-validation>

</jwt-authentication-manager>

<allow-all-authorization-manager/> <!-- Wir prüfen die Berechtigungen nicht tiefer, wer ein valides Token besitzt, darf alles tun.

Alternativ sql-authentication-manager, dieser bezieht die Berechtigungen aus DB -->

</listener-pipeline>

</pipelines>

</enterprise-security-extension>

HiveMQ bietet schon direkt einfache Dockerimages an, da wir dem Image aber noch eine eigene Konfiguration und die Enterprise-Security-Extension anfügen möchten, mussten wir das Basisimage erweitern:

FROM hivemq/hivemq4

RUN curl -L https://www.hivemq.com/releases/extensions/hivemq-enterprise-security-extension-1.4.0.zip -o /opt/hivemq-ese.zip \
    && unzip /opt/hivemq-ese.zip -d /opt/hivemq/extensions/ \
    && rm /opt/hivemq-ese.zip

COPY config.xml /opt/hivemq/conf/config.xml
COPY enterprise-security-extension.xml /opt/hivemq/extensions/hivemq-enterprise-security-extension/enterprise-security-extension.xml

FROM hivemq/hivemq4

RUN curl -L https://www.hivemq.com/releases/extensions/hivemq-enterprise-security-extension-1.4.0.zip -o /opt/hivemq-ese.zip \

&& unzip /opt/hivemq-ese.zip -d /opt/hivemq/extensions/ \

&& rm /opt/hivemq-ese.zip

COPY config.xml /opt/hivemq/conf/config.xml

COPY enterprise-security-extension.xml /opt/hivemq/extensions/hivemq-enterprise-security-extension/enterprise-security-extension.xml

Webapp

In der Angular-Webapp läuft letztendlich alles zusammen:

1. Die Authentifizierung des Benutzers: Dafür nutzen wir das freie angular-oauth2-oidc Modul welches einen Großteil des Login-Prozesses übernimmt und nach dem sogenannten Implicit Flow abläuft. Dieser funktioniert grob beschrieben wie folgt: Wenn der Benutzer auf die Webapp zugreift und noch nicht eingeloggt ist, wird er automatisch auf die Loginseite des Keycloaks umgeleitet. Nachdem er sich dort erfolgreich authentifiziert hat, wird er zurück auf die Webapp geleitet. Die Token werden dabei in der URL transportiert, so dass sie die Webapp auswerten und benutzen kann. Dieser Schritt lässt sich noch zusätzlich mittels PKCE absichern (Blogpost).

2. Die Verbindung zu unserem MQTT-Broker: Hierfür kommt ngx-mqtt zum Zuge, dieses Module „umhüllt“ MQTT.js, so dass die für Angular typischen Observables genutzt werden können. Die Anmeldedaten der MQTT-Verbindung werden dabei von den zuvor empfangenen Token übernommen.

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {
  private mqttService?: MqttService;
  lightStatus = 'ON';

  readonly lightStatusTopic = 'light';

  constructor(private oauthService: OAuthService) {
  }

  async ngOnInit() {
    const authConfig: AuthConfig = {
      issuer: 'http://keycloak:8083/auth/realms/master',
      redirectUri: window.location.origin,
      clientId: 'frontend',
      scope: 'mqtt',
    };
    this.oauthService.configure(authConfig);
    this.oauthService.tokenValidationHandler = new JwksValidationHandler();
    await this.oauthService.loadDiscoveryDocumentAndTryLogin();
    if (this.oauthService.hasValidAccessToken()) {
      await this.connectMQTT();
    } else {
      this.oauthService.initImplicitFlow();
    }
  }

  private async connectMQTT() {
    this.mqttService = new MqttService({
      url: 'ws://localhost:8081/mqtt',
      username: this.oauthService.getIdentityClaims()['sub'],
      password: this.oauthService.getAccessToken()
    });

    this.mqttService.observe(this.lightStatusTopic).subscribe(message => {
      this.lightStatus = message.payload.toString();
    });
  }

  private changeLightStatus(newStatus: string) {
    this.mqttService.publish(this.lightStatusTopic, newStatus, {qos: 0, retain: true}).subscribe();
  }
}

@Component({

selector: 'app-root',

templateUrl: './app.component.html',

styleUrls: ['./app.component.css']

})

export class AppComponent implements OnInit {

private mqttService?: MqttService;

lightStatus = 'ON';

readonly lightStatusTopic = 'light';

constructor(private oauthService: OAuthService) {

}

async ngOnInit() {

const authConfig: AuthConfig = {

issuer: 'http://keycloak:8083/auth/realms/master',

redirectUri: window.location.origin,

clientId: 'frontend',

scope: 'mqtt',

};

this.oauthService.configure(authConfig);

this.oauthService.tokenValidationHandler = new JwksValidationHandler();

await this.oauthService.loadDiscoveryDocumentAndTryLogin();

if (this.oauthService.hasValidAccessToken()) {

await this.connectMQTT();

} else {

this.oauthService.initImplicitFlow();

}

private async connectMQTT() {

this.mqttService = new MqttService({

url: 'ws://localhost:8081/mqtt',

username: this.oauthService.getIdentityClaims()['sub'],

password: this.oauthService.getAccessToken()

});

this.mqttService.observe(this.lightStatusTopic).subscribe(message => {

this.lightStatus = message.payload.toString();

});

}

private changeLightStatus(newStatus: string) {

this.mqttService.publish(this.lightStatusTopic, newStatus, {qos: 0, retain: true}).subscribe();

}

Wenn nun alle Dienste gestartet werden, sieht alles zusammen nachdem Login bei uns wie folgt aus:

Webapp in zwei verschiedenen, über MQTT synchronisierten Browsern und zusätzlich ein Mockdevice welches die Änderungen auf der Konsole anzeigt

Fazit

Mit den von uns verwendeten Diensten, lies sich innerhalb von kurzer Zeit und mit wenig Aufwand, eine Webapp an einen MQTT-Broker anbinden. Dies ermöglicht uns eine schnelle Umsetzung vieler IoT Use Cases, aber auch die einfache Synchronisierung mehrere Browser von unterschiedlichen Benutzern, ohne auf IT-Sicherheit verzichten zu müssen.

Zusätzlich sollte noch, um die Integrität und Vertraulichkeit der Nachrichten sicherzustellen, auf jeden Fall TLS als Transportverschlüsselung aktiviert werden, dies ist direkt in HiveMQ, aber auch mittels eines Ingress-Gateways/Proxy möglich.

Je nach Fall muss auch die Zugriffsberechtigungen für einzelne Topics auf dem Broker überprüft werden. Die Enterprise-Security-Extension bietet die Möglichkeit, dies datenbankgestützt zu prüfen.